# jefffleurima/set-ai-fitness-coach architecture

> Architecture diagram of the GitHub repository jefffleurima/set-ai-fitness-coach, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jefffleurima/set-ai-fitness-coach
- Repository: https://github.com/jefffleurima/set-ai-fitness-coach

## Overview

1. **Product shape**
   PeakSet is an iOS SwiftUI app centered on three user-facing loops: live exercise analysis, AI coaching, and fitness/activity tracking. The codebase is organized as a single app target with feature folders rather than separate services, so the main architecture is client-side and state-driven.

2. **App entry and UI shell**
   `PeakSetApp.swift` is the app entry point, with `ContentView.swift` acting as the root shell. The UI appears to branch into major screens such as welcome/onboarding, workout/exercise, messages, health details, summary, and terms acceptance, likely composed through SwiftUI navigation/tab patterns.

3. **Core feature domains**
   The repo is split into three primary domains:  
   - `AR/` for camera-based form analysis and mirrored workout view  
   - `Voice/` for wake-word detection, audio session control, and spoken responses  
   - `Models/` plus `ViewModels/` for data and orchestration  
   This separation is the main architectural boundary: sensor/input handling, AI/voice intelligence, and presentation/state.

4. **Form analysis pipeline**
   The `AR` folder contains the real-time workout analysis stack: `MirrorViewController`, `MirrorViewWrapper`, `SkeletonOverlayView`, and `FormAnalyzer`. Despite the name, the README indicates this is Vision-based 2D pose analysis rather than full ARKit scene tracking. The pipeline is camera input → pose detection/form scoring → overlay rendering → workout feedback.

5. **Voice assistant subsystem**
   The voice stack is split into `AudioSessionManager` for audio coordination, `VoiceAssistantManager` for conversational flow, and `ElevenLabsVoiceManager` for speech synthesis. The README describes a wake-word driven assistant (“Hey Rex”) using Picovoice Porcupine, with fallback behavior and simulator support, so the voice subsystem is a self-contained interaction engine that manages listening, speaking, and interruptions.

6. **AI coaching and conversation**
   `Models/OpenAIClient.swift` and `ViewModels/AICoachViewModel.swift` form the AI coaching boundary. The client likely handles calls to OpenAI for fitness advice, while the view model converts app state and workout context into user-facing coaching feedback. `AICoachFeedback.swift` is the main response model passed back into the UI and/or voice layer.

7. **Exercise and workout domain model**
   `Models/Exercise.swift` appears to define the exercise library and its form criteria, safety notes, and scoring rules. This model is the bridge between pose analysis and coaching: the analyzer judges movement against exercise-specific rules, and the coach explains what to improve.

8. **Health and activity tracking**
   `Models/HealthKitManager.swift` is the HealthKit integration boundary. It likely owns permissions, data fetching, and aggregation for steps, calories, distance, and workout history. The UI layer then reads this state through views such as `HealthDetailViews.swift` and `SummaryView.swift`, which present Apple Fitness-style progress views and trends.

9. **Screen-level presentation**
   The `Views/` folder is organized by feature screens rather than generic components: workout display, messages/chat, summary, onboarding, legal terms, and health details. This suggests the app surfaces multiple modes from one root state machine: first-run consent, live coaching, post-session review, and daily progress review.

10. **Design system and configuration**
   `Theme/AppTheme.swift` and `Assets.xcassets` provide the visual system: colors, app icons, and surface/text palettes. `Config.swift` and `Config.template.swift`, plus `Info.template.plist`, indicate runtime configuration is injected at build/setup time rather than hardcoded, especially for API keys and environment-specific settings.

11. **External dependencies and runtime boundaries**
   The important external services are OpenAI for coaching text, ElevenLabs for spoken output, HealthKit for fitness data, Vision for pose detection, Picovoice for wake-word detection, and Apple audio/speech frameworks for session and recognition handling. These are the main integration boundaries that determine app behavior and should appear as separate external systems in an architecture diagram.

12. **Security, permissions, and distribution constraints**
   The presence of `PeakSet.entitlements`, template plist/config files, and the README’s beta/legal language implies the app depends on camera, microphone, speech, and HealthKit permissions, with API keys kept out of source control. The app is built as a beta iOS client, so operational concerns are mostly local-device privacy, audio session reliability, and safe handling of biometric/workout data rather than server-side scalability.

