# wilsonckm/runtracker architecture

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

- Interactive diagram: https://gitdiagram.com/wilsonckm/runtracker
- Repository: https://github.com/wilsonckm/runtracker

## Overview

##### Overall Architecture and Main Components
- Application Core (RunTracker): Represent the Xcode project as the overall application boundary. Inside, break down the system into major layers:
- User Interface Layer
- Domain/Business Logic Layer
- Helpers/Utilities
- External Frameworks/Services

##### And Break Down the Components
a. User Interface (UI) / Presentation Layer:
- Views: Look inside the “Views” directory which includes various view types such as HomeView, HistoryView (with subcomponents like RunListView, RunListCell, RunDetailView), RunView (with NewRun, RunSummaryView), Onboarding, and Profile.
- MapView: This view displays the tracked route using MapKit.

b. Domain/Model Layer:
- Models: Located in the “Model” folder including files like Run.swift, Coordinates.swift, and LocationManager.swift.
- These classes capture and manage the core data related to the run tracking.
- Integration with frameworks: Clearly indicate that LocationManager uses CoreLocation to capture sensor data, and MapView leverages MapKit for visualizing the route.

c. Helpers & Components:
- Helpers: Files in the “Helper” directory (StringFormatHelper.swift, TextFormatHelper.swift) to format and manage string/text functionalities.
- Additional business logic components in the “Component” folder (RunStat.swift) which likely computes and encapsulates run statistics.

d. External Frameworks and Libraries:
- CoreLocation: For real-time location tracking.
- MapKit: For displaying the route on a map.
- SwiftData: For local data storage (as mentioned in the README regarding persistence challenges).
- SwiftUI: For building the entire UI.
- Future integration: HealthKit (as described in future updates).

##### Relationships and Interactions
- That the MapView component in the UI pulls data from the LocationManager and Run Model to build polylines with MapKit.
- Helpers/Components as utility classes that support both the UI and Model (e.g., formatting values, computing statistics).
- Local data storage through SwiftData and mention the decision against a full MVVM separation – note that only aggregate observable objects that provide state are used.

##### Architectural Patterns and Design Principles
- Although the project originally considered MVVM, the chosen “ModelView” approach means that the user interface directly interacts with observable objects and aggregate models; illustrate this by showing a simplified flow between views and models.

