Train. Level Up. Unlock Your Stronger Self.
The world's first fitness RPG web app powered by real-time computer vision. FitQuest combines AI-powered pose detection, a gamified workout experience, and an interactive exercise library into a mobile-first progressive web app.
- Features
- Tech Stack
- Getting Started
- Project Structure
- AI Coach System
- Gamification System
- Exercise Library
- State Management
- Testing
- Deployment
- Documentation
- Contributing
- License
- Real-time pose detection using MediaPipe PoseLandmarker running in a dedicated Web Worker
- 7 camera-tracked lift patterns — squat, bench press, row, overhead press, deadlift, plank and glute bridge (configured in
lib/exercise-config.js) - Automatic rep counting via a state machine that tracks joint angle cycles (UP → DOWN → UP = 1 rep)
- Form scoring with per-exercise rules (depth, knee cave, back lean, hip sag, elbow flare)
- Voice coaching powered by Web Speech API with calm/energetic accents and adjustable volume
- Camera skeleton overlay showing detected body landmarks in real time
- 6 Hero Classes with unique RPG stats (Power, Endurance, Stability):
- Barbell Beast (Mythic) · Calisthenics King (Legendary) · PR Crusader (Legendary)
- Cardio Cheetah (Epic) · Mobility Monk (Epic) · Protein Sage (Rare)
- XP & Level Progression with exponential curve (
nextXp *= 1.35) - Daily Streak Tracking with streak milestones
- Achievement Badges — First Blood, Perfect Form, Iron King, Gold Finisher, Seven Day, Storm Caller
- Performance Bonuses for 90%+ form scores
- Confetti Celebration on workout completion
- 29 exercises across 3 equipment tiers: Barbell/Cable (9), Dumbbells (10), Bodyweight (10)
- Each exercise includes setup instructions, descent/drive cues, common mistakes, pro tips, target muscles, difficulty rating, and an illustration
- Responsive design with a centered phone frame on desktop (430px max-width)
- Bottom navigation with floating Coach button
- Service worker with MediaPipe model caching for faster loads
- PWA manifest for installability
- Dark mode support via CSS custom properties
- Toast notifications, error boundary with recovery, and accessibility features (ARIA labels, prefers-reduced-motion)
| Technology | Version | Purpose |
|---|---|---|
| Next.js | 16.2.9 | React framework (App Router, SSR) |
| React | 19.2.4 | UI library |
| Tailwind CSS | v4 | Utility-first CSS |
| MediaPipe Tasks Vision | ^0.10.21 | AI pose detection |
| Lucide React | ^1.21.0 | Icon library |
| Canvas Confetti | ^1.9.4 | Celebration effects |
| Vitest | ^4.1.9 | Unit testing |
| ESLint | ^9 | Linting |
| Prettier | latest | Code formatting |
| Vercel | — | Deployment platform |
Requires Node.js >= 18.18.0
- Node.js >= 18.18.0
- npm (included with Node)
# Clone the repository (the app lives at the repo root)
git clone https://github.com/princekumar-dev/FitQuest.git
cd FitQuest
# Install dependencies
npm installnpm run dev
# Open http://localhost:3000npm run build
npm run start| Command | Description |
|---|---|
npm run dev |
Start development server |
npm run build |
Create production build |
npm run start |
Start production server |
npm test |
Run unit tests (Vitest) |
npm run test:watch |
Run tests in watch mode |
npm run lint |
Run ESLint |
FitQuest/ # Next.js app at the repo root
├── app/ # Next.js App Router pages
│ ├── page.js # Landing page
│ ├── layout.js # Root layout with providers
│ ├── globals.css # Design system (1900+ lines)
│ ├── not-found.js # Custom 404 page
│ ├── home/page.js # Home dashboard
│ ├── onboarding/page.js # 6-step onboarding flow
│ ├── plan/page.js # Workout plan (tabbed view)
│ ├── coach/page.js # AI Camera Coach
│ ├── exercise/[id]/page.js # Exercise detail (dynamic)
│ ├── avatar/page.js # Hero class selection
│ ├── profile/page.js # User profile & settings
│ ├── progress/page.js # Performance analytics
│ ├── profile-result/page.js # Post-onboarding readiness score
│ └── workout-summary/page.js # Post-workout XP/rewards summary
├── components/ # Shared React components
│ ├── AppShell.js # App frame with nav bar & header
│ ├── CoachCountdown.js # 3-2-1 countdown overlay
│ ├── ErrorBoundary.js # React error boundary
│ ├── ServiceWorkerRegister.js # PWA service worker registration
│ ├── Skeleton.js # Loading skeleton components
│ └── Toast.js # Toast notification system
├── context/
│ └── AppContext.js # Global state (user, stats, settings, exercises)
├── lib/ # Core logic libraries
│ ├── exercise-config.js # Pose detection config per exercise
│ ├── pose-detection.worker.js # Web Worker for MediaPipe Pose
│ ├── pose-utils.js # Angle calculation & math utilities
│ ├── rep-counter.js # Rep counting state machine
│ ├── pose-utils.test.js # Tests for pose utilities
│ └── rep-counter.test.js # Tests for rep counter
├── public/ # Static assets
│ ├── manifest.json # PWA manifest
│ ├── sw.js # Service worker (caching + MediaPipe)
│ └── *.png # Exercise illustration images
├── next.config.mjs # Next.js configuration
├── vercel.json # Vercel deployment config
├── vitest.config.js # Test runner config
└── package.json
The AI Coach uses MediaPipe PoseLandmarker to detect 33 body landmarks in real time and processes them in a dedicated Web Worker to avoid blocking the main thread.
- Camera captures video frames and sends
ImageBitmapto the Web Worker - Worker loads MediaPipe model from Google's CDN and runs pose detection
- Pose utilities (
pose-utils.js) calculate joint angles from 33 landmarks usingatan2math - Rep counter (
rep-counter.js) tracks angle changes through a state machine (UP → DOWN → UP = 1 rep) - Form rules per exercise evaluate depth, alignment, and movement quality
- Form score is calculated with deductions per rule violation
- Voice feedback is delivered via Web Speech API
Each exercise in exercise-config.js defines:
- Joint indices and angle thresholds
- Direction (ascending/descending angle for reps)
- Form rules (e.g., depth >= 90°, no knee cave, no hip sag)
- Camera overlay skeleton keypoint mapping
| Class | Rarity | Stats |
|---|---|---|
| Barbell Beast | Mythic | Power: 10 · Endurance: 8 · Stability: 7 |
| Calisthenics King | Legendary | Power: 8 · Endurance: 9 · Stability: 8 |
| PR Crusader | Legendary | Power: 9 · Endurance: 7 · Stability: 9 |
| Cardio Cheetah | Epic | Power: 6 · Endurance: 10 · Stability: 6 |
| Mobility Monk | Epic | Power: 5 · Endurance: 8 · Stability: 10 |
| Protein Sage | Rare | Power: 7 · Endurance: 6 · Stability: 7 |
- XP earned per workout based on reps, form score, and exercise difficulty
- Level-up threshold:
nextXp *= 1.35(exponential curve) - Performance bonus: +20% XP for form scores >= 90%
- Daily streaks tracked with best-streak milestones
- Badges unlocked at milestones (First Blood, Perfect Form, Iron King, etc.)
29 exercises organized by equipment tier:
| Tier | Count | Exercises |
|---|---|---|
| Barbell / Cable | 9 | Back Squat, Front Squat, Bench Press, Bent-Over Row, Military Press, Conventional Deadlift, Romanian Deadlift, Lat Pulldown, Seated Cable Row |
| Dumbbells | 10 | Goblet Squat, Reverse Lunge, Flat Bench Press, Incline Bench Press, Seated Shoulder Press, Bent-Over Row, Single-Arm Row, Romanian Deadlift, Bicep Curl, Lateral Raise |
| Bodyweight | 10 | Air Squat, Split Squat, Push-Up, Diamond Push-Up, Incline Push-Up, Pull-Up, Chin-Up, Inverted Row, Plank, Glute Bridge |
Each exercise card includes:
- Difficulty rating (1–5)
- Target muscle groups
- Step-by-step form guide
- Common mistakes and corrections
- Pro tips
- Illustration image
All data is persisted client-side via localStorage with debounced writes (500ms):
| Key | Contents |
|---|---|
fq_user |
User profile (name, age, level, goals, gear, limitations, avatarId) |
fq_stats |
RPG stats (level, xp, nextXp, streak, bestStreak, cleanReps, totalWorkouts, avgForm) |
fq_settings |
App settings (voiceCoach, voiceType, volume, camera, privacy) |
fq_hasPlan |
Boolean flag for plan generation status |
fq_logs |
Array of completed workout session objects |
The AppContext provides global state via React Context with useMemo and useCallback for performance.
Tests are located in lib/**/*.test.js and context/**/*.test.js:
# Run all tests
npm test
# Run tests in watch mode
npm run test:watchTest coverage includes:
pose-utils.test.js— angle calculations and math utilitiesrep-counter.test.js— rep counting state machine logic
The project includes a vercel.json with custom headers for the /coach route:
{
"headers": [
{
"source": "/coach",
"headers": [
{ "key": "Cross-Origin-Opener-Policy", "value": "same-origin" },
{ "key": "Cross-Origin-Embedder-Policy", "value": "require-corp" }
]
}
]
}These headers are required for Web Worker + SharedArrayBuffer compatibility with MediaPipe.
Ensure your hosting platform supports:
- Custom headers for COOP/COEP on the
/coachroute - Service worker registration (HTTPS required)
- Static file serving for the
public/directory
The codebase is self-documented through:
- This README — product, architecture and system guides
AGENTS.md/CLAUDE.md— Next.js 16 agent rules (breaking-change notices for AI-assisted development)- Inline code comments — pose math, rep-counting state machine and gamification curves are commented in
lib/andcontext/ - Unit tests as living specs —
pose-utils.test.js,rep-counter.test.jsandAppContext.test.jsdocument expected behaviour
- Fork the repository
- Create a feature branch (
git checkout -b feature/your-feature) - Commit your changes (
git commit -m "Add your feature") - Push to the branch (
git push origin feature/your-feature) - Open a Pull Request
- Prettier: semicolons, double quotes, 2-space indentation
- ESLint: next/core-web-vitals rules
- Follow existing patterns in the codebase
- Add tests for new logic in
lib/
MIT, as declared by the author. A LICENSE file is not yet included — adding the standard MIT text would let GitHub detect and display it automatically.
FitQuest AI — Where every rep is a quest, and every workout levels you up.