# conorzen/fitkit architecture

> Architecture diagram of the GitHub repository conorzen/fitkit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/conorzen/fitkit
- Repository: https://github.com/conorzen/fitkit

## Overview

##### Project Type and Purpose
- This is a full‑stack mobile/watchOS fitness application (“WatchFit”) featuring:
- A watchOS frontend that tracks workouts via Apple’s WorkoutKit & HealthKit.
- An iOS companion app for settings, history, and analytics.
- A cloud backend (Supabase) for user authentication, training‑plan storage and sync.
- Local persistence (Core Data) for offline caching of workouts, user data.
- A WatchConnectivity channel to sync data between watch and phone.

##### File Structure
- Top‑level “run.xcodeproj” / “run” directory holds Swift code.
- “Assets.xcassets”, “Info.plist”, “runApp.swift” – entrypoint & app metadata.
- “Models” – Core Data entities & domain models (RecentRun, TrainingPlan, User).
- “Persistence.swift” + “run.xcdatamodeld” – Core Data stack.
- “Services” – AuthManager (Supabase auth), TrainingPlanService (REST calls), SupabaseConfig.
- “HKM” – HealthKitManager, workout configuration extension.
- “WatchConnectivity” – WatchSessionManager to sync between watchOS & iOS.
- “Views” – SwiftUI views, organized by feature (AuthenticationView, RunningView, CalendarView, SettingsView).
- “ThemeManager.swift” – UI theming.
- “runTests” / “runUITests” – unit & UI tests.

##### README for Additional Insights
- Leverages WorkoutKit & HealthKit for real‑time metrics.
- Uses Supabase as cloud backend (auth, data storage).

a. Main Components:
1. WatchOS App (UI Layer)
2. iOS Companion App (UI Layer)
3. Core Data Persistence Layer (Persistence.swift + run.xcdatamodeld)
4. HealthKit / WorkoutKit Frameworks (Apple SDKs)
5. Supabase Backend (Auth + Database)
6. WatchConnectivity Service
7. Local Models & Service Layer (AuthManager, TrainingPlanService, HealthKitManager)
b. Relationships & Interactions:
- WatchOS UI ⇄ HealthKitManager (WorkoutKit data capture)
- WatchOS UI ⇄ WatchSessionManager ⇄ iOS Companion UI (sync workout data & plans)
- Both WatchOS & iOS Apps ⇄ Persistence Layer (read/write Core Data)
- iOS App ⇄ Supabase (via AuthManager & TrainingPlanService for remote user data + plans)
- iOS App ⇄ HealthKitManager (to read/write Health data on phone)
c. Architectural Patterns & Principles:
- MVVM (SwiftUI Views bound to Models via @StateObject/ViewModel)
- Repository/Service Layer for external dependencies (HealthKit, Supabase)
- Single Source of Truth in Core Data
- Separation of Concerns: UI / Domain Models / Services / Persistence
d. Relevant Technologies:
- SwiftUI (UI)
- Apple WatchKit, HealthKit, WorkoutKit
- Core Data (Persistence)
- Supabase (Backend as a Service)
- WatchConnectivity Framework
- Combine (data binding, if used)

