# wl3512-lab/habitabull-lifting architecture

> Architecture diagram of the GitHub repository wl3512-lab/habitabull-lifting, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wl3512-lab/habitabull-lifting
- Repository: https://github.com/wl3512-lab/habitabull-lifting

## Overview

HabitaBull is a phone-first lifting and habit-tracking app. The main workflow is to set up a profile and weekly routine, generate a session, log sets, then review the workout and progress. Its additional branches include calendar/history, goals and streaks, routine assistance, and an opt-in crew for shared plans, check-ins, and workout photos. The main page’s orchestration, local persistence, rules engine, generation endpoint, and crew server/database calls are evidenced in sampled source; some UI and integration wiring is inferred only from the tree and imports.

Main entry points: [`app/page.tsx`](https://github.com/wl3512-lab/habitabull-lifting/blob/main/app/page.tsx) (App coordinator), [`components/RoutineEditor.tsx`](https://github.com/wl3512-lab/habitabull-lifting/blob/main/components/RoutineEditor.tsx) (Routine editor), [`components/LogSession.tsx`](https://github.com/wl3512-lab/habitabull-lifting/blob/main/components/LogSession.tsx) (Session logger), [`lib/engine.ts`](https://github.com/wl3512-lab/habitabull-lifting/blob/main/lib/engine.ts) (Training rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workout["Workout planning"]
  node_onboarding["Onboarding<br/>[Onboarding.tsx]"]
  node_weeksetup["Week setup<br/>[WeekSetup.tsx]"]
  node_routineeditor["Routine editor<br/>[RoutineEditor.tsx]"]
  node_engine["Training rules<br/>[engine.ts]"]
  node_exercises["Exercise catalog<br/>[exercises.ts]"]
  node_templates["Routine templates<br/>[templates.ts]"]
end

subgraph group_tracking["Training and history"]
  node_today["Today view<br/>[Today.tsx]"]
  node_logger["Session logger<br/>[LogSession.tsx]"]
  node_timer["Rest timer<br/>[RestTimer.tsx]"]
  node_after["Workout summary<br/>[AfterWorkout.tsx]"]
  node_progress["Progress and streaks<br/>[Progress.tsx]"]
  node_calendar["Calendar history<br/>[Calendar.tsx]"]
  node_goals["Goal tracking<br/>[GoalScreen.tsx]"]
end

subgraph group_community["Crew sharing"]
  node_crewui["Crew experience<br/>[Crew.tsx]"]
  node_cloud["Crew client<br/>[cloud.ts]"]
  node_crewapi["Crew API<br/>[route.ts]"]
end

subgraph group_services["App services"]
  node_app["App coordinator<br/>[page.tsx]"]
  node_generate["Workout assistance<br/>[route.ts]"]
  node_storage[("Local app data<br/>[storage.ts]")]
  node_db["Crew data access<br/>[db.ts]"]
  node_backup["Backup and restore<br/>[backup.ts]"]
  node_voice["Voice cues<br/>[voice.ts]"]
end

node_person(("Lifter"))
node_ai["AI proxy"]
node_supabase[("Supabase services")]

node_person -->|"uses"| node_app
node_app -->|"loads and saves"| node_storage
node_app -->|"presents"| node_onboarding
node_app -->|"presents"| node_weeksetup
node_app -->|"presents"| node_routineeditor
node_routineeditor -->|"builds routines"| node_engine
node_routineeditor -->|"uses templates"| node_templates
node_routineeditor -->|"selects exercises"| node_exercises
node_generate -->|"gets alternatives"| node_engine
node_generate -.->|"requests interpretation"| node_ai
node_app -->|"builds sessions"| node_engine
node_app -->|"presents"| node_today
node_app -->|"opens session"| node_logger
node_logger -->|"gets records and rest"| node_engine
node_logger -->|"shows rest"| node_timer
node_logger -->|"gets cues"| node_voice
node_app -->|"presents completion"| node_after
node_app -->|"presents history"| node_progress
node_app -->|"presents history"| node_calendar
node_app -->|"presents goals"| node_goals
node_app -->|"presents crew"| node_crewui
node_crewui -->|"uses crew services"| node_cloud
node_cloud -->|"sends requests"| node_crewapi
node_crewapi -->|"reads and writes"| node_db
node_db -->|"calls REST and storage"| node_supabase
node_app -->|"offers data backup"| node_backup

click node_app "https://github.com/wl3512-lab/habitabull-lifting/blob/main/app/page.tsx"
click node_onboarding "https://github.com/wl3512-lab/habitabull-lifting/blob/main/components/Onboarding.tsx"
click node_weeksetup "https://github.com/wl3512-lab/habitabull-lifting/blob/main/components/WeekSetup.tsx"
click node_routineeditor "https://github.com/wl3512-lab/habitabull-lifting/blob/main/components/RoutineEditor.tsx"
click node_engine "https://github.com/wl3512-lab/habitabull-lifting/blob/main/lib/engine.ts"
click node_exercises "https://github.com/wl3512-lab/habitabull-lifting/blob/main/lib/exercises.ts"
click node_templates "https://github.com/wl3512-lab/habitabull-lifting/blob/main/lib/templates.ts"
click node_generate "https://github.com/wl3512-lab/habitabull-lifting/blob/main/app/api/generate/route.ts"
click node_today "https://github.com/wl3512-lab/habitabull-lifting/blob/main/components/Today.tsx"
click node_logger "https://github.com/wl3512-lab/habitabull-lifting/blob/main/components/LogSession.tsx"
click node_timer "https://github.com/wl3512-lab/habitabull-lifting/blob/main/components/RestTimer.tsx"
click node_after "https://github.com/wl3512-lab/habitabull-lifting/blob/main/components/AfterWorkout.tsx"
click node_progress "https://github.com/wl3512-lab/habitabull-lifting/blob/main/components/Progress.tsx"
click node_calendar "https://github.com/wl3512-lab/habitabull-lifting/blob/main/components/Calendar.tsx"
click node_goals "https://github.com/wl3512-lab/habitabull-lifting/blob/main/components/GoalScreen.tsx"
click node_storage "https://github.com/wl3512-lab/habitabull-lifting/blob/main/lib/storage.ts"
click node_crewui "https://github.com/wl3512-lab/habitabull-lifting/blob/main/components/Crew.tsx"
click node_cloud "https://github.com/wl3512-lab/habitabull-lifting/blob/main/lib/cloud.ts"
click node_crewapi "https://github.com/wl3512-lab/habitabull-lifting/blob/main/app/api/crew/%5Baction%5D/route.ts"
click node_db "https://github.com/wl3512-lab/habitabull-lifting/blob/main/lib/server/db.ts"
click node_backup "https://github.com/wl3512-lab/habitabull-lifting/blob/main/lib/backup.ts"
click node_voice "https://github.com/wl3512-lab/habitabull-lifting/blob/main/lib/voice.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_onboarding,node_weeksetup,node_routineeditor,node_engine,node_exercises,node_templates toneBlue
class node_today,node_logger,node_timer,node_after,node_progress,node_calendar,node_goals,node_supabase toneAmber
class node_crewui,node_cloud,node_crewapi toneMint
class node_app,node_generate,node_storage,node_db,node_backup,node_voice toneRose
class node_person,node_ai toneIndigo
```

## Components

### Workout planning

- [Onboarding](https://github.com/wl3512-lab/habitabull-lifting/blob/main/components/Onboarding.tsx): `components/Onboarding.tsx`
- [Week setup](https://github.com/wl3512-lab/habitabull-lifting/blob/main/components/WeekSetup.tsx): `components/WeekSetup.tsx`
- [Routine editor](https://github.com/wl3512-lab/habitabull-lifting/blob/main/components/RoutineEditor.tsx): `components/RoutineEditor.tsx`
- [Training rules](https://github.com/wl3512-lab/habitabull-lifting/blob/main/lib/engine.ts): `lib/engine.ts`
- [Exercise catalog](https://github.com/wl3512-lab/habitabull-lifting/blob/main/lib/exercises.ts): `lib/exercises.ts`
- [Routine templates](https://github.com/wl3512-lab/habitabull-lifting/blob/main/lib/templates.ts): `lib/templates.ts`

### Training and history

- [Today view](https://github.com/wl3512-lab/habitabull-lifting/blob/main/components/Today.tsx): `components/Today.tsx`
- [Session logger](https://github.com/wl3512-lab/habitabull-lifting/blob/main/components/LogSession.tsx): `components/LogSession.tsx`
- [Rest timer](https://github.com/wl3512-lab/habitabull-lifting/blob/main/components/RestTimer.tsx): `components/RestTimer.tsx`
- [Workout summary](https://github.com/wl3512-lab/habitabull-lifting/blob/main/components/AfterWorkout.tsx): `components/AfterWorkout.tsx`
- [Progress and streaks](https://github.com/wl3512-lab/habitabull-lifting/blob/main/components/Progress.tsx): `components/Progress.tsx`
- [Calendar history](https://github.com/wl3512-lab/habitabull-lifting/blob/main/components/Calendar.tsx): `components/Calendar.tsx`
- [Goal tracking](https://github.com/wl3512-lab/habitabull-lifting/blob/main/components/GoalScreen.tsx): `components/GoalScreen.tsx`

### Crew sharing

- [Crew experience](https://github.com/wl3512-lab/habitabull-lifting/blob/main/components/Crew.tsx): `components/Crew.tsx`
- [Crew client](https://github.com/wl3512-lab/habitabull-lifting/blob/main/lib/cloud.ts): `lib/cloud.ts`
- [Crew API](https://github.com/wl3512-lab/habitabull-lifting/blob/main/app/api/crew/%5Baction%5D/route.ts): `app/api/crew/[action]/route.ts`

### App services

- [App coordinator](https://github.com/wl3512-lab/habitabull-lifting/blob/main/app/page.tsx): `app/page.tsx`
- [Workout assistance](https://github.com/wl3512-lab/habitabull-lifting/blob/main/app/api/generate/route.ts): `app/api/generate/route.ts`
- [Local app data](https://github.com/wl3512-lab/habitabull-lifting/blob/main/lib/storage.ts): `lib/storage.ts`
- [Crew data access](https://github.com/wl3512-lab/habitabull-lifting/blob/main/lib/server/db.ts): `lib/server/db.ts`
- [Backup and restore](https://github.com/wl3512-lab/habitabull-lifting/blob/main/lib/backup.ts): `lib/backup.ts`
- [Voice cues](https://github.com/wl3512-lab/habitabull-lifting/blob/main/lib/voice.ts): `lib/voice.ts`

### Other components

- **Lifter**
- **AI proxy**
- **Supabase services**

## Connections

- Lifter → App coordinator: uses
- App coordinator → Local app data: loads and saves
- App coordinator → Onboarding: presents
- App coordinator → Week setup: presents
- App coordinator → Routine editor: presents
- Routine editor → Training rules: builds routines
- Routine editor → Routine templates: uses templates
- Routine editor → Exercise catalog: selects exercises
- Workout assistance → Training rules: gets alternatives
- Workout assistance → AI proxy: requests interpretation
- App coordinator → Training rules: builds sessions
- App coordinator → Today view: presents
- App coordinator → Session logger: opens session
- Session logger → Training rules: gets records and rest
- Session logger → Rest timer: shows rest
- Session logger → Voice cues: gets cues
- App coordinator → Workout summary: presents completion
- App coordinator → Progress and streaks: presents history
- App coordinator → Calendar history: presents history
- App coordinator → Goal tracking: presents goals
- App coordinator → Crew experience: presents crew
- Crew experience → Crew client: uses crew services
- Crew client → Crew API: sends requests
- Crew API → Crew data access: reads and writes
- Crew data access → Supabase services: calls REST and storage
- App coordinator → Backup and restore: offers data backup