How saabithe/forma works
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: App.jsx App · WorkoutSession.jsx WorkoutSession · useFormaState.js FormaState · Layout.jsx Layout
Components 33
Delivery
Build and automated static deployment
Runtime
App entry and bootstrap
- index.html · Vite entry document
index.html - main.jsx · Mounts the React app
src/main.jsx - App · Top-level application composition
src/App.jsx
Presentation
Shared shell, navigation, and reusable UI
- Theme · App-wide theme state
src/theme/ThemeContext.jsx - Layout · Primary chrome and page frame
src/components/Layout.jsx - TabBar · Primary navigation control
src/components/TabBar.jsx - ExerciseCard · Reusable workout item display
src/components/ExerciseCard.jsx - CriteriaTracker · Shows session criteria and completion
src/components/CriteriaTracker.jsx - LevelUpModal · Milestone and advancement feedback
src/components/LevelUpModal.jsx - ThemeToggle · User-facing theme switch
src/components/ThemeToggle.jsx
Views
Major user-facing screens
- Home · Entry point into the app
src/pages/Home.jsx - Onboarding · Initial user setup and preferences
src/pages/Onboarding.jsx - WorkoutSession · Active workout execution screen
src/pages/WorkoutSession.jsx - Results · Post-session outcome and summary
src/pages/Results.jsx - Profile · User progress and state overview
src/pages/Profile.jsx - Roadmap · Long-term skill and curriculum navigation
src/pages/Roadmap.jsx - SkillDetail · Focused skill breakdown and requirements
src/pages/SkillDetail.jsx
Engine
Session orchestration and progression logic
- WorkoutEngine · Assembles sessions from plans and rules
src/hooks/useWorkoutEngine.js - SessionState · Manages live workout session state
src/hooks/useWorkoutSession.js - DailyWorkout · Selects the day’s workout
src/hooks/useDailyWorkout.js - Progression · Coordinates advancement logic
src/hooks/useProgression.js - FormaState · Centralized app state orchestration
src/hooks/useFormaState.js
Content
Curriculum, plans, exercises, and persistence rules
- Curriculum · Core skill progression model
src/data/curriculum.js - TrainingPlans · Plan variants by level and support
src/data/training-plans/index.js - Exercises · Holds, reps, and mobility definitions
src/data/exercises/index.js - Routines · Daily workout templates
src/data/daily-routines.js - Assessment · Evaluates workout performance
src/lib/assessment.js - Criteria · Defines completion criteria
src/lib/criteria.js - ProgressionRules · Advancement and level logic
src/lib/progression.js - Storage · Browser storage access
src/lib/storage.js - Migration · Normalizes older saved state
src/lib/migration.js
Connections 34
- 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