# saabithe/forma architecture

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

- Interactive diagram: https://gitdiagram.com/saabithe/forma
- Repository: https://github.com/saabithe/forma

## Overview

1. This is a client-side React + Vite single-page application. The runtime entry is `index.html` → `src/main.jsx` → `src/App.jsx`, with Vite handling local development, bundling, and production builds.

2. The app is organized around page-level views in `src/pages`: `Home`, `Onboarding`, `Profile`, `Results`, `Roadmap`, `SkillDetail`, and `WorkoutSession`. These are the main navigation destinations and likely correspond to the major user journey through setup, training, review, and progress tracking.

3. Shared UI lives in `src/components`. The key reusable pieces are `Layout`, `TabBar`, `ThemeToggle`, `PhaseIndicator`, `CriteriaTracker`, `ExerciseCard`, and `LevelUpModal`. This suggests a consistent shell around the app plus specialized training UI for exercise display, progress criteria, and milestone feedback.

4. The core business logic is split into custom hooks under `src/hooks`, which act as the orchestration layer between UI and domain data. `useWorkoutEngine`, `useWorkoutSession`, `useDailyWorkout`, `useProgression`, and `useFormaState` likely manage session state, workout generation, progression rules, and the overall app state machine.

5. Static domain content is centralized in `src/data`. `curriculum.js`, `daily-routines.js`, and the `training-plans` and `exercises` subfolders define the underlying workout/skill system. The exercise data is further separated by type (`holds`, `reps`, `mobility`), which indicates the app treats different exercise modalities distinctly.

6. Domain rules and evaluation logic live in `src/lib`. `assessment.js`, `criteria.js`, `progression.js`, `migration.js`, and `storage.js` form the backend-free logic layer: assessing performance, determining advancement, handling stored state, and migrating older saved data formats. This is the most important boundary in the app because it turns training inputs into progression outcomes.

7. The primary data flow is: curriculum and plan data are selected by the hooks, the workout engine assembles a session, the session UI renders exercises and criteria, and user outcomes feed back into progression logic. Results and profile screens then present the updated state, while roadmap/skill detail views expose the longer-term curriculum structure.

8. Persistence appears to be entirely client-side. `src/lib/storage.js` and `migration.js` imply saved user progress, onboarding choices, and session history are stored locally in the browser and periodically normalized as the app evolves. There is no visible server/API layer in the repository tree.

9. Theming is handled separately through `src/theme/ThemeContext.jsx` and the `src/theme` folder. `ThemeToggle` in the component layer indicates theme state is global and user-controlled, affecting the entire app shell rather than being local to one page.

10. The app’s design is strongly data-driven: UI components are generic, while the training logic comes from declarative datasets and rule libraries. That makes the architecture easy to diagram as presentation on top of a domain engine, with static curriculum content feeding the engine and local storage providing persistence.

11. Build and delivery are lightweight but real: the project includes a GitHub Actions workflow at `.github/workflows/deploy.yml`, which suggests automated deployment of the static Vite build. The repository therefore has a clear separation between source code, generated assets, and deployment automation.

