gravl/.planning/codebase/INTEGRATIONS.md

External Integrations

Analysis Date: 2026-02-15

APIs & External Services

None - No external third-party APIs currently integrated.

Data Storage

Databases:

• PostgreSQL (Primary)
  • Connection via pg client library (8.11.3)
  • Environment variables:
    • DB_HOST - Default: postgres (Docker service name)
    • DB_PORT - Default: 5432
    • DB_USER - Default: postgres
    • DB_PASSWORD - Required secret
    • DB_NAME - Default: gravl
  • ORM/Client: pg (node-postgres) - Direct SQL queries, no ORM
  • Initialization: db/init.sql - Schema and seed data
  • Tables: users, programs, program_days, exercises, program_exercises, workout_logs, user_measurements, user_strength

File Storage:

• Local filesystem only - No external file storage service
• Static assets served by Nginx from built frontend dist/ directory

Caching:

• None detected - No Redis, Memcached, or other caching layer

Authentication & Identity

Auth Provider:

• Custom JWT-based authentication
  • Implementation: backend/src/index.js (lines 22-29, 35-68)
  • Token generation: jsonwebtoken 9.0.2
  • Password hashing: bcryptjs 2.4.3
  • Secret: JWT_SECRET environment variable (default: gravl-secret-key-change-in-production)
  • Token expiration: 30 days

Auth Flow:

1. Frontend AuthContext (frontend/src/context/AuthContext.jsx) manages user state
2. User registers or logs in via /api/auth/register or /api/auth/login
3. Backend verifies credentials, generates JWT token
4. Frontend stores token in localStorage as token
5. Subsequent requests include Authorization: Bearer {token} header
6. Backend authMiddleware validates token on protected routes
7. User profile fetched on app load via /api/user/profile

Protected Routes:

• /api/user/profile - GET/PUT (requires auth)
• /api/user/measurements - GET/POST (requires auth)
• /api/user/strength - GET/POST (requires auth)
• /api/logs - GET/POST (no auth check in code - potential security gap)
• /api/progression/:programExerciseId - GET (no auth check - potential security gap)

Public Routes:

• /api/health - Health check endpoint
• /api/auth/register - User registration
• /api/auth/login - User login
• /api/programs - List all programs
• /api/programs/:id - Get program details
• /api/days/:dayId/exercises - Get exercises for a day
• /api/today/:programId - Get workout for day

Frontend-Backend Communication

API Base URL:

• Hardcoded as /api in frontend/src/context/AuthContext.jsx (line 2)
• Development: Proxied by Vite to http://localhost:3001
• Production: Proxied by Nginx to http://gravl-backend:3001

CORS:

• Enabled on backend via cors middleware 2.8.5
• app.use(cors()) in backend/src/index.js (line 19)

HTTP Methods:

• POST /api/auth/register - Register user
• POST /api/auth/login - Login user
• GET /api/user/profile - Get user profile
• PUT /api/user/profile - Update user profile
• POST /api/user/measurements - Add measurements
• GET /api/user/measurements - Get measurement history
• POST /api/user/strength - Add strength record
• GET /api/user/strength - Get strength history
• GET /api/programs - List programs
• GET /api/programs/:id - Get program with days and exercises
• GET /api/days/:dayId/exercises - Get exercises for day
• GET/POST /api/logs - Get/create workout logs
• GET /api/logs/last/:programExerciseId - Get last workout for exercise
• GET /api/progression/:programExerciseId - Calculate suggested weight

Request/Response Format:

• Content-Type: application/json
• Token: Passed in Authorization: Bearer {token} header
• Response: JSON objects

Monitoring & Observability

Error Tracking:

• None detected - No Sentry, LogRocket, or similar

Logs:

• Backend: console.error() for errors (lines 48, 65, 98, 115, 133, 147, 165, 179, 190, 228, 246, 276, 294, 327, 380, 417)
• Frontend: No error tracking integrated
• Example: console.error('Register error:', err) in backend/src/index.js (line 48)

Database Logging:

• None detected - SQL queries not logged

Webhooks & Callbacks

Incoming:

• None detected

Outgoing:

• None detected

Environment Configuration

Required env vars for backend:

• DB_HOST - PostgreSQL hostname
• DB_PORT - PostgreSQL port
• DB_USER - Database user
• DB_PASSWORD - Database password (REQUIRED SECRET)
• DB_NAME - Database name
• JWT_SECRET - JWT signing secret (REQUIRED SECRET for production)
• PORT - Backend port (optional, default 3001)

Secrets location:

• Docker Compose: docker-compose.yml (lines 8-13) - WARNING: Password visible in file
• Backend defaults: backend/src/index.js (lines 9, 14-16)
• Frontend: None (token stored in browser localStorage)

Traefik Integration:

• Frontend exposed via Traefik reverse proxy
• Host: gravl.homelab.local
• HTTP and HTTPS support configured
• Networks: proxy (external), homelab (internal Docker Compose network)

Service Dependencies

Backend Dependencies:

• PostgreSQL (required)
• Traefik proxy (for production routing)

Frontend Dependencies:

• Backend API at /api (required for all authenticated operations)
• Can operate in degraded mode if API is unavailable

---

Integration audit: 2026-02-15