gravl/.planning/codebase/STRUCTURE.md

Codebase Structure

Analysis Date: 2026-02-15

Directory Layout

gravl/
├── .git/                     # Git repository
├── .planning/
│   └── codebase/             # Analysis documents (this file)
├── agents/                   # AI agent configurations (not active codebase)
│   ├── architect/
│   ├── backend-dev/
│   ├── coach/
│   ├── frontend-dev/
│   ├── nutritionist/
│   └── reviewer/
├── backend/                  # Express.js REST API server
│   ├── src/
│   │   └── index.js          # Main server file (all routes and handlers)
│   ├── package.json          # Backend dependencies
│   ├── Dockerfile            # Docker build config
│   └── node_modules/         # Dependencies (not committed)
├── frontend/                 # React SPA application
│   ├── src/
│   │   ├── main.jsx          # App entry point (routing, providers)
│   │   ├── App.jsx           # Main app shell (view routing)
│   │   ├── index.css         # Global styles
│   │   ├── App.css           # App component styles
│   │   ├── pages/            # Full-page components (views)
│   │   ├── components/       # Reusable components
│   │   └── context/          # React Context providers
│   ├── index.html            # HTML template
│   ├── vite.config.js        # Vite build configuration
│   ├── package.json          # Frontend dependencies
│   ├── Dockerfile            # Docker build config
│   └── node_modules/         # Dependencies (not committed)
├── db/                       # Database schema and initialization
│   └── init.sql              # PostgreSQL schema definition
├── docker/                   # Docker-related files
├── docker-compose.yml        # Multi-container orchestration
├── README.md                 # Project overview
├── CLAUDE.md                 # LLM context file
└── TODO.md                   # Project tasks and notes

Directory Purposes

backend/src/:

• Purpose: Backend application code
• Contains: Single Express server file with all routes, middleware, and database handlers
• Key files: index.js (14,361 lines, monolithic backend)

frontend/src/:

• Purpose: Frontend application source code
• Contains: React component files, styling, and global state management
• Key files: App.jsx, main.jsx, page components, AuthContext

frontend/src/pages/:

• Purpose: Full-page/route components (views)
• Contains: 8 page components handling entire view logic
• Key files:
  • Dashboard.jsx - Main view showing program and scheduled workout
  • WorkoutPage.jsx - Active workout tracking interface
  • ProfilePage.jsx - User profile and measurements
  • ProgressPage.jsx - Progress tracking and statistics
  • LoginPage.jsx - Authentication entry
  • RegisterPage.jsx - Account creation
  • OnboardingWizard.jsx - Initial profile setup
  • WorkoutSelectPage.jsx - Program/day selection

frontend/src/components/:

• Purpose: Reusable UI components
• Contains: Shared UI building blocks
• Key files: Icons.jsx - Icon system and icon name mapping

frontend/src/context/:

• Purpose: React Context providers for global state
• Contains: Authentication state and session management
• Key files: AuthContext.jsx - User login, registration, profile updates, token management

db/:

• Purpose: Database schema and initialization
• Contains: SQL scripts for schema creation and seed data
• Key files: init.sql - Creates 8 tables, indexes, and inserts PPL program template

docker/:

• Purpose: Docker-related configuration (currently minimal)
• Contains: Likely Dockerfile templates or configuration

Key File Locations

Entry Points:

• frontend/index.html - HTML template that loads React app
• frontend/src/main.jsx - React bootstrap, BrowserRouter setup, routing definitions
• frontend/src/App.jsx - Main app shell, view routing, workout state management
• backend/src/index.js - Express server initialization, all API routes

Configuration:

• frontend/vite.config.js - Vite build config, dev proxy setup
• frontend/package.json - React, React Router, Vite dependencies
• backend/package.json - Express, PostgreSQL driver, JWT, bcrypt dependencies
• docker-compose.yml - Service definitions, networking, Traefik routing labels

Core Logic:

• frontend/src/context/AuthContext.jsx - Authentication and session management
• backend/src/index.js - All API endpoints, auth middleware, database queries
• db/init.sql - Database schema and initial data

Styling:

