# Workout Planner — File & Folder Reference

_Last updated: February 18, 2026_

## Project Root (`workout-planner/`)

| File | Purpose |
|------|---------|
| `package.json` | Dependencies: Next.js 14, React 18, Prisma, Tailwind, Zod, Lucide, bcryptjs |
| `next.config.js` | Next.js configuration |
| `tailwind.config.ts` | Tailwind setup with zinc color palette |
| `tsconfig.json` | TypeScript config with `@/` path alias |
| `middleware.ts` | Route protection — redirects unauthenticated requests away from `/main/*` |
| `postcss.config.js` | PostCSS for Tailwind |
| `.env` / `.env.local` | Database URL and secrets (not committed) |
| `.env.example` | Template for env vars |
| `Dockerfile` | Container build for production |
| `docker-compose.yml` | Docker orchestration with volume mount for DB |
| `.gitignore` | Standard Next.js + Prisma ignores |

## `app/` — Next.js App Router Pages & API

### Root Layout & Entry
| File | Purpose |
|------|---------|
| `app/layout.tsx` | Root HTML layout, global fonts, meta tags, PWA registration |
| `app/globals.css` | Tailwind imports, CSS variables (`--sidebar-width`, `--bottom-nav-height`) |
| `app/page.tsx` | Landing page — redirects to `/main/dashboard` if logged in |

### Auth (`app/auth/`)
| File | Purpose |
|------|---------|
| `app/auth/login/page.tsx` | Login form (email + password) |
| `app/auth/login/actions.ts` | Server action for login — validates credentials, creates session, sets cookie |

### Main App (`app/main/`)
All pages under `/main/` require authentication (enforced by middleware).

| File | Purpose |
|------|---------|
| `app/main/layout.tsx` | Authenticated layout with sidebar (desktop) and bottom nav (mobile) |
| `app/main/navigation.tsx` | Navigation component — 5 links: Dashboard, Workouts, Exercises, Import, Settings + logout |
| `app/main/actions.ts` | Server actions (logout) |

### Dashboard
| File | Purpose |
|------|---------|
| `app/main/dashboard/page.tsx` | Summary stats, recent workouts, personal bests |

### Workouts
| File | Purpose |
|------|---------|
| `app/main/workouts/page.tsx` | Workout history list with date filters, upload button linking to import |
| `app/main/workouts/new/page.tsx` | Create new workout — pick exercises, log sets |
| `app/main/workouts/[id]/page.tsx` | View/edit a single workout |

### Exercises
| File | Purpose |
|------|---------|
| `app/main/exercises/page.tsx` | Exercise library list with search and equipment type filter pills |
| `app/main/exercises/[id]/page.tsx` | Exercise detail — edit name/type/muscles/fields, view workout history for this exercise |

### Import
| File | Purpose |
|------|---------|
| `app/main/import/page.tsx` | Server component wrapper — auth check, renders `ImportCSVPage` |
| `app/main/import/page-csv.tsx` | Client component (~610 lines) — full CSV import flow: upload → review queue → approve/skip each workout |

### Settings
| File | Purpose |
|------|---------|
| `app/main/settings/page.tsx` | Server component wrapper for settings form |

### API Routes (`app/api/`)

| Route | Methods | Purpose |
|-------|---------|---------|
| `app/api/auth/route.ts` | POST | Login — validate credentials, create session, return token |
| `app/api/auth/logout/route.ts` | POST | Logout — delete session |
| `app/api/exercises/route.ts` | GET, POST | List exercises (with search), create new exercise |
| `app/api/exercises/[id]/route.ts` | GET, PUT, DELETE | Get/update/delete a single exercise |
| `app/api/workouts/route.ts` | GET, POST | List workouts (with date filters, pagination), create workout with sets |
| `app/api/workouts/[id]/route.ts` | GET, PUT, DELETE | Get/update/delete a single workout |
| `app/api/workouts/[id]/sets/route.ts` | POST, PUT, DELETE | Manage individual sets within a workout |
| `app/api/workouts/import/route.ts` | POST | Import endpoint (used by import page) |
| `app/api/workouts/import/save/route.ts` | POST | Save a single approved imported workout to DB |
| `app/api/import/parse/route.ts` | POST | Parse CSV upload — maps exercise names, groups by date, returns structured data with unmapped names |
| `app/api/preferences/route.ts` | GET, POST | Get/update user preferences (theme, weight unit, Claude AI settings) |
| `app/api/health/route.ts` | GET | Health check endpoint |

## `components/` — Reusable UI Components