Main entry points: [`src/App.jsx`](https://github.com/saabithe/forma/blob/main/src/App.jsx) (App), [`src/pages/WorkoutSession.jsx`](https://github.com/saabithe/forma/blob/main/src/pages/WorkoutSession.jsx) (WorkoutSession), [`src/hooks/useFormaState.js`](https://github.com/saabithe/forma/blob/main/src/hooks/useFormaState.js) (FormaState), [`src/components/Layout.jsx`](https://github.com/saabithe/forma/blob/main/src/components/Layout.jsx) (Layout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_delivery["Delivery"]
  node_vite_config["Vite<br/>build config<br/>[vite.config.js]"]
  node_deploy_workflow["Deploy<br/>ci workflow<br/>[deploy.yml]"]
end

subgraph group_runtime["Runtime"]
  node_index_html["index.html<br/>entry document<br/>[index.html]"]
  node_main_jsx["main.jsx<br/>bootstrap<br/>[main.jsx]"]
  node_app_jsx["App<br/>shell/router<br/>[App.jsx]"]
end

subgraph group_presentation["Presentation"]
  node_theme_context["Theme<br/>global context<br/>[ThemeContext.jsx]"]
  node_layout["Layout<br/>app shell<br/>[Layout.jsx]"]
  node_tab_bar["TabBar<br/>navigation UI<br/>[TabBar.jsx]"]
  node_exercise_card["ExerciseCard<br/>exercise UI<br/>[ExerciseCard.jsx]"]
  node_criteria_tracker["CriteriaTracker<br/>progress UI"]
  node_level_up_modal["LevelUpModal<br/>feedback UI<br/>[LevelUpModal.jsx]"]
  node_theme_toggle["ThemeToggle<br/>control UI<br/>[ThemeToggle.jsx]"]
end

subgraph group_views["Views"]
  node_home_view["Home<br/>landing page<br/>[Home.jsx]"]
  node_onboarding_view["Onboarding<br/>setup page<br/>[Onboarding.jsx]"]
  node_session_view["WorkoutSession<br/>training page<br/>[WorkoutSession.jsx]"]
  node_results_view["Results<br/>review page<br/>[Results.jsx]"]
  node_profile_view["Profile<br/>progress page<br/>[Profile.jsx]"]
  node_curriculum_views["Roadmap<br/>curriculum page<br/>[Roadmap.jsx]"]
  node_skill_detail_view["SkillDetail<br/>curriculum page<br/>[SkillDetail.jsx]"]
end

subgraph group_engine["Engine"]
  node_workout_engine["WorkoutEngine<br/>orchestration hook"]
  node_workout_session_hook["SessionState<br/>session hook"]
  node_daily_workout_hook["DailyWorkout<br/>schedule hook<br/>[useDailyWorkout.js]"]
  node_progression_hook["Progression<br/>state hook<br/>[useProgression.js]"]
  node_forma_state_hook["FormaState<br/>app state hook<br/>[useFormaState.js]"]
end

subgraph group_content["Content"]
  node_curriculum_data["Curriculum<br/>[curriculum.js]"]
  node_training_plans["TrainingPlans<br/>plan catalog<br/>[index.js]"]
  node_exercise_library["Exercises<br/>exercise catalog<br/>[index.js]"]
  node_daily_routines["Routines<br/>routine data<br/>[daily-routines.js]"]
  node_assessment_lib["Assessment<br/>rule library<br/>[assessment.js]"]
  node_criteria_lib["Criteria<br/>rule library<br/>[criteria.js]"]
  node_progression_lib["ProgressionRules<br/>rule library<br/>[progression.js]"]
  node_storage_lib["Storage<br/>persistence<br/>[storage.js]"]
  node_migration_lib["Migration<br/>[migration.js]"]
end

node_index_html -->|"loads"| node_main_jsx
node_main_jsx -->|"renders"| node_app_jsx
node_app_jsx -->|"wraps"| node_layout
node_app_jsx -->|"provides"| node_theme_context
node_app_jsx -->|"routes"| node_home_view
node_app_jsx -->|"routes"| node_onboarding_view
node_app_jsx -->|"routes"| node_session_view
node_app_jsx -->|"routes"| node_results_view
node_app_jsx -->|"routes"| node_profile_view
node_app_jsx -->|"routes"| node_curriculum_views
node_app_jsx -->|"routes"| node_skill_detail_view
node_layout -->|"contains"| node_tab_bar
node_layout -->|"contains"| node_theme_toggle
node_session_view -->|"shows"| node_exercise_card
node_session_view -->|"tracks"| node_criteria_tracker
node_results_view -->|"celebrates"| node_level_up_modal
node_home_view -->|"uses"| node_daily_workout_hook
node_onboarding_view -->|"uses"| node_forma_state_hook
node_session_view -->|"uses"| node_workout_session_hook
node_session_view -->|"uses"| node_workout_engine
node_results_view -->|"uses"| node_progression_hook
node_profile_view -->|"uses"| node_forma_state_hook
node_workout_engine -->|"reads"| node_curriculum_data
node_workout_engine -->|"builds from"| node_training_plans
node_daily_workout_hook -->|"reads"| node_daily_routines
node_workout_session_hook -->|"evaluates"| node_assessment_lib
node_progression_hook -->|"applies"| node_progression_lib
node_progression_hook -->|"checks"| node_criteria_lib
node_forma_state_hook -->|"persists"| node_storage_lib
node_forma_state_hook -->|"normalizes"| node_migration_lib
node_training_plans -->|"references"| node_exercise_library
node_exercise_library -->|"aligns with"| node_curriculum_data
node_storage_lib -->|"upgrades"| node_migration_lib
node_vite_config -->|"supports"| node_deploy_workflow

click node_index_html "https://github.com/saabithe/forma/blob/main/index.html"
click node_main_jsx "https://github.com/saabithe/forma/blob/main/src/main.jsx"
click node_app_jsx "https://github.com/saabithe/forma/blob/main/src/App.jsx"
click node_vite_config "https://github.com/saabithe/forma/blob/main/vite.config.js"
click node_deploy_workflow "https://github.com/saabithe/forma/blob/main/.github/workflows/deploy.yml"
click node_theme_context "https://github.com/saabithe/forma/blob/main/src/theme/ThemeContext.jsx"
click node_layout "https://github.com/saabithe/forma/blob/main/src/components/Layout.jsx"
click node_tab_bar "https://github.com/saabithe/forma/blob/main/src/components/TabBar.jsx"
click node_exercise_card "https://github.com/saabithe/forma/blob/main/src/components/ExerciseCard.jsx"
click node_criteria_tracker "https://github.com/saabithe/forma/blob/main/src/components/CriteriaTracker.jsx"
click node_level_up_modal "https://github.com/saabithe/forma/blob/main/src/components/LevelUpModal.jsx"
click node_theme_toggle "https://github.com/saabithe/forma/blob/main/src/components/ThemeToggle.jsx"
click node_home_view "https://github.com/saabithe/forma/blob/main/src/pages/Home.jsx"
click node_onboarding_view "https://github.com/saabithe/forma/blob/main/src/pages/Onboarding.jsx"
click node_session_view "https://github.com/saabithe/forma/blob/main/src/pages/WorkoutSession.jsx"
click node_results_view "https://github.com/saabithe/forma/blob/main/src/pages/Results.jsx"
click node_profile_view "https://github.com/saabithe/forma/blob/main/src/pages/Profile.jsx"
click node_curriculum_views "https://github.com/saabithe/forma/blob/main/src/pages/Roadmap.jsx"
click node_skill_detail_view "https://github.com/saabithe/forma/blob/main/src/pages/SkillDetail.jsx"
click node_workout_engine "https://github.com/saabithe/forma/blob/main/src/hooks/useWorkoutEngine.js"
click node_workout_session_hook "https://github.com/saabithe/forma/blob/main/src/hooks/useWorkoutSession.js"
click node_daily_workout_hook "https://github.com/saabithe/forma/blob/main/src/hooks/useDailyWorkout.js"
click node_progression_hook "https://github.com/saabithe/forma/blob/main/src/hooks/useProgression.js"
click node_forma_state_hook "https://github.com/saabithe/forma/blob/main/src/hooks/useFormaState.js"
click node_curriculum_data "https://github.com/saabithe/forma/blob/main/src/data/curriculum.js"
click node_training_plans "https://github.com/saabithe/forma/blob/main/src/data/training-plans/index.js"
click node_exercise_library "https://github.com/saabithe/forma/blob/main/src/data/exercises/index.js"
click node_daily_routines "https://github.com/saabithe/forma/blob/main/src/data/daily-routines.js"
click node_assessment_lib "https://github.com/saabithe/forma/blob/main/src/lib/assessment.js"
click node_criteria_lib "https://github.com/saabithe/forma/blob/main/src/lib/criteria.js"
click node_progression_lib "https://github.com/saabithe/forma/blob/main/src/lib/progression.js"
click node_storage_lib "https://github.com/saabithe/forma/blob/main/src/lib/storage.js"
click node_migration_lib "https://github.com/saabithe/forma/blob/main/src/lib/migration.js"

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_vite_config,node_deploy_workflow toneBlue
class node_index_html,node_main_jsx,node_app_jsx toneAmber
class node_theme_context,node_layout,node_tab_bar,node_exercise_card,node_criteria_tracker,node_level_up_modal,node_theme_toggle toneMint
class node_home_view,node_onboarding_view,node_session_view,node_results_view,node_profile_view,node_curriculum_views,node_skill_detail_view toneRose
class node_workout_engine,node_workout_session_hook,node_daily_workout_hook,node_progression_hook,node_forma_state_hook toneIndigo
class node_curriculum_data,node_training_plans,node_exercise_library,node_daily_routines,node_assessment_lib,node_criteria_lib,node_progression_lib,node_storage_lib,node_migration_lib toneTeal
```

## Components

### Delivery

Build and automated static deployment

- [Vite](https://github.com/saabithe/forma/blob/main/vite.config.js): build config · Local dev and production build configuration · `vite.config.js`
- [Deploy](https://github.com/saabithe/forma/blob/main/.github/workflows/deploy.yml): ci workflow · Automated static deploy pipeline · `.github/workflows/deploy.yml`

### Runtime

App entry and bootstrap

- [index.html](https://github.com/saabithe/forma/blob/main/index.html): entry document · Vite entry document · `index.html`
- [main.jsx](https://github.com/saabithe/forma/blob/main/src/main.jsx): bootstrap · Mounts the React app · `src/main.jsx`
- [App](https://github.com/saabithe/forma/blob/main/src/App.jsx): shell/router · Top-level application composition · `src/App.jsx`

### Presentation

Shared shell, navigation, and reusable UI

- [Theme](https://github.com/saabithe/forma/blob/main/src/theme/ThemeContext.jsx): global context · App-wide theme state · `src/theme/ThemeContext.jsx`
- [Layout](https://github.com/saabithe/forma/blob/main/src/components/Layout.jsx): app shell · Primary chrome and page frame · `src/components/Layout.jsx`
- [TabBar](https://github.com/saabithe/forma/blob/main/src/components/TabBar.jsx): navigation UI · Primary navigation control · `src/components/TabBar.jsx`
- [ExerciseCard](https://github.com/saabithe/forma/blob/main/src/components/ExerciseCard.jsx): exercise UI · Reusable workout item display · `src/components/ExerciseCard.jsx`
- [CriteriaTracker](https://github.com/saabithe/forma/blob/main/src/components/CriteriaTracker.jsx): progress UI · Shows session criteria and completion · `src/components/CriteriaTracker.jsx`
- [LevelUpModal](https://github.com/saabithe/forma/blob/main/src/components/LevelUpModal.jsx): feedback UI · Milestone and advancement feedback · `src/components/LevelUpModal.jsx`
- [ThemeToggle](https://github.com/saabithe/forma/blob/main/src/components/ThemeToggle.jsx): control UI · User-facing theme switch · `src/components/ThemeToggle.jsx`

### Views

Major user-facing screens

- [Home](https://github.com/saabithe/forma/blob/main/src/pages/Home.jsx): landing page · Entry point into the app · `src/pages/Home.jsx`
- [Onboarding](https://github.com/saabithe/forma/blob/main/src/pages/Onboarding.jsx): setup page · Initial user setup and preferences · `src/pages/Onboarding.jsx`
- [WorkoutSession](https://github.com/saabithe/forma/blob/main/src/pages/WorkoutSession.jsx): training page · Active workout execution screen · `src/pages/WorkoutSession.jsx`
- [Results](https://github.com/saabithe/forma/blob/main/src/pages/Results.jsx): review page · Post-session outcome and summary · `src/pages/Results.jsx`
- [Profile](https://github.com/saabithe/forma/blob/main/src/pages/Profile.jsx): progress page · User progress and state overview · `src/pages/Profile.jsx`
- [Roadmap](https://github.com/saabithe/forma/blob/main/src/pages/Roadmap.jsx): curriculum page · Long-term skill and curriculum navigation · `src/pages/Roadmap.jsx`
- [SkillDetail](https://github.com/saabithe/forma/blob/main/src/pages/SkillDetail.jsx): curriculum page · Focused skill breakdown and requirements · `src/pages/SkillDetail.jsx`

### Engine

Session orchestration and progression logic

- [WorkoutEngine](https://github.com/saabithe/forma/blob/main/src/hooks/useWorkoutEngine.js): orchestration hook · Assembles sessions from plans and rules · `src/hooks/useWorkoutEngine.js`
- [SessionState](https://github.com/saabithe/forma/blob/main/src/hooks/useWorkoutSession.js): session hook · Manages live workout session state · `src/hooks/useWorkoutSession.js`
- [DailyWorkout](https://github.com/saabithe/forma/blob/main/src/hooks/useDailyWorkout.js): schedule hook · Selects the day’s workout · `src/hooks/useDailyWorkout.js`
- [Progression](https://github.com/saabithe/forma/blob/main/src/hooks/useProgression.js): state hook · Coordinates advancement logic · `src/hooks/useProgression.js`
- [FormaState](https://github.com/saabithe/forma/blob/main/src/hooks/useFormaState.js): app state hook · Centralized app state orchestration · `src/hooks/useFormaState.js`

### Content

Curriculum, plans, exercises, and persistence rules

- [Curriculum](https://github.com/saabithe/forma/blob/main/src/data/curriculum.js): curriculum data · Core skill progression model · `src/data/curriculum.js`
- [TrainingPlans](https://github.com/saabithe/forma/blob/main/src/data/training-plans/index.js): plan catalog · Plan variants by level and support · `src/data/training-plans/index.js`
- [Exercises](https://github.com/saabithe/forma/blob/main/src/data/exercises/index.js): exercise catalog · Holds, reps, and mobility definitions · `src/data/exercises/index.js`
- [Routines](https://github.com/saabithe/forma/blob/main/src/data/daily-routines.js): routine data · Daily workout templates · `src/data/daily-routines.js`
- [Assessment](https://github.com/saabithe/forma/blob/main/src/lib/assessment.js): rule library · Evaluates workout performance · `src/lib/assessment.js`
- [Criteria](https://github.com/saabithe/forma/blob/main/src/lib/criteria.js): rule library · Defines completion criteria · `src/lib/criteria.js`
- [ProgressionRules](https://github.com/saabithe/forma/blob/main/src/lib/progression.js): rule library · Advancement and level logic · `src/lib/progression.js`
- [Storage](https://github.com/saabithe/forma/blob/main/src/lib/storage.js): persistence · Browser storage access · `src/lib/storage.js`
- [Migration](https://github.com/saabithe/forma/blob/main/src/lib/migration.js): schema migration · Normalizes older saved state · `src/lib/migration.js`

## Connections

- index.html → main.jsx: loads · HTML entry boots the React bundle
- main.jsx → App: renders · Bootstrap mounts the application shell
- App → Layout: wraps · Top-level shell surrounds route content
- App → Theme: provides · Theme state is global to the app
- App → Home: routes · Main navigation starts at home
- App → Onboarding: routes · Setup flow before training
- App → WorkoutSession: routes · Active workout screen
- App → Results: routes · Post-session review screen
- App → Profile: routes · Progress and profile screen
- App → Roadmap: routes · Long-term roadmap navigation
- App → SkillDetail: routes · Focused skill detail view
- Layout → TabBar: contains · Shell includes primary navigation
- Layout → ThemeToggle: contains · Shell exposes theme control
- WorkoutSession → ExerciseCard: shows · Workout screen renders exercises
- WorkoutSession → CriteriaTracker: tracks · Displays completion criteria during training
- Results → LevelUpModal: celebrates · Results may surface advancement feedback
- Home → DailyWorkout: uses · Landing page can surface the daily workout
- Onboarding → FormaState: uses · Setup updates central app state
- WorkoutSession → SessionState: uses · Workout screen manages live session state
- WorkoutSession → WorkoutEngine: uses · Session is assembled by the workout engine
- Results → Progression: uses · Results feed progression decisions
- Profile → FormaState: uses · Profile reads centralized app state
- WorkoutEngine → Curriculum: reads · Engine selects from curriculum structure
- WorkoutEngine → TrainingPlans: builds from · Engine assembles sessions from plan catalog
- DailyWorkout → Routines: reads · Daily selection comes from routine templates
- SessionState → Assessment: evaluates · Session state tracks performance assessment
- Progression → ProgressionRules: applies · Advancement logic uses progression rules
- Progression → Criteria: checks · Completion criteria gate progression
- FormaState → Storage: persists · Central state is saved locally
- FormaState → Migration: normalizes · Loaded state is migrated forward
- TrainingPlans → Exercises: references · Plans are composed from exercise definitions
- Exercises → Curriculum: aligns with · Exercise catalog supports the curriculum model
- Storage → Migration: upgrades · Stored data is normalized through migrations
- Vite → Deploy: supports · Build config and deployment workflow align on static output
