grant/proof-of-work
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1b64c45c52b2d50038f4aba6ee08310e1d3b01c1
proof-of-work/workout-planner/docs/FILE_REFERENCE.md
T
MacPro 1b64c45c52 Initial commit for Start9 packaging
2026-02-28 09:27:26 -06:00

184 lines
8.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 |
Reference in New Issue View Git Blame Copy Permalink