gravl/.planning/codebase/CONCERNS.md

Codebase Concerns

Analysis Date: 2026-02-15

Tech Debt

Hardcoded Program ID in Backend:

• Issue: Multiple API endpoints hardcode program_id = 1 in queries, preventing multi-program support
• Files: backend/src/index.js (lines 27, 198, 386, 410)
• Impact: Cannot support multiple training programs; system is locked to single PPL program. Future features requiring program selection will require significant refactoring
• Fix approach: Add program_id parameter to endpoints; refactor to accept program ID from request or user preferences

Hardcoded User ID Default:

• Issue: Backend defaults to user_id = 1 when not provided; frontend also uses fallback user?.id || 1
• Files: backend/src/index.js (line 290), frontend/src/App.jsx (line 21), frontend/src/pages/ProfilePage.jsx (lines 25-27, 48)
• Impact: Multi-user isolation broken; all users can see/modify each other's data if API auth fails. Critical security concern
• Fix approach: Remove all fallback user IDs; enforce auth token verification; validate user ownership on all endpoints

Single Backend File Architecture:

• Issue: All 425 lines of API logic in one file (backend/src/index.js); no separation into routes, controllers, middleware
• Files: backend/src/index.js
• Impact: Difficult to maintain, test, or extend. Mixed concerns (auth, database, business logic) in same file. No clear patterns for new endpoints
• Fix approach: Refactor into: routes/, controllers/, middleware/, services/ directories

No Request Validation:

• Issue: No input validation on any API endpoints; accepts any data and passes to database
• Files: backend/src/index.js (all POST/PUT routes: lines 35-50, 103-118, 121-136, 153-168, 299-329)
• Impact: SQL injection risk (mitigated by parameterized queries but semantic validation missing), malformed data in database, inconsistent state
• Fix approach: Add validation library (e.g., joi, zod); validate types, ranges, required fields before database operations

Weak Default JWT Secret:

• Issue: JWT secret defaults to plain string 'gravl-secret-key-change-in-production' if env var not set
• Files: backend/src/index.js (line 9)
• Impact: If deployment forgets to set JWT_SECRET env var, all tokens can be forged. Auth completely broken in that scenario
• Fix approach: Require JWT_SECRET as mandatory env var; fail at startup if not set; remove default

Exposed Database Password in Docker Compose:

• Issue: Database password hardcoded in plaintext in docker-compose.yml
• Files: docker-compose.yml (line 12: DB_PASSWORD=homelab_postgres_2026)
• Impact: Secret visible in git history and version control. Deployed as plain text to running containers
• Fix approach: Use .env file (gitignored) with env var substitution; never commit secrets

Hardcoded Database Connection Defaults:

• Issue: Database credentials have weak defaults if env vars missing
• Files: backend/src/index.js (lines 11-17)
• Impact: If env vars not set, connects with default user/password/database
• Fix approach: Require critical env vars (DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME) as mandatory at startup

No Error Handling for Database Failures:

• Issue: Database errors logged to console but no graceful degradation or retry logic
• Files: backend/src/index.js (lines 46-50, 64-67, 97-100, 114-117, 132-135, 164-167, 189-191, 227-230, 245-248, 275-278, 292-295, 325-328, 379-382, 416-419)
• Impact: Client gets generic "Database error" message; no way to debug; connection pool exhaustion not handled
• Fix approach: Add structured error logging; implement connection retry logic; differentiate error messages (auth vs DB vs validation)

Vague Error Messages:

• Issue: Many endpoints return generic { error: 'Server error' } without details
• Files: backend/src/index.js (lines 49, 66, 116, 134, 166, 191, 229, 248, 278, 295, 328, 381, 418)
• Impact: Frontend cannot distinguish between different failure modes; users see unhelpful messages; debugging impossible
• Fix approach: Use structured error codes (e.g., ERR_EMAIL_EXISTS, ERR_INVALID_CREDENTIALS, ERR_DB_UNAVAILABLE)

Known Bugs

User ID Fallback Breaks Multi-User:

• Symptoms: Any endpoint called without proper auth gets user ID 1; all data accessible to wrong users
• Files: backend/src/index.js (line 290: user_id || 1)
• Trigger: Call /api/logs/last/...?program_exercise_id=X without user_id parameter, or auth fails silently
• Workaround: Frontend always provides user ID; but if auth token expires mid-session, falls back to user 1

Progression Calculation Assumes User Context:

