# joshfkon/workout-app architecture

> Architecture diagram of the GitHub repository joshfkon/workout-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joshfkon/workout-app
- Repository: https://github.com/joshfkon/workout-app

## Overview

HyperTrack is a science-based hypertrophy training tracker. The main user journey is to enter the dashboard, start and log a workout, then finish the session; session completion triggers post-session training updates and a summary. The product also supports training plans, coaching, nutrition, body and wellness tracking, analytics, motion capture, social features, wearables, and subscriptions. The graph reflects documented README capabilities and visible source references; where implementation or wiring was not sampled, relationships are omitted rather than inferred.

Main entry points: [`app/(dashboard)/dashboard/DashboardClient.tsx`](https://github.com/joshfkon/workout-app/blob/main/app/(dashboard)/dashboard/DashboardClient.tsx) (Dashboard), [`lib/supabase/client.ts`](https://github.com/joshfkon/workout-app/blob/main/lib/supabase/client.ts) (Supabase database), [`app/(dashboard)/dashboard/workout/[id]/_lib/finishWorkout.ts`](https://github.com/joshfkon/workout-app/blob/main/app/(dashboard)/dashboard/workout/%5Bid%5D/_lib/finishWorkout.ts) (Session completion), [`app/(dashboard)/dashboard/workout/[id]/page.tsx`](https://github.com/joshfkon/workout-app/blob/main/app/(dashboard)/dashboard/workout/%5Bid%5D/page.tsx) (Workout session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Access and dashboard"]
  node_auth["Authentication<br/>[route.ts]"]
  node_dashboard["Dashboard"]
end

subgraph group_training["Training workflow"]
  node_workout["Workout session<br/>[page.tsx]"]
  node_finish["Session completion<br/>[finishWorkout.ts]"]
  node_program["Training programs<br/>[programEngine.ts]"]
end

subgraph group_insights["Progress and wellness"]
  node_volume["Volume analytics<br/>[weeklyVolume.ts]"]
  node_lift["Strength trends<br/>[liftTrends.ts]"]
  node_body["Body tracking"]
  node_nutrition["Nutrition and TDEE<br/>[adaptive-tdee.ts]"]
end

subgraph group_support["Coaching and integrations"]
  node_coaching["AI coaching<br/>[coachingEngine.ts]"]
  node_planreview["Plan review<br/>[aiReview.ts]"]
  node_motion["Motion capture<br/>[pipeline.ts]"]
  node_social["Social features<br/>[index.ts]"]
  node_wearables["Wearable integrations<br/>[index.ts]"]
  node_billing["Subscriptions<br/>[stripe.ts]"]
end

subgraph group_platform["Data and services"]
  node_supabase[("Supabase database<br/>[client.ts]")]
  node_query[("Cached query state<br/>[queryClient.ts]")]
end

node_user(("Athlete"))

node_user -->|"signs in"| node_auth
node_auth -->|"authenticates"| node_supabase
node_user -->|"opens app"| node_dashboard
node_dashboard -->|"loads dashboard data"| node_supabase
node_dashboard -.->|"starts workout"| node_workout
node_workout -.->|"finishes session"| node_finish
node_finish -->|"writes session"| node_supabase
node_finish -->|"updates training block"| node_program
node_finish -->|"queues offline sets"| node_query
node_finish -->|"shows summary"| node_workout
node_program -->|"loads and saves plans"| node_supabase
node_dashboard -->|"loads volume data"| node_volume
node_dashboard -->|"loads lift trends"| node_lift
node_body -->|"logs body data"| node_supabase
node_dashboard -->|"loads eating window"| node_nutrition
node_user -.->|"requests guidance"| node_coaching
node_user -.->|"reviews draft plan"| node_planreview
node_user -.->|"captures movement"| node_motion
node_user -.->|"uses social features"| node_social
node_user -.->|"connects wearable"| node_wearables
node_user -->|"manages subscription"| node_billing
node_billing -->|"updates billing state"| node_supabase
node_dashboard -->|"caches app queries"| node_query

click node_auth "https://github.com/joshfkon/workout-app/blob/main/app/(auth)/auth/callback/route.ts"
click node_dashboard "https://github.com/joshfkon/workout-app/blob/main/app/(dashboard)/dashboard/DashboardClient.tsx"
click node_workout "https://github.com/joshfkon/workout-app/blob/main/app/(dashboard)/dashboard/workout/%5Bid%5D/page.tsx"
click node_finish "https://github.com/joshfkon/workout-app/blob/main/app/(dashboard)/dashboard/workout/%5Bid%5D/_lib/finishWorkout.ts"
click node_program "https://github.com/joshfkon/workout-app/blob/main/lib/training/programEngine.ts"
click node_volume "https://github.com/joshfkon/workout-app/blob/main/app/(dashboard)/dashboard/_lib/weeklyVolume.ts"
click node_lift "https://github.com/joshfkon/workout-app/blob/main/app/(dashboard)/dashboard/_lib/liftTrends.ts"
click node_body "https://github.com/joshfkon/workout-app/blob/main/components/body/LogBodyDataSheet.tsx"
click node_nutrition "https://github.com/joshfkon/workout-app/blob/main/lib/nutrition/adaptive-tdee.ts"
click node_coaching "https://github.com/joshfkon/workout-app/blob/main/services/coachingEngine.ts"
click node_planreview "https://github.com/joshfkon/workout-app/blob/main/services/workoutSetup/aiReview.ts"
click node_motion "https://github.com/joshfkon/workout-app/blob/main/services/shared/motion/pipeline.ts"
click node_social "https://github.com/joshfkon/workout-app/blob/main/components/social/index.ts"
click node_wearables "https://github.com/joshfkon/workout-app/blob/main/lib/integrations/index.ts"
click node_billing "https://github.com/joshfkon/workout-app/blob/main/lib/stripe.ts"
click node_supabase "https://github.com/joshfkon/workout-app/blob/main/lib/supabase/client.ts"
click node_query "https://github.com/joshfkon/workout-app/blob/main/lib/query/queryClient.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_auth,node_dashboard toneBlue
class node_workout,node_finish,node_program toneAmber
class node_volume,node_lift,node_body,node_nutrition toneMint
class node_coaching,node_planreview,node_motion,node_social,node_wearables,node_billing toneRose
class node_supabase,node_query,node_user toneIndigo
```

## Components

### Access and dashboard

- [Authentication](https://github.com/joshfkon/workout-app/blob/main/app/(auth)/auth/callback/route.ts): `app/(auth)/auth/callback/route.ts`
- [Dashboard](https://github.com/joshfkon/workout-app/blob/main/app/(dashboard)/dashboard/DashboardClient.tsx): `app/(dashboard)/dashboard/DashboardClient.tsx`

### Training workflow

- [Workout session](https://github.com/joshfkon/workout-app/blob/main/app/(dashboard)/dashboard/workout/%5Bid%5D/page.tsx): `app/(dashboard)/dashboard/workout/[id]/page.tsx`
- [Session completion](https://github.com/joshfkon/workout-app/blob/main/app/(dashboard)/dashboard/workout/%5Bid%5D/_lib/finishWorkout.ts): `app/(dashboard)/dashboard/workout/[id]/_lib/finishWorkout.ts`
- [Training programs](https://github.com/joshfkon/workout-app/blob/main/lib/training/programEngine.ts): `lib/training/programEngine.ts`

### Progress and wellness

- [Volume analytics](https://github.com/joshfkon/workout-app/blob/main/app/(dashboard)/dashboard/_lib/weeklyVolume.ts): `app/(dashboard)/dashboard/_lib/weeklyVolume.ts`
- [Strength trends](https://github.com/joshfkon/workout-app/blob/main/app/(dashboard)/dashboard/_lib/liftTrends.ts): `app/(dashboard)/dashboard/_lib/liftTrends.ts`
- [Body tracking](https://github.com/joshfkon/workout-app/blob/main/components/body/LogBodyDataSheet.tsx): `components/body/LogBodyDataSheet.tsx`
- [Nutrition and TDEE](https://github.com/joshfkon/workout-app/blob/main/lib/nutrition/adaptive-tdee.ts): `lib/nutrition/adaptive-tdee.ts`

### Coaching and integrations

- [AI coaching](https://github.com/joshfkon/workout-app/blob/main/services/coachingEngine.ts): `services/coachingEngine.ts`
- [Plan review](https://github.com/joshfkon/workout-app/blob/main/services/workoutSetup/aiReview.ts): `services/workoutSetup/aiReview.ts`
- [Motion capture](https://github.com/joshfkon/workout-app/blob/main/services/shared/motion/pipeline.ts): `services/shared/motion/pipeline.ts`
- [Social features](https://github.com/joshfkon/workout-app/blob/main/components/social/index.ts): `components/social/index.ts`
- [Wearable integrations](https://github.com/joshfkon/workout-app/blob/main/lib/integrations/index.ts): `lib/integrations/index.ts`
- [Subscriptions](https://github.com/joshfkon/workout-app/blob/main/lib/stripe.ts): `lib/stripe.ts`

### Data and services

- [Supabase database](https://github.com/joshfkon/workout-app/blob/main/lib/supabase/client.ts): `lib/supabase/client.ts`
- [Cached query state](https://github.com/joshfkon/workout-app/blob/main/lib/query/queryClient.ts): `lib/query/queryClient.ts`

### Other components

- **Athlete**

## Connections

- Athlete → Authentication: signs in (evidence: `README.md`)
- Authentication → Supabase database: authenticates (evidence: `app/(auth)/auth/callback/route.ts`)
- Athlete → Dashboard: opens app (evidence: `README.md`)
- Dashboard → Supabase database: loads dashboard data (evidence: `app/(dashboard)/dashboard/DashboardClient.tsx`)
- Dashboard → Workout session: starts workout
- Workout session → Session completion: finishes session
- Session completion → Supabase database: writes session (evidence: `app/(dashboard)/dashboard/workout/[id]/_lib/finishWorkout.ts`)
- Session completion → Training programs: updates training block (evidence: `app/(dashboard)/dashboard/workout/[id]/_lib/finishWorkout.ts`)
- Session completion → Cached query state: queues offline sets (evidence: `app/(dashboard)/dashboard/workout/[id]/_lib/finishWorkout.ts`)
- Session completion → Workout session: shows summary (evidence: `app/(dashboard)/dashboard/workout/[id]/_lib/finishWorkout.ts`)
- Training programs → Supabase database: loads and saves plans (evidence: `lib/training/programEngine.ts`)
- Dashboard → Volume analytics: loads volume data (evidence: `app/(dashboard)/dashboard/DashboardClient.tsx`)
- Dashboard → Strength trends: loads lift trends (evidence: `app/(dashboard)/dashboard/DashboardClient.tsx`)
- Body tracking → Supabase database: logs body data (evidence: `components/body/LogBodyDataSheet.tsx`)
- Dashboard → Nutrition and TDEE: loads eating window (evidence: `app/(dashboard)/dashboard/DashboardClient.tsx`)
- Athlete → AI coaching: requests guidance
- Athlete → Plan review: reviews draft plan
- Athlete → Motion capture: captures movement
- Athlete → Social features: uses social features
- Athlete → Wearable integrations: connects wearable
- Athlete → Subscriptions: manages subscription (evidence: `README.md`)
- Subscriptions → Supabase database: updates billing state
- Dashboard → Cached query state: caches app queries