##### Overall Representation Suggestions
- Notes near each component to explain their roles (e.g., “LocationManager monitors GPS data via CoreLocation”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "iOS Device"
        direction TB
        %% User Interface Layer
        subgraph "User Interface Layer (SwiftUI Views)"
            direction TB
            UI_Root["SwiftUI Views"]:::ui
            UI_Root -->|"loads"| UI1["HomeView"]:::ui
            UI_Root -->|"loads"| UI2["RunView"]:::ui
            UI_Root -->|"loads"| UI5["HistoryView"]:::ui
            UI_Root -->|"loads"| UI9["OnboardingView"]:::ui
            UI_Root -->|"loads"| UI11["ProfileView"]:::ui
            UI_Root -->|"loads"| UI12["MapView"]:::ui

            subgraph "RunView"
                direction TB
                UI2
                UI3["RunSummaryView"]:::ui
                UI4["NewRun"]:::ui
                UI2 -->|"updates"| UI3
                UI2 -->|"triggers"| UI4
            end

            subgraph "HistoryView"
                direction TB
                UI5
                UI6["RunListView"]:::ui
                UI7["RunListCell"]:::ui
                UI8["RunDetailView"]:::ui
                UI5 -->|"contains"| UI6
                UI6 -->|"renders"| UI7
                UI6 -->|"selects"| UI8
            end

            subgraph "Onboarding"
                direction TB
                UI9
                UI10["OnboardingDetailView"]:::ui
                UI9 -->|"details"| UI10
            end
        end

        %% Domain/Model Layer
        subgraph "Domain/Model Layer"
            direction TB
            DM1["Run Model"]:::domain
            DM2["Coordinates"]:::domain
            DM3["LocationManager"]:::domain
            DM1 -->|"uses"| DM2
            %% LocationManager receives sensor data from CoreLocation (External)
            DM3 -->|"senses"| EX1["CoreLocation"]:::external
            %% Future integration: HealthKit provides additional data to Run Model
            DM1 -->|"future"| EX5["HealthKit (Future)"]:::external
            %% Persistence via SwiftData
            DM1 -->|"stores"| EX3["SwiftData"]:::external
        end

        %% Helpers & Business Logic
        subgraph "Helpers & Components"
            direction TB
            HP1["StringFormatHelper"]:::helper
            HP2["TextFormatHelper"]:::helper
            BL1["RunStat"]:::business
            %% Helpers assist UI for formatting
            HP1 -->|"formats"| UI1
            HP2 -->|"formats"| UI1
            %% Run Model computes statistics through RunStat
            DM1 -->|"calculates"| BL1
            BL1 -->|"provides"| UI2
        end

        %% External Frameworks & Services
        subgraph "External Frameworks & Services"
            direction TB
            EX1["CoreLocation"]:::external
            EX2["MapKit"]:::external
            EX3["SwiftData"]:::external
            EX4["SwiftUI"]:::external
            EX5["HealthKit (Future)"]:::external
            %% MapView leverages MapKit for route visualization
            UI12 -->|"renders map"| EX2
        end

        %% Interactions between UI and Domain components
        UI1 -->|"interacts"| DM1
        UI2 -->|"interacts"| DM1
        UI3 -->|"reflects"| DM1
        UI4 -->|"triggers update"| DM1
        UI5 -->|"displays data from"| DM1
        UI11 -->|"displays data from"| DM1
        UI12 -->|"requests route data"| DM1
        UI12 -->|"requests location"| DM3
    end

    %% Click Events for UI Layer
    click UI_Root "https://github.com/wilsonckm/runtracker/tree/main/RunTracker/Views"
    click UI1 "https://github.com/wilsonckm/runtracker/blob/main/RunTracker/Views/HomeView.swift"
    click UI2 "https://github.com/wilsonckm/runtracker/blob/main/RunTracker/Views/RunView/RunView.swift"
    click UI3 "https://github.com/wilsonckm/runtracker/blob/main/RunTracker/Views/RunView/RunSummaryView.swift"
    click UI4 "https://github.com/wilsonckm/runtracker/blob/main/RunTracker/Views/RunView/NewRun.swift"
    click UI5 "https://github.com/wilsonckm/runtracker/blob/main/RunTracker/Views/HistoryView/HistoryView.swift"
    click UI6 "https://github.com/wilsonckm/runtracker/blob/main/RunTracker/Views/HistoryView/RunListView.swift"
    click UI7 "https://github.com/wilsonckm/runtracker/blob/main/RunTracker/Views/HistoryView/RunListCell.swift"
    click UI8 "https://github.com/wilsonckm/runtracker/blob/main/RunTracker/Views/HistoryView/RunDetailView.swift"
    click UI9 "https://github.com/wilsonckm/runtracker/blob/main/RunTracker/Views/Onboarding/OnboardingView.swift"
    click UI10 "https://github.com/wilsonckm/runtracker/blob/main/RunTracker/Views/Onboarding/OnboardingDetailView.swift"
    click UI11 "https://github.com/wilsonckm/runtracker/blob/main/RunTracker/Views/Profile/ProfileView.swift"
    click UI12 "https://github.com/wilsonckm/runtracker/blob/main/RunTracker/MapView/MapView.swift"

    %% Click Events for Domain/Model Layer
    click DM1 "https://github.com/wilsonckm/runtracker/blob/main/RunTracker/Model/Run.swift"
    click DM2 "https://github.com/wilsonckm/runtracker/blob/main/RunTracker/Model/Coordinates.swift"
    click DM3 "https://github.com/wilsonckm/runtracker/blob/main/RunTracker/Model/LocationManager.swift"

    %% Click Events for Helpers & Components
    click HP1 "https://github.com/wilsonckm/runtracker/blob/main/RunTracker/Helper/StringFormatHelper.swift"
    click HP2 "https://github.com/wilsonckm/runtracker/blob/main/RunTracker/Helper/TextFormatHelper.swift"
    click BL1 "https://github.com/wilsonckm/runtracker/blob/main/RunTracker/Component/RunStat.swift"

    %% Styles
    classDef ui fill:#AEDFF7,stroke:#1E88E5,stroke-width:2px;
    classDef domain fill:#FFCDD2,stroke:#E53935,stroke-width:2px;
    classDef helper fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px;
    classDef external fill:#D1C4E9,stroke:#7E57C2,stroke-width:2px;
    classDef business fill:#C5E1A5,stroke:#7CB342,stroke-width:2px;
```
