How jefffleurima/set-ai-fitness-coach works
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: ContentView.swift Root shell · VoiceAssistantManager.swift Assistant flow · AICoachViewModel.swift Coach VM · FormAnalyzer.swift Form analyzer
Components 28
App shell
Root SwiftUI entry point and screen orchestration.
- PeakSetApp · SwiftUI app entry and lifecycle bootstrap.
PeakSet/PeakSetApp.swift - Root 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 · Hosts the live workout camera and pose-driven mirror experience.
PeakSet/AR/MirrorViewController.swift - Mirror wrapper · Bridges the camera controller into SwiftUI.
PeakSet/AR/MirrorViewWrapper.swift - Pose overlay · Renders skeleton and form feedback on top of the camera feed.
PeakSet/AR/SkeletonOverlayView.swift - Form analyzer · Evaluates pose data against exercise-specific criteria.
PeakSet/AR/FormAnalyzer.swift
Voice assistant
Wake-word listening, audio session, and spoken responses.
- Audio session · Manages microphone and playback session behavior.
PeakSet/Voice/AudioSessionManager.swift - Assistant flow · Coordinates wake-word listening, interruptions, and dialogue state.
PeakSet/Voice/VoiceAssistantManager.swift - Voice output · Generates spoken responses for the assistant.
PeakSet/Voice/ElevenLabsVoiceManager.swift
AI coaching
OpenAI-backed feedback generation and coaching state.
- Coach VM · Builds coaching context and drives AI feedback in the UI.
PeakSet/ViewModels/AICoachViewModel.swift - OpenAI client · Sends coaching prompts and receives guidance responses.
PeakSet/Models/OpenAIClient.swift - Coach feedback · Structured AI feedback consumed by views and voice.
PeakSet/Models/AICoachFeedback.swift
Activity tracking
HealthKit integration and progress presentation.
- HealthKit manager · Owns permissions and workout/activity data access.
PeakSet/Models/HealthKitManager.swift
Screens
Primary feature screens and flows.
- Welcome · First-run onboarding and entry consent flow.
PeakSet/Views/WelcomeScreenView.swift - Workout screen · Primary exercise and coaching experience.
PeakSet/Views/ExerciseView.swift - Messages · Conversation and assistant message UI.
PeakSet/Views/MessagesView.swift - Health details · Fitness metrics and activity detail views.
PeakSet/Views/HealthDetailViews.swift - Summary · Post-session and progress summary presentation.
PeakSet/Views/SummaryView.swift - Terms · Terms and conditions acceptance flow.
PeakSet/Views/TermsAndConditionsView.swift
Shared model/config
Cross-cutting models, theming, and runtime config.
- Exercise model · Defines exercises, form rules, and scoring context.
PeakSet/Models/Exercise.swift - App theme · Shared colors and visual styling tokens.
PeakSet/Theme/AppTheme.swift - Config · Build-time injected app and API configuration.
PeakSet/Config.swift
External systems
Third-party and Apple platform dependencies.
- OpenAI · Generative coaching backend.
- ElevenLabs · Spoken voice generation backend.
- HealthKit · Apple health and activity framework.
- Vision · Pose detection and image analysis framework.
- Picovoice · Wake-word detection and listener runtime.
- Audio/Speech · Apple audio session and speech frameworks.
Connections 34
- 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.