proof-of-work/workout-planner/docs/FILE_REFERENCE.md

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