##### Elements
- Clear labels: e.g., “WatchOS App UI”, “HealthKitManager Service”, “Core Data Store”
– Data flow from WorkoutKit → WatchOS UI → Persistence → Supabase
– Client components (blue rectangles)
- Notes on authentication flow: Show OAuth token exchange with Supabase via AuthManager.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Applications
    subgraph "Client Apps"
        direction TB
        subgraph "WatchOS App"
            direction TB
            WatchUI["WatchOS App UI"]:::client
            WKManager["HealthKitManager Service"]:::service
            WorkoutExt["HKWorkoutConfiguration+Displaying"]:::service
            WatchSession["WatchSessionManager Service"]:::service
            Persistence["Core Data Store"]:::persistence
            ThemeMgr["ThemeManager"]:::service
            AppEntry["runApp.swift & Info.plist"]:::client
            Assets["Assets.xcassets"]:::client
        end
        subgraph "iOS Companion App"
            direction TB
            IOSUI["iOS App UI"]:::client
            AuthMgr["AuthManager Service"]:::service
            PlanSvc["TrainingPlanService"]:::service
            SupabaseCfg["SupabaseConfig"]:::service
            HealthMgr["HealthKitManager Service"]:::service
            Persistence2["Core Data Store"]:::persistence
            Models["Local Models & Entities"]:::service
            ThemeMgr2["ThemeManager"]:::service
            AppEntry2["runApp.swift & Info.plist"]:::client
            Assets2["Assets.xcassets"]:::client
        end
    end

    %% Local Data Layer
    LocalModels["Models (RecentRun, TrainingPlan, User)"]:::service

    %% Supabase Backend
    subgraph "Supabase Backend"
        direction TB
        AuthSvc["Authentication Service"]:::external
        DB["Database"]:::external
    end

    %% External Frameworks
    WorkoutKitExt["WorkoutKit & HealthKit Frameworks"]:::external

    %% Data Flows
    WatchUI -->|"capture workout"| WKManager
    WKManager -->|"configures"| WorkoutExt
    WatchUI -->|"save/load"| Persistence
    WatchSession -->|"sync data"| WatchUI
    WatchSession -->|"sync data"| IOSUI
    IOSUI -->|"binds UI"| Models
    IOSUI -->|"authenticate"| AuthMgr
    IOSUI -->|"fetch/plans"| PlanSvc
    AuthMgr -->|"OAuth token"| AuthSvc
    PlanSvc -->|"REST API calls"| DB
    IOSUI -->|"read/write"| Persistence2
    IOSUI -->|"read/write"| HealthMgr
    Models --> Persistence
    Models --> Persistence2
    Models --> WKManager
    Models --> HealthMgr
    HealthMgr -->|"uses"| WorkoutKitExt

    %% Click Events
    click WatchUI "https://github.com/conorzen/fitkit/blob/main/run/Views/RunningView.swift"
    click WatchUI "https://github.com/conorzen/fitkit/blob/main/run/Views/AuthenticationView.swift"
    click WatchUI "https://github.com/conorzen/fitkit/blob/main/run/Views/CalendarView.swift"
    click WatchUI "https://github.com/conorzen/fitkit/blob/main/run/Views/SettingsView.swift"
    click WatchUI "https://github.com/conorzen/fitkit/blob/main/run/Views/ContentView.swift"
    click IOSUI "https://github.com/conorzen/fitkit/blob/main/run/Views/RunningView.swift"
    click IOSUI "https://github.com/conorzen/fitkit/blob/main/run/Views/AuthenticationView.swift"
    click IOSUI "https://github.com/conorzen/fitkit/blob/main/run/Views/CalendarView.swift"
    click IOSUI "https://github.com/conorzen/fitkit/blob/main/run/Views/SettingsView.swift"
    click IOSUI "https://github.com/conorzen/fitkit/blob/main/run/Views/ContentView.swift"
    click Persistence "https://github.com/conorzen/fitkit/blob/main/run/Persistence.swift"
    click Persistence "https://github.com/conorzen/fitkit/blob/main/run/run.xcdatamodeld/run.xcdatamodel"
    click WKManager "https://github.com/conorzen/fitkit/blob/main/run/HKM/HealthKitManager.swift"
    click WorkoutExt "https://github.com/conorzen/fitkit/tree/main/run/HKM/HKWorkoutConfiguration+Displaying"
    click AuthMgr "https://github.com/conorzen/fitkit/blob/main/run/Services/AuthManager.swift"
    click SupabaseCfg "https://github.com/conorzen/fitkit/blob/main/run/SupabaseConfig.swift"
    click PlanSvc "https://github.com/conorzen/fitkit/blob/main/run/Services/TrainingPlanService.swift"
    click Models "https://github.com/conorzen/fitkit/blob/main/run/Models/RecentRun.swift"
    click Models "https://github.com/conorzen/fitkit/blob/main/run/Models/TrainingPlan.swift"
    click Models "https://github.com/conorzen/fitkit/blob/main/run/Models/User.swift"
    click Models "https://github.com/conorzen/fitkit/blob/main/run/Models/WorkoutStore.swift"
    click WatchSession "https://github.com/conorzen/fitkit/blob/main/run/WatchConnectivity/WatchSessionManager.swift"
    click ThemeMgr "https://github.com/conorzen/fitkit/blob/main/run/ThemeManager.swift"
    click AppEntry "https://github.com/conorzen/fitkit/blob/main/run/runApp.swift"
    click AppEntry "https://github.com/conorzen/fitkit/blob/main/run/Info.plist"
    click Assets "https://github.com/conorzen/fitkit/blob/main/run/Assets.xcassets"
    click Assets2 "https://github.com/conorzen/fitkit/blob/main/run/Assets.xcassets"

    %% Styles
    classDef client fill:#cce5ff,stroke:#004085
    classDef service fill:#d4edda,stroke:#155724
    classDef persistence fill:#fff3cd,stroke:#856404
    classDef external fill:#f8d7da,stroke:#721c24
```