• frontend/src/index.css - Global styles, CSS variables, base components
• frontend/src/App.css - Application layout styles
• frontend/src/pages/*.jsx - Inline inline className attributes (CSS-in-JS via CSS class selectors)

Naming Conventions

Files:

• Pages: PascalCase with "Page" suffix (e.g., LoginPage.jsx, WorkoutPage.jsx)
• Components: PascalCase (e.g., Icons.jsx)
• Context: PascalCase with "Context" suffix (e.g., AuthContext.jsx)
• Backend routes: Lowercase with slashes (e.g., /api/auth/login, /api/user/profile)
• Database tables: Lowercase with underscores (e.g., workout_logs, program_exercises)

Directories:

• Page directory: pages/ (plural)
• Component directory: components/ (plural)
• Context directory: context/ (singular, convention)
• Backend: src/ (single index.js file, no subdirectories)

Functions:

• React components: PascalCase (e.g., function Dashboard())
• Hooks/helpers: camelCase (e.g., fetchProgram(), getCoachGreeting(), getMuscleGroups())
• Constants: camelCase (e.g., API_URL, weekdays, warmupExercises)
• Middleware: camelCase (e.g., authMiddleware)

Variables:

• State: camelCase (e.g., user, loading, selectedDay)
• Props: camelCase (e.g., onStartWorkout, onNavigate)
• API endpoints: Lowercase kebab-case in URLs, snake_case in query parameters and JSON bodies

Types/Database:

• Columns: snake_case (e.g., password_hash, onboarding_complete, program_exercise_id)
• Tables: Lowercase plural (e.g., users, programs, workout_logs)
• Foreign keys: Follow pattern {table_id} (e.g., user_id, program_id)

Where to Add New Code

New Feature (e.g., new page/view):

• Primary code: frontend/src/pages/{FeatureName}Page.jsx
• Styling: Inline CSS class names in JSX or extend App.css
• API calls: Direct fetch in component useEffect hooks, passing API_URL from page file
• Routing: Add Route to frontend/src/main.jsx with Route path and component
• If requires auth: Wrap in <ProtectedRoute> wrapper in main.jsx
• If requires context: Use useAuth() hook from AuthContext

New API Endpoint (backend):

• Location: Add route handler in backend/src/index.js
• Pattern: Use app.get(), app.post(), app.put() with path and handler function
• Database: Use pool.query() for PostgreSQL queries with parameterized queries ($1, $2, etc.)
• Auth: Add authMiddleware parameter if endpoint requires authentication
• Response: Return res.json() with data or error object
• Error handling: Wrap in try-catch, return appropriate status codes (400, 401, 404, 500)

New Component:

• Location: frontend/src/components/{ComponentName}.jsx
• Export: Default export or named export function component
• Props: Accept props for reusability, avoid direct API calls
• Integration: Import into pages or other components as needed

New Database Table/Schema Change:

• Location: db/init.sql
• Pattern: Add CREATE TABLE statement with proper data types and constraints
• Relations: Use FOREIGN KEY references and ON DELETE CASCADE
• Indexes: Add indexes for frequently queried columns (user_id, date, etc.)
• Seed data: Use INSERT statements with ON CONFLICT DO NOTHING
• Application: Changes apply on container restart (init.sql runs every startup)

Utilities/Helpers:

• Location: Keep in page file if only used there, or create in frontend/src/utils/ if reused
• Pattern: Export as named functions (no separate utils directory currently exists)
• Examples: getCoachGreeting(), getMuscleGroups(), getWeekStart() are defined in pages

Authentication/State:

• Location: Extend frontend/src/context/AuthContext.jsx if global
• Location: Add to page component state with useState if local to page
• Pattern: Use useAuth() hook for auth context, create custom hooks if reusable state pattern emerges

Special Directories

node_modules/:

• Purpose: Installed npm dependencies
• Generated: Yes (by npm install)
• Committed: No (.gitignore)
• Notes: Frontend and backend have separate node_modules directories

.git/:

• Purpose: Git version control repository
• Generated: Yes (git init)
• Committed: N/A (git internal)

.planning/codebase/:

• Purpose: Architecture and codebase analysis documents
• Generated: Yes (by mapping tools)
• Committed: Yes (for orchestrator reference)
• Contains: ARCHITECTURE.md, STRUCTURE.md, and other analysis documents

agents/:

• Purpose: Agent configuration (not part of active codebase)
• Generated: Yes (from setup)
• Committed: Yes
• Notes: These are orchestrator definitions, not part of the running application

---

Structure analysis: 2026-02-15