# Architecture

**Analysis Date:** 2026-02-15

## Pattern Overview

**Overall:** Monolithic multi-tier architecture with separated frontend and backend services.

**Key Characteristics:**
- Frontend: Single-Page Application (SPA) with React + React Router
- Backend: Express.js REST API with direct database queries
- Database: PostgreSQL with relational schema
- State Management: React Context API for authentication, local component state for page-level data
- Communication: HTTP/JSON via Fetch API with Bearer token authentication
- Deployment: Containerized (Docker) with Traefik reverse proxy routing

## Layers

**Presentation Layer (Frontend):**
- Purpose: Render UI, handle user interactions, manage local state and navigation
- Location: `/workspace/gravl/frontend/src/`
- Contains: React pages, components, context providers, CSS styling
- Depends on: React, React Router, AuthContext, backend API endpoints
- Used by: Browser clients

**Application/Page Layer (Frontend):**
- Purpose: Manage view logic, fetch data, orchestrate navigation between different views
- Location: `/workspace/gravl/frontend/src/pages/`
- Contains: Full page components (Dashboard, WorkoutPage, ProfilePage, ProgressPage, LoginPage, RegisterPage, OnboardingWizard, WorkoutSelectPage)
- Depends on: AuthContext, Icon components, API calls via fetch
- Used by: App.jsx routing logic

**Context Layer (Frontend):**
- Purpose: Provide global authentication state and user session management
- Location: `/workspace/gravl/frontend/src/context/AuthContext.jsx`
- Contains: Auth state, login/register/logout functions, token management, localStorage integration
- Depends on: React hooks, backend authentication endpoints
- Used by: All protected pages and components

**API/REST Layer (Backend):**
- Purpose: Handle HTTP requests, validate input, manage authentication, route requests to data layer
- Location: `/workspace/gravl/backend/src/index.js`
- Contains: Express routes for auth, user profile, programs, exercises, logs, progression
- Depends on: PostgreSQL connection, JWT verification, bcrypt password hashing
- Used by: Frontend via HTTP requests

**Data Layer (Backend):**
- Purpose: Execute queries against PostgreSQL database
- Location: Database queries within `/workspace/gravl/backend/src/index.js` using pg Pool
- Contains: User management, program/day/exercise definitions, workout logs, measurements, strength records
- Depends on: PostgreSQL driver (pg)
- Used by: API layer for all data operations

**Database Layer:**
- Purpose: Persist application data
- Location: `/workspace/gravl/db/init.sql` (schema definition)
- Contains: 7 tables (users, programs, program_days, exercises, program_exercises, workout_logs, user_measurements, user_strength)
- Depends on: PostgreSQL engine
- Used by: Backend data layer

## Data Flow

**User Registration/Login Flow:**

1. User enters credentials on RegisterPage or LoginPage
2. Page calls `useAuth().register()` or `useAuth().login()` from AuthContext
3. AuthContext makes POST to `/api/auth/register` or `/api/auth/login`
4. Backend validates credentials (register: email uniqueness + hash password; login: password verification)
5. Backend returns JWT token and user object
6. AuthContext stores token in localStorage and sets user state
7. Navigation redirects to `/onboarding` (incomplete) or `/` (complete)

**Onboarding Flow:**

1. User completes OnboardingWizard with profile data (gender, age, experience, goal, measurements, strength)
2. Wizard calls `useAuth().updateProfile()` with profile data
3. Backend updates users table and related measurement/strength tables
4. Sets `onboarding_complete = true`
5. User navigated to Dashboard

**Workout/Exercise Flow:**

1. Dashboard displays program days and selected day's workout
2. User clicks workout day, `onStartWorkout()` called
3. App.jsx calls `fetchProgram()` to load program with all days/exercises
4. App.jsx calls `fetchLogs()` to fetch existing workout logs for that day
5. WorkoutPage displayed with exercises and weight/rep input fields
6. User enters weight/reps and clicks "Log Set"
7. `logSet()` calls POST `/api/logs` with exercise_id, weight, reps, date, set_number
8. Backend checks if log exists for that set (update) or creates new (insert)
9. Response updates local logs state
10. WorkoutPage re-renders with updated data

**Progression Calculation Flow:**

1. WorkoutPage calls `fetchProgression()` for each exercise
2. Backend fetches last workout for that exercise (last 10 logs, completed only)
3. Analyzes if all sets hit max_reps
4. Returns suggestedWeight (same weight or +2.5kg if maxed out)
5. Frontend displays suggestion in workout interface

