docs: map existing codebase
This commit is contained in:
@@ -0,0 +1,216 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user