A local-first, deterministic fitness coaching web application built with Next.js 16, TypeScript, SQLite, and Tailwind CSS v4.
It replaces complex LLM-orchestrated prompt flows with a fast, deterministic, offline-capable coaching engine that syncs seamlessly with the Hevy REST API, analyzes workout progression, auto-generates 3-day split weekly plans, and compiles interactive performance reports.
- 🔑 Multi-User Authentication: Powered by Better Auth with invite-only account registration and admin invitation management.
- 🔒 Physical Data Isolation: Each user gets their own SQLite database (
data/users/<userId>/fitness.db) for complete physical separation. - 🔐 Encrypted Per-User API Keys: Hevy, Strava, and AI credentials are setup per-user in Settings and stored encrypted (AES-256-GCM) at rest.
- 🚂 Railway Deployment: Pre-configured Dockerfile and
railway.tomlfor zero-downtime deployment on Railway with persistent volume mounting. - 📱 Local-First & Offline Capable: Syncs workout history, routines, and body measurements from Hevy into isolated SQLite storage.
- ❤️ Heart Rate Enrichment: Automatically pulls HR data from Strava (via Apple Watch) and enriches Hevy workout records with avg/max HR, suffer score, and second-by-second HR timeline.
- 🔔 Training Insights: Smart notifications that detect HR adaptation, recovery needs, and RPE-HR mismatches over time.
- 🚴 Strava Integration: Sync activities from Strava and enrich weight training sessions with heart rate data from wearables.
- 📈 Readiness & Progression Engine: Calculates exercise readiness status (
ready,likely_ready,hold,consolidate), session tonnage, volume trends, and acute:chronic workload ratios. - 🗓️ Deterministic Weekly Plan Generator: Auto-generates weekly workout routines snapped strictly to available dumbbell racks, barbells, and machine weight steps.
- 📊 Interactive Performance Reports: Visual tonnage charts and progression lines powered by Recharts.
- ⚙️ Config Workspace: Visually edit gym equipment inventories, routine template structures, and exercise progression rules.
- 📝 Weekly Check-in & Profile Adaptation: Structured weekly check-in form for user feedback.
-
Copy
.env.exampleto.env.local:cp .env.example .env.local
-
Configure App & Auth Secrets:
BETTER_AUTH_SECRET=your-64-character-secret-string BETTER_AUTH_URL=http://localhost:3000 ENCRYPTION_KEY=your-64-character-hex-encryption-key NEXT_PUBLIC_BASE_URL=http://localhost:3000
-
Start Development Server:
npm run dev
-
Register Admin Account:
- The first user who registers automatically receives the
adminrole. - Go to
http://localhost:3000/sign-upto create your initial account. - Open
/adminto generate invite codes for friends and family.
- The first user who registers automatically receives the
For deep technical details, guidelines, and codebase reference, see:
- 📐
architecture.md— Single source of truth for overall system design, SQLite database schema definitions, subsystem boundaries, and Mermaid data flow diagrams. - 🤖
AGENTS.md— Developer guidelines, layer separation boundaries, agent directives, and the Automated Documentation Sync Protocol.
fitness-coach-app/
├── architecture.md # Authoritative technical reference
├── AGENTS.md # Agent rules & doc sync protocol
├── README.md # Human landing page & quick start guide
├── data/ # Persistent SQLite storage (data/fitness-coach.db)
├── prisma/
│ └── schema.sql # SQLite DDL schema definitions
├── src/
│ ├── app/ # Next.js App Router (Pages & API Route Handlers)
│ ├── components/ # React UI components by domain (dashboard, plan, config)
│ └── lib/ # Decoupled Core Business Logic Layer
│ ├── db.ts # SQLite connection manager (better-sqlite3)
│ ├── hevy/ # Hevy REST API client & sync engine
│ ├── strava/ # Strava API client, sync, and HR enrichment
│ ├── analysis/ # Progression readiness, tonnage, workload math, insights engine
│ ├── validation/ # Weight snapping & routine validation
│ └── planning/ # Weekly plan generator & progression engine
└── scripts/ # Data migration & utility scripts
npm run dev # Start development server
npm run build # Build production bundle
npm run type-check # Run TypeScript strict type checking
npm run lint # Run ESLint checkPrivate repository. All rights reserved.