Main entry points: [`PeakSet/ContentView.swift`](https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/ContentView.swift) (Root shell), [`PeakSet/Voice/VoiceAssistantManager.swift`](https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Voice/VoiceAssistantManager.swift) (Assistant flow), [`PeakSet/ViewModels/AICoachViewModel.swift`](https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/ViewModels/AICoachViewModel.swift) (Coach VM), [`PeakSet/AR/FormAnalyzer.swift`](https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/AR/FormAnalyzer.swift) (Form analyzer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_peakset_app["PeakSetApp<br/>entry point<br/>[PeakSetApp.swift]"]
  node_content_view["Root shell<br/>swiftui shell<br/>[ContentView.swift]"]
end

subgraph group_analysis["Workout analysis"]
  node_mirror_vc["Mirror camera<br/>camera view controller"]
  node_mirror_wrapper["Mirror wrapper<br/>SwiftUI bridge"]
  node_skeleton_overlay["Pose overlay<br/>overlay view"]
  node_form_analyzer["Form analyzer<br/>analysis engine<br/>[FormAnalyzer.swift]"]
end

subgraph group_voice["Voice assistant"]
  node_audio_session["Audio session<br/>audio coordinator"]
  node_voice_assistant["Assistant flow<br/>conversation engine"]
  node_voice_synth["Voice output<br/>speech synthesis"]
end

subgraph group_coach["AI coaching"]
  node_coach_vm["Coach VM<br/>view model"]
  node_openai_client["OpenAI client<br/>[OpenAIClient.swift]"]
  node_feedback_model["Coach feedback<br/>response model"]
end

subgraph group_tracking["Activity tracking"]
  node_health_manager[("HealthKit manager<br/>health integration")]
end

subgraph group_ui["Screens"]
  node_welcome_view["Welcome<br/>onboarding screen"]
  node_exercise_view["Workout screen<br/>[ExerciseView.swift]"]
  node_messages_view["Messages<br/>chat screen<br/>[MessagesView.swift]"]
  node_health_views["Health details<br/>progress screens"]
  node_summary_view["Summary<br/>review screen<br/>[SummaryView.swift]"]
  node_terms_view["Terms<br/>legal screen"]
end

subgraph group_shared["Shared model/config"]
  node_exercise_model["Exercise model<br/>domain model<br/>[Exercise.swift]"]
  node_app_theme["App theme<br/>design system<br/>[AppTheme.swift]"]
  node_config["Config<br/>[Config.swift]"]
end

subgraph group_external["External systems"]
  node_openai_ext(("OpenAI<br/>external service"))
  node_elevenlabs_ext(("ElevenLabs<br/>external service"))
  node_healthkit_ext(("HealthKit<br/>platform API"))
  node_vision_ext(("Vision<br/>platform API"))
  node_picovoice_ext(("Picovoice<br/>wake-word SDK"))
  node_apple_audio_ext(("Audio/Speech<br/>platform API"))
end

node_peakset_app -->|"boots"| node_content_view
node_content_view -->|"routes"| node_welcome_view
node_content_view -->|"routes"| node_exercise_view
node_content_view -->|"routes"| node_messages_view
node_content_view -->|"routes"| node_health_views
node_content_view -->|"routes"| node_summary_view
node_content_view -->|"routes"| node_terms_view
node_exercise_view -->|"hosts"| node_mirror_wrapper
node_mirror_wrapper -->|"bridges"| node_mirror_vc
node_mirror_vc -->|"feeds"| node_form_analyzer
node_form_analyzer -->|"drives"| node_skeleton_overlay
node_form_analyzer -->|"uses"| node_exercise_model
node_exercise_view -->|"requests"| node_coach_vm
node_coach_vm -->|"calls"| node_openai_client
node_openai_client -->|"uses"| node_openai_ext
node_coach_vm -->|"produces"| node_feedback_model
node_voice_assistant -->|"controls"| node_audio_session
node_voice_assistant -->|"speaks"| node_voice_synth
node_voice_assistant -->|"requests"| node_coach_vm
node_voice_assistant -->|"listens"| node_picovoice_ext
node_voice_synth -->|"uses"| node_elevenlabs_ext
node_audio_session -->|"uses"| node_apple_audio_ext
node_health_views -->|"reads"| node_health_manager
node_health_manager -->|"uses"| node_healthkit_ext
node_health_manager -->|"feeds"| node_summary_view
node_app_theme -->|"styles"| node_content_view
node_config -->|"configures"| node_openai_client
node_config -->|"configures"| node_voice_synth
node_config -->|"configures"| node_health_manager
node_exercise_model -->|"context"| node_coach_vm
node_exercise_model -->|"rules"| node_form_analyzer
node_feedback_model -->|"renders"| node_messages_view
node_feedback_model -->|"reads"| node_voice_assistant
node_mirror_vc -->|"uses"| node_vision_ext

click node_peakset_app "https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/PeakSetApp.swift"
click node_content_view "https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/ContentView.swift"
click node_mirror_vc "https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/AR/MirrorViewController.swift"
click node_mirror_wrapper "https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/AR/MirrorViewWrapper.swift"
click node_skeleton_overlay "https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/AR/SkeletonOverlayView.swift"
click node_form_analyzer "https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/AR/FormAnalyzer.swift"
click node_audio_session "https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Voice/AudioSessionManager.swift"
click node_voice_assistant "https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Voice/VoiceAssistantManager.swift"
click node_voice_synth "https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Voice/ElevenLabsVoiceManager.swift"
click node_coach_vm "https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/ViewModels/AICoachViewModel.swift"
click node_openai_client "https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Models/OpenAIClient.swift"
click node_feedback_model "https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Models/AICoachFeedback.swift"
click node_exercise_model "https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Models/Exercise.swift"
click node_health_manager "https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Models/HealthKitManager.swift"
click node_welcome_view "https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Views/WelcomeScreenView.swift"
click node_exercise_view "https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Views/ExerciseView.swift"
click node_messages_view "https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Views/MessagesView.swift"
click node_health_views "https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Views/HealthDetailViews.swift"
click node_summary_view "https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Views/SummaryView.swift"
click node_terms_view "https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Views/TermsAndConditionsView.swift"
click node_app_theme "https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Theme/AppTheme.swift"
click node_config "https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Config.swift"

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_peakset_app,node_content_view,node_exercise_model,node_app_theme,node_config toneBlue
class node_mirror_vc,node_mirror_wrapper,node_skeleton_overlay,node_form_analyzer,node_openai_ext,node_elevenlabs_ext,node_healthkit_ext,node_vision_ext,node_picovoice_ext,node_apple_audio_ext toneAmber
class node_audio_session,node_voice_assistant,node_voice_synth toneMint
class node_coach_vm,node_openai_client,node_feedback_model toneRose
class node_health_manager toneIndigo
class node_welcome_view,node_exercise_view,node_messages_view,node_health_views,node_summary_view,node_terms_view toneTeal
```

## Components

### App shell

Root SwiftUI entry point and screen orchestration.

- [PeakSetApp](https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/PeakSetApp.swift): entry point · SwiftUI app entry and lifecycle bootstrap. · `PeakSet/PeakSetApp.swift`
- [Root shell](https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/ContentView.swift): swiftui shell · Top-level UI container that routes into major app flows. · `PeakSet/ContentView.swift`

### Workout analysis

Camera-based form analysis and mirrored workout UI.

- [Mirror camera](https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/AR/MirrorViewController.swift): camera view controller · Hosts the live workout camera and pose-driven mirror experience. · `PeakSet/AR/MirrorViewController.swift`
- [Mirror wrapper](https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/AR/MirrorViewWrapper.swift): SwiftUI bridge · Bridges the camera controller into SwiftUI. · `PeakSet/AR/MirrorViewWrapper.swift`
- [Pose overlay](https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/AR/SkeletonOverlayView.swift): overlay view · Renders skeleton and form feedback on top of the camera feed. · `PeakSet/AR/SkeletonOverlayView.swift`
- [Form analyzer](https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/AR/FormAnalyzer.swift): analysis engine · Evaluates pose data against exercise-specific criteria. · `PeakSet/AR/FormAnalyzer.swift`

### Voice assistant

Wake-word listening, audio session, and spoken responses.

- [Audio session](https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Voice/AudioSessionManager.swift): audio coordinator · Manages microphone and playback session behavior. · `PeakSet/Voice/AudioSessionManager.swift`
- [Assistant flow](https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Voice/VoiceAssistantManager.swift): conversation engine · Coordinates wake-word listening, interruptions, and dialogue state. · `PeakSet/Voice/VoiceAssistantManager.swift`
- [Voice output](https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Voice/ElevenLabsVoiceManager.swift): speech synthesis · Generates spoken responses for the assistant. · `PeakSet/Voice/ElevenLabsVoiceManager.swift`

### AI coaching

OpenAI-backed feedback generation and coaching state.

- [Coach VM](https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/ViewModels/AICoachViewModel.swift): view model · Builds coaching context and drives AI feedback in the UI. · `PeakSet/ViewModels/AICoachViewModel.swift`
- [OpenAI client](https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Models/OpenAIClient.swift): AI client · Sends coaching prompts and receives guidance responses. · `PeakSet/Models/OpenAIClient.swift`
- [Coach feedback](https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Models/AICoachFeedback.swift): response model · Structured AI feedback consumed by views and voice. · `PeakSet/Models/AICoachFeedback.swift`

### Activity tracking

HealthKit integration and progress presentation.

- [HealthKit manager](https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Models/HealthKitManager.swift): health integration · Owns permissions and workout/activity data access. · `PeakSet/Models/HealthKitManager.swift`

### Screens

Primary feature screens and flows.

- [Welcome](https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Views/WelcomeScreenView.swift): onboarding screen · First-run onboarding and entry consent flow. · `PeakSet/Views/WelcomeScreenView.swift`
- [Workout screen](https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Views/ExerciseView.swift): live workout screen · Primary exercise and coaching experience. · `PeakSet/Views/ExerciseView.swift`
- [Messages](https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Views/MessagesView.swift): chat screen · Conversation and assistant message UI. · `PeakSet/Views/MessagesView.swift`
- [Health details](https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Views/HealthDetailViews.swift): progress screens · Fitness metrics and activity detail views. · `PeakSet/Views/HealthDetailViews.swift`
- [Summary](https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Views/SummaryView.swift): review screen · Post-session and progress summary presentation. · `PeakSet/Views/SummaryView.swift`
- [Terms](https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Views/TermsAndConditionsView.swift): legal screen · Terms and conditions acceptance flow. · `PeakSet/Views/TermsAndConditionsView.swift`

### Shared model/config

Cross-cutting models, theming, and runtime config.

- [Exercise model](https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Models/Exercise.swift): domain model · Defines exercises, form rules, and scoring context. · `PeakSet/Models/Exercise.swift`
- [App theme](https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Theme/AppTheme.swift): design system · Shared colors and visual styling tokens. · `PeakSet/Theme/AppTheme.swift`
- [Config](https://github.com/jefffleurima/set-ai-fitness-coach/blob/main/PeakSet/Config.swift): runtime config · Build-time injected app and API configuration. · `PeakSet/Config.swift`

### External systems

Third-party and Apple platform dependencies.

- **OpenAI**: external service · Generative coaching backend.
- **ElevenLabs**: external service · Spoken voice generation backend.
- **HealthKit**: platform API · Apple health and activity framework.
- **Vision**: platform API · Pose detection and image analysis framework.
- **Picovoice**: wake-word SDK · Wake-word detection and listener runtime.
- **Audio/Speech**: platform API · Apple audio session and speech frameworks.

## Connections

- PeakSetApp → Root shell: boots · App entry creates the root shell.
- Root shell → Welcome: routes · Initial onboarding and first-run flow.
- Root shell → Workout screen: routes · Main live workout experience.
- Root shell → Messages: routes · Assistant conversation screen.
- Root shell → Health details: routes · Activity and health detail screens.
- Root shell → Summary: routes · Session summary and review flow.
- Root shell → Terms: routes · Consent acceptance flow.
- Workout screen → Mirror wrapper: hosts · Embeds the mirrored camera experience.
- Mirror wrapper → Mirror camera: bridges · Connects SwiftUI to camera controller.
- Mirror camera → Form analyzer: feeds · Camera frames are evaluated for form.
- Form analyzer → Pose overlay: drives · Analysis results render as overlay feedback.
- Form analyzer → Exercise model: uses · Exercise rules define scoring and criteria.
- Workout screen → Coach VM: requests · Workout screen asks for coaching feedback.
- Coach VM → OpenAI client: calls · View model prepares prompts and sends them to AI.
- OpenAI client → OpenAI: uses · External generative coaching service.
- Coach VM → Coach feedback: produces · Structured feedback returned to the UI.
- Assistant flow → Audio session: controls · Conversation flow manages audio lifecycle.
- Assistant flow → Voice output: speaks · Assistant sends spoken replies to synthesis.
- Assistant flow → Coach VM: requests · Voice mode can surface coaching feedback.
- Assistant flow → Picovoice: listens · Wake-word detection via Picovoice.
- Voice output → ElevenLabs: uses · Speech generation backend.
- Audio session → Audio/Speech: uses · Apple audio session and speech frameworks.
- Health details → HealthKit manager: reads · Health screens consume tracked activity data.
- HealthKit manager → HealthKit: uses · HealthKit permissions and data access.
- HealthKit manager → Summary: feeds · Aggregated activity data powers summaries.
- App theme → Root shell: styles · Shared visual system applied across the shell.
- Config → OpenAI client: configures · API/runtime settings for coaching services.
- Config → Voice output: configures · Runtime credentials and service settings.
- Config → HealthKit manager: configures · Environment-dependent health behavior.
- Exercise model → Coach VM: context · Exercise definitions shape coaching prompts.
- Exercise model → Form analyzer: rules · Analyzer compares motion against exercise criteria.
- Coach feedback → Messages: renders · Feedback is surfaced in the chat UI.
- Coach feedback → Assistant flow: reads · Assistant can vocalize structured feedback.
- Mirror camera → Vision: uses · Pose detection and image analysis framework.