• Symptoms: /api/progression/:id endpoint without auth header returns data for user_id=1, not current user
• Files: backend/src/index.js (line 334: user_id || 1)
• Trigger: Make unauthenticated request to progression endpoint
• Workaround: Frontend includes user_id in query param, but no validation that it matches auth token

Missing Auth Validation on Read Endpoints:

• Symptoms: /api/logs, /api/logs/last/..., /api/progression/... do not require auth; anyone can see anyone's data
• Files: backend/src/index.js (lines 252-279, 282-296, 332-383 — none have authMiddleware)
• Trigger: Unauthenticated request to any of these endpoints returns full data
• Workaround: None; endpoint is truly public

Profile Fetch Endpoints Bypass Auth:

• Symptoms: /api/user/profile GET and other profile endpoints sometimes called without token
• Files: frontend/src/pages/ProfilePage.jsx (lines 25-27 make calls with optional header)
• Trigger: Token expires or not in localStorage; frontend still tries to fetch profile
• Workaround: Redirect on 401, but data may be partially loaded

Onboarding Does Not Validate Strength Input:

• Symptoms: Can enter non-numeric strength values; API accepts and stores as invalid data
• Files: frontend/src/pages/OnboardingWizard.jsx (lines 150-153); backend/src/index.js (no validation)
• Trigger: Enter "abc" in 1RM field; submit saves to database
• Workaround: None; data is corrupted

Security Considerations

Authentication Not Required on Data Endpoints:

• Risk: Public endpoints /api/logs, /api/progression/..., /api/logs/last/... expose all user workout data without auth
• Files: backend/src/index.js (routes at lines 252, 282, 332)
• Current mitigation: None; these routes are public
• Recommendations: Add authMiddleware to all endpoints that return user data; validate user_id from request matches decoded token

User ID Not Validated on Update Operations:

• Risk: Client sends PUT request with any user_id; no validation that it matches auth token
• Files: backend/src/index.js (lines 103, 121, 153, 299)
• Current mitigation: Database constraint on user_id, but not enforced at API level
• Recommendations: Extract user_id from JWT token (req.user.id); never accept from request body; validate ownership

Password Hashing Strength Acceptable But Not Tested:

• Risk: Uses bcryptjs with rounds=10 (line 39); no test for hash strength
• Files: backend/src/index.js (line 39)
• Current mitigation: bcryptjs with 10 rounds is secure
• Recommendations: Increase to 12+ rounds; add integration test for password hashing

JWT Token Expiry Too Long:

• Risk: 30-day token expiry is long; stolen token has extended window
• Files: backend/src/index.js (lines 44, 61)
• Current mitigation: Token stored in localStorage; vulnerable to XSS
• Recommendations: Reduce to 1-7 days; implement refresh token rotation; consider httpOnly cookies

No CORS Validation:

• Risk: CORS enabled for all origins (app.use(cors()))
• Files: backend/src/index.js (line 19)
• Current mitigation: None; frontend is localhost during dev, but prod deployment may not restrict
• Recommendations: Add whitelist: cors({ origin: process.env.FRONTEND_URL })

Database Connection Not SSL in Docker:

• Risk: PostgreSQL connection from Docker unencrypted if over network
• Files: backend/src/index.js (lines 11-17); docker-compose.yml
• Current mitigation: On internal homelab network, but not encrypted
• Recommendations: Add ssl: true to pool config if connecting over untrusted network

Performance Bottlenecks

N+1 Query Problem in Program Endpoints:

• Problem: /api/programs/:id loads program, then for each day, joins exercises separately
• Files: backend/src/index.js (lines 196-231)
• Cause: Single query with complex LEFT JOINs and json_agg; works but could be optimized with batching
• Improvement path: Already optimized with single query; no issue here. Performance is acceptable

No Database Indexes on Common Queries:

• Problem: workout_logs queries filter by (user_id, date, program_exercise_id) but indexes only on two columns
• Files: db/init.sql (line 77); backend/src/index.js (lines 252-279)
• Cause: Missing composite index on (user_id, date) and separate on program_exercise_id
• Improvement path: Add CREATE INDEX idx_workout_logs_user_date_exercise ON workout_logs(user_id, date, program_exercise_id)

Measurements Fetch Not Limited:

• Problem: /api/user/measurements returns up to 100 rows without pagination
• Files: backend/src/index.js (line 142)
• Cause: LIMIT 100 hardcoded; if user has years of data, transfers unnecessary payload
• Improvement path: Add limit and offset query params; default to last 30 records

Strength History Not Limited:

• Problem: /api/user/strength also LIMIT 100
• Files: backend/src/index.js (line 174)
• Cause: Same as measurements
• Improvement path: Add pagination; default to last 12 records (1 year monthly checks)

Frontend Fetches All Logs for All Exercises at Once:

• Problem: App.jsx fetchLogs() makes one request per exercise (loop)
• Files: frontend/src/App.jsx (lines 35-51)
• Cause: Not batched; if 6 exercises, makes 6 API calls sequentially
• Improvement path: Batch into single endpoint; return all day's logs in one query

Progression Calculation Fetches Last 10 Logs Per Request:

• Problem: /api/progression/:id fetches last 10 logs for every exercise opened
• Files: backend/src/index.js (line 354)
• Cause: Called on component expand; if user expands 6 exercises, 6 queries
• Improvement path: Batch progression calculations; include in WorkoutPage's initial fetch

Fragile Areas

AuthContext Token Refresh Not Automatic:

• Files: frontend/src/context/AuthContext.jsx
• Why fragile: 30-day token expiry means users logged in for <30d get sudden 401. No refresh token mechanism. Token stored in localStorage (XSS vulnerable)
• Safe modification: Add refresh token endpoint; implement automatic refresh-before-expiry; consider httpOnly cookies
• Test coverage: No tests; AuthContext has no test file

Profile Fetch Without Error Boundaries:

• Files: frontend/src/pages/ProfilePage.jsx (lines 22-42)
• Why fragile: Fetch errors caught in console but no UI feedback; Promise.all() fails if one fetch fails, but all three fetches (profile, measurements, strength) are separate queries
• Safe modification: Wrap each fetch in try-catch separately; show partial data if some fail; add error toast
• Test coverage: No tests

Onboarding State Not Persisted During Request:

• Files: frontend/src/pages/OnboardingWizard.jsx (lines 24-72)
• Why fragile: If user fills all 4 steps and network fails during save, form clears but data lost. No draft save
• Safe modification: Auto-save to localStorage after each step; restore on remount
• Test coverage: No tests; body fat calculation not tested

Warmup Completion State Lost on Navigation:

• Files: frontend/src/pages/WorkoutPage.jsx (lines 51-53, 79-87)
• Why fragile: completedWarmups is local state in component; navigating away loses progress. No persistence
• Safe modification: Save to localStorage keyed by date+day
• Test coverage: No tests

Exercise Progression Display Race Condition:

• Files: frontend/src/pages/WorkoutPage.jsx (lines 48-67)
• Why fragile: loadProgressions() called in useEffect with [day] dependency; if day changes rapidly, multiple requests in flight; setState after unmount possible
• Safe modification: Add cleanup function; abort controller for fetch; cache by day ID
• Test coverage: No tests

Database Schema Missing User FK in Measurements:

• Files: db/init.sql (lines 64-74)
• Why fragile: user_measurements table has no explicit FOREIGN KEY to users table; can create orphaned records; cascading delete not enforced
• Safe modification: Add user_id INTEGER REFERENCES users(id) ON DELETE CASCADE NOT NULL
• Test coverage: Schema not tested

Hardcoded Warmup Exercises Not Database-Driven:

• Files: frontend/src/pages/WorkoutPage.jsx (lines 5-35)
• Why fragile: Warmup data hardcoded in component; if new muscle group added to exercises, no warmups for it; mapping is manual and fragile
• Safe modification: Move to database table warmup_exercises(muscle_group, name, duration, type); fetch on page load
• Test coverage: No tests; mapping logic untested

Scaling Limits

Single Program Per User:

• Current capacity: System assumes all users follow program_id=1
• Limit: Cannot support multiple programs or user switching between programs
• Scaling path: Refactor endpoints to accept program_id; add user_programs join table; allow user to select active program

No Pagination on History Endpoints:

• Current capacity: /api/user/measurements returns LIMIT 100; /api/user/strength returns LIMIT 100
• Limit: If user has >100 measurements (100+ days of data), response grows indefinitely
• Scaling path: Implement cursor-based pagination; return 20-30 records per page; add date range filters

Database Connection Pool Not Configured:

• Current capacity: pg module defaults to pool size 10
• Limit: 10 concurrent connections; 11th request queues
• Scaling path: Add explicit pool configuration: max: 20, min: 5 adjusted per load; monitor with pg_stat_activity

Logs Stored Flat Without Aggregate Summary:

• Current capacity: Every set logged individually; querying 100 workouts × 6 exercises × 3 sets = 1800 rows
• Limit: As user history grows, workout fetches slow down
• Scaling path: Add workout_sessions table with aggregate stats; denormalize common queries

Frontend Loads Entire Program Structure:

• Current capacity: /api/programs/:id returns all days + all exercises in one response
• Limit: With 12+ exercises per day, response grows; not a problem now but scales poorly
• Scaling path: Lazy-load exercises per day; separate endpoint for day details; cache aggressively

Dependencies at Risk

Express 4.x Minor Versions:

• Risk: No automatic security updates; express vulnerabilities not patched unless manually updated
• Impact: Known CVEs in middleware could be exploited
• Migration plan: Upgrade to Express 5.x (breaking changes); or add npm audit fix to CI pipeline

bcryptjs No Longer Maintained:

• Risk: bcryptjs is unmaintained library; use native Node.js crypto instead
• Impact: Security bugs in bcryptjs won't be fixed; but practical risk is low (bcrypt algorithm is solid)
• Migration plan: Switch to bcrypt (native binding) or Node.js crypto.scrypt() + built-in functions

jsonwebtoken Known Vulns:

• Risk: jsonwebtoken has history of algorithm confusion vulnerabilities (prior versions)
• Impact: Current version 9.0.2 (in package.json) is recent; likely patched
• Migration plan: Keep up with minor/patch updates; add npm audit to CI

pg Library Version:

• Risk: pg 8.11.3 is from 2023; no known critical issues but check advisories
• Impact: Low; PostgreSQL driver is stable
• Migration plan: Keep updated; monitor npm advisories

Missing Critical Features

No Input Sanitization:

• Problem: User inputs not sanitized before database storage; e.g., XSS in exercise names, injection in auth fields
• Blocks: Any user-generated content features (notes, comments); social features
• Fix approach: Add input sanitization library (e.g., DOMPurify for frontend, xss for backend); validate at both layers

No Rate Limiting:

• Problem: No rate limits on auth endpoints; brute force attack possible on /api/auth/login
• Blocks: Public deployment; production security
• Fix approach: Add express-rate-limit middleware; 5 attempts per 15 min per IP

No Audit Logging:

• Problem: No record of who did what when; can't detect unauthorized access or data changes
• Blocks: Compliance requirements; forensics
• Fix approach: Add audit_logs table; log all create/update/delete with user_id, timestamp, action

No Soft Deletes:

• Problem: No way to recover deleted data; hard deletes cascade immediately
• Blocks: Undo features; data recovery
• Fix approach: Add deleted_at column to tables; use soft deletes; implement undelete mechanism

No API Versioning:

• Problem: No v1, v2 paths; breaking changes would affect all clients
• Blocks: Safe API evolution
• Fix approach: Add /api/v1/... prefix; maintain backward compatibility when possible

Test Coverage Gaps

No Backend Tests:

• What's not tested: All 425 lines of backend/src/index.js have zero test coverage
• Files: backend/src/index.js
• Risk: Auth logic not verified; SQL injection prevention untested; progression calculation not validated; error paths not covered
• Priority: High

No Frontend Unit Tests:

• What's not tested: No Jest/Vitest config; components not tested
• Files: frontend/src/**/*.jsx (all files)
• Risk: UI bugs not caught; hooks logic untested; state transitions not verified
• Priority: High

No Integration Tests:

• What's not tested: API-to-database flow untested; full workout logging flow untested
• Risk: Database schema changes break endpoints; race conditions in concurrent requests not caught
• Priority: Medium

No E2E Tests:

• What's not tested: User flows untested (register → onboard → log workout → progress)
• Risk: Broken onboarding, broken login, navigation issues in production not caught
• Priority: Medium

Auth Logic Not Tested:

• What's not tested: Token verification, expiry, malformed tokens, missing auth headers
• Files: backend/src/index.js (lines 22-29); frontend/src/context/AuthContext.jsx
• Risk: Auth bypass vulnerabilities not detected
• Priority: Critical

Progression Calculation Not Tested:

• What's not tested: Algorithm for suggesting weight increases
• Files: backend/src/index.js (lines 332-383)
• Risk: Incorrect progression logic goes unnoticed; users stay on same weight or jump too much
• Priority: High

Database Schema Not Validated:

• What's not tested: Foreign key constraints, cascading deletes, data types
• Files: db/init.sql
• Risk: Invalid data created; orphaned records; type mismatches
• Priority: Medium

---

Concerns audit: 2026-02-15