### Exercises
| File | Purpose |
|------|---------|
| `components/exercises/AddExerciseForm.tsx` | Form for creating new exercises with type, muscle groups, and tracked fields |
| `components/exercises/ExerciseCard.tsx` | Card component for exercise list items |
| `components/exercises/ExercisesClient.tsx` | Client-side exercises list with search/filter state |

### Workouts
| File | Purpose |
|------|---------|
| `components/workouts/WorkoutForm.tsx` | Full workout logging form — exercise selection, set entry, notes |
| `components/workouts/WorkoutCard.tsx` | Expandable workout card for history list — shows date, stats line (exercises, total sets, duration), expandable exercise details with grouped set summaries |
| `components/workouts/ExercisePicker.tsx` | Modal/form for selecting an exercise from the library when logging a workout, includes inline exercise creation |
| `components/workouts/SetRow.tsx` | Single set row in the workout form — inputs for reps, weight, unit dropdown, RPE, duration, distance, calories, notes. Fields shown are controlled by exercise's `inputFields` |

### Import
| File | Purpose |
|------|---------|
| `components/import/WorkoutImportClient.tsx` | Import-related client component |

### Settings
| File | Purpose |
|------|---------|
| `components/settings/SettingsForm.tsx` | Settings form — theme selector, weight unit, Claude AI toggle + API key field |

## `lib/` — Shared Utilities & Data Access

| File | Purpose |
|------|---------|
| `lib/prisma.ts` | Singleton Prisma client instance |
| `lib/auth.ts` | Auth utilities: `hashPassword`, `verifyPassword`, `createSession`, `validateSession`, `getCurrentUser` |
| `lib/formatSets.ts` | `formatSetsSummary()` — groups consecutive same-weight sets into compact display (e.g., "245 x 3/3/3") |
| `lib/exerciseSearch.ts` | Exercise search/filter logic |
| `lib/utils.ts` | General utility functions (e.g., `cn()` for class merging with clsx + tailwind-merge) |
| `lib/db/exercises.ts` | Database queries for exercises |
| `lib/db/workouts.ts` | Database queries for workouts |
| `lib/db/stats.ts` | Dashboard statistics queries |

## `prisma/` — Database Schema & Data

| File | Purpose |
|------|---------|
| `prisma/schema.prisma` | Full data model — 13 models (User, Session, Exercise, Workout, SetLog, Program, ProgramWeek, ProgramDay, ProgramExercise, Equipment, ContentItem, ContentChunk, AISuggestion, UserPreferences) |
| `prisma/seed.ts` | Database seeding script |
| `prisma/data/app.db` | **The actual SQLite database file** (not `prisma/dev.db`) |
| `prisma/dev.db` | Stale/empty — do not use |

## `types/` — TypeScript Type Definitions

| File | Purpose |
|------|---------|
| `types/index.ts` | Shared types: `WorkoutWithSets`, `SetLogWithExercise`, `ExerciseWithStats`, `DashboardStats`, `SearchFilters`, `PaginationMeta`, `ParsedSet`, `ParsedExercise`, `ParsedWorkout`, `ImportParseResponse`, `ReviewedWorkout` |

## `public/` — Static Assets & PWA

| File | Purpose |
|------|---------|
| `public/manifest.json` | PWA manifest — app name, icons, theme color |
| `public/sw.js` | Service worker for offline caching |
| `public/sw-register.js` | Service worker registration script |
| `public/icons/` | App icons at multiple sizes (72–512px) including maskable variants, plus SVG favicon |

## `scripts/` — Server Management

| File | Purpose |
|------|---------|
| `scripts/start.sh` | Start the Next.js server (production) |
| `scripts/stop.sh` | Stop the server using stored PID |
| `scripts/rebuild.sh` | Rebuild and restart |
| `scripts/setup-autostart.sh` | Configure the app to start on boot |
| `scripts/generate-icons.js` | Generate PWA icons from SVG source |

## `import-data/` — Historical Workout Data

| File | Purpose |
|------|---------|
| `import-data/workout-log-feb2026.csv` | Parsed handwritten workout logs (Jan–Feb 2026, ~362 rows). Format: `date,exercise,weight,reps,notes`. More pages to be added. |

## `docs/` — Project Documentation

| File | Purpose |
|------|---------|
| `docs/PROJECT_OVERVIEW.md` | High-level overview: features, tech stack, future phases, design philosophy |
| `docs/FILE_REFERENCE.md` | This file — every file and folder explained |

## `logs/` — Server Logs

| File | Purpose |
|------|---------|
| `logs/server.log` | Server stdout |
| `logs/server-error.log` | Server stderr |