**Profile/Measurements Flow:**

1. User navigates to ProfilePage
2. Page calls parallel fetches: `/api/user/profile`, `/api/user/measurements`, `/api/user/strength`
3. Backend joins latest measurements and strength records with user profile
4. Page displays current profile and can add new measurements or strength records
5. User saves changes → updates user profile state in AuthContext

**State Management:**
- **Global state:** User session, authentication token (AuthContext in localStorage)
- **Page-level state:** Program, logs, current view, selected day (App.jsx state)
- **Component-level state:** Form inputs, editing mode, expanded sections (individual page components)
- **No shared state management library:** Direct React Context + local useState

## Key Abstractions

**AuthContext:**
- Purpose: Centralized authentication and user session management
- Examples: `useAuth()` hook returns { user, token, loading, register, login, logout, updateProfile, refreshProfile }
- Pattern: React Context + custom hook for easy access from any component

**Page Components:**
- Purpose: Encapsulate view logic, form handling, and local data fetching
- Examples: `Dashboard.jsx`, `WorkoutPage.jsx`, `ProfilePage.jsx`
- Pattern: Functional components with useState/useEffect, direct API calls via fetch

**Program/Exercise Model:**
- Purpose: Represent training structure in database and API
- Structure: Program > Days > Exercises (program_exercises join table) > Logs (user workout records)
- Pattern: Nested JSON responses from `/api/programs/:id` endpoint

**Workout Log:**
- Purpose: Record individual set performance (weight, reps, completion status)
- Examples: `workout_logs` table with user_id, program_exercise_id, date, set_number, weight, reps, completed
- Pattern: Upsert logic (update if exists, insert if new)

## Entry Points

**Frontend Entry:**
- Location: `frontend/index.html` → `src/main.jsx` → `src/App.jsx`
- Triggers: Browser loads gravl.homelab.local
- Responsibilities:
  1. Bootstrap React app with BrowserRouter and AuthProvider
  2. Define route structure (auth routes vs. protected routes)
  3. Initialize token from localStorage and verify session
  4. Render main App component

**Backend Entry:**
- Location: `backend/src/index.js`
- Triggers: Docker container startup (`npm start` → `node src/index.js`)
- Responsibilities:
  1. Initialize Express app and PostgreSQL connection pool
  2. Mount CORS and JSON middleware
  3. Define all API routes with request/response handling
  4. Listen on port 3001
  5. Database queries executed inline within route handlers

**Auth-Protected Routes:**
- ProtectedRoute wrapper checks user existence and onboarding status
- Redirects to `/login` if unauthenticated
- Redirects to `/onboarding` if authenticated but onboarding incomplete
- Routes: `/`, `/profile`, `/progress`, `/select-workout`, `/workout`

**Auth Routes:**
- AuthRoute wrapper redirects to `/` or `/onboarding` if already authenticated
- Routes: `/login`, `/register`

## Error Handling

**Strategy:** Try-catch in Express routes returns JSON errors; frontend logs errors and may show error UI

**Patterns:**
- Backend: Catch database/auth errors, return 400/401/500 with JSON error message
- Frontend: Catch fetch errors in async functions, log to console, optionally show in component error state
- Validation: Frontend form validation (required, minLength); backend re-validates email uniqueness
- Auth failures: Return 401 Unauthorized, AuthContext logs user out
- Database errors: Return 500 with generic message (details in server logs only)

## Cross-Cutting Concerns

**Logging:**
- Backend: `console.error()` for exceptions; logs visible in Docker container stdout
- Frontend: `console.error()` for network failures and state issues

**Validation:**
- Frontend: HTML5 form validation (type="email", minLength, required)
- Backend: Email lowercase normalization, null coercion for numeric fields, JWT signature verification

**Authentication:**
- Method: JWT Bearer token in Authorization header
- Token storage: localStorage on browser
- Token validation: `authMiddleware` function checks header and verifies signature
- Token lifetime: 30 days expiration
- Session management: AuthContext refresh on mount, logout clears localStorage and state

**CORS:**
- Enabled globally with `cors()` middleware on all routes
- Frontend proxy configured in Vite for `/api` calls during development
- Docker network configured for service-to-service communication

**Data Integrity:**
- Foreign key constraints in database schema (ON DELETE CASCADE)
- Unique email constraint in users table
- Indexes on frequently queried columns (user_id, date, program_exercise_id)

---

*Architecture analysis: 2026-02-15*