# daneden/solstice architecture

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

- Interactive diagram: https://gitdiagram.com/daneden/solstice
- Repository: https://github.com/daneden/solstice

## Overview

##### Project type and purpose
- Solstice is a native SwiftUI-based iOS/macOS/watchOS/mobile app with a WidgetKit extension, a Siri Intents extension, and a RealityKit Swift package. Its core purpose is to compute and display daylight metrics (sunrise, sunset, total daylight) to improve mental health awareness. It persists user data (saved locations, settings) with Core Data, provides home-screen widgets, watchOS support, and Siri shortcuts, and includes an optional in-app purchase tip.

##### File structure
- Top-level targets:
– Solstice (iOS/macOS main app)
– Widget (WidgetKit extension with three widget types: Countdown, Overview, Solar Chart)
– watchOS (watchOS SwiftUI app)
– Intents (SiriKit shortcuts provider)
– Packages/RealityKitContent (SwiftPM package for 3D Earth model and assets)
- Core Data model under Data Model (Persistence.swift + .xcdatamodeld).
- Helpers and Services under Helpers (e.g., SolsticeCalculator, LocationSearchService, NotificationManager).
- UI under Solstice folder (Views, Charts, Detail View, List View, Settings, Helper Views, Extensions).
- WidgetKit timelines under Widget/…WidgetTimelineProvider.
- Localizable.strings, Info.plist, StoreKitConfiguration for IAP.

##### Extract architecture hints from README
- Emphasis on open-source, healthcare/mental-health use case, always free, with optional In-App Purchase tip.
- No prescribed architecture, but file tree suggests MVVM (Views + business logic + persistence).

– Mobile App Target (“Solstice App”)
– Widget Extension
– watchOS App
– Siri Intents Extension
– RealityKitContent Package (shared 3D assets)
– Core Data Persistence (Solstice.xcdatamodeld + defaultData.json)
– External Services/System APIs: Location Services (CLLocation), Notifications (UNUserNotificationCenter), SiriKit, StoreKit
– Solstice App UI → ViewModels/Helpers → SolsticeCalculator → Persistence
– Helpers (LocationSearchService) ↔ Core Location API
– Helpers (NotificationManager) ↔ UserNotification API
– Widget Extension ← shared data container ← Persistence (via App Group)
– watchOS App ← shared code (Helpers + Persistence)
– Intents Extension ← reads from Persistence + invokes SolsticeCalculator → returns data to Siri
– RealityKitContent Package → used by EquinoxInfoView for 3D rendering
– In-App Purchase UI → StoreKit → Apple servers
c. Architectural patterns/design principles:
– MVVM: SwiftUI Views bind to business logic in Helpers/Services (ViewModels implicitly via @StateObject / @ObservedObject).
– Modular targets: each feature (widgets, watchOS, Siri) lives in its own extension sharing core modules.
– Shared persistence via App Groups for cross-target data.
– Swift Package for 3D content to decouple large assets.
– Functional composition: many View+Modifiers extensions.
d. Key technologies/frameworks:
– SwiftUI & Combine (UI + reactive data binding)
– Core Data (persistence)
– WidgetKit (home-screen widgets)
– SiriKit Intents (shortcuts providers)
– RealityKit (3D Earth model)
– StoreKit (in-app tips)
– Core Location & UserNotifications

– Blue rectangles for App Targets
– Yellow parallelograms for shared packages (RealityKitContent)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "App Targets"
        SA["Solstice App"]:::appTargets
        WE["Widget Extension"]:::appTargets
        WA["watchOS App"]:::appTargets
        IE["Intents Extension"]:::appTargets
    end

    subgraph "Shared Modules"
        HM["Helpers/Services"]:::shared
        UD["UI Views"]:::shared
        EXV["Extensions"]:::shared
        RP["RealityKitContent Package"]:::shared
    end

    PD["Core Data Persistence"]:::persistence

    subgraph "External Services/APIs"
        LOC["Location Services (CLLocation)"]:::external
        NOTF["UserNotifications"]:::external
        SIRI["SiriKit"]:::external
        STORE["StoreKit"]:::external
    end

    SA -->|"binds to"| HM
    SA -->|"uses"| UD
    SA -->|"applies"| EXV
    SA -->|"renders 3D"| RP
    SA -->|"reads/writes"| PD
    SA -->|"in-app tip"| STORE

    HM -->|"queries"| LOC
    HM -->|"schedules"| NOTF

    WE -->|"reads shared data"| PD

    WA -->|"uses shared code"| HM
    WA -->|"reads/writes"| PD

    IE -->|"reads"| PD
    IE -->|"invokes calculator"| HM
    IE -->|"responds via"| SIRI

    RP -->|"used by EquinoxInfoView"| UD

    LOC -->|"callback"| HM
    NOTF -->|"callback"| HM
    STORE -->|"callback"| SA
    SIRI -->|"triggers"| IE

    PD -->|"shared data bus (App Group)"| WE

    classDef appTargets fill:#cce5ff,stroke:#3399ff;
    classDef persistence fill:#d5f5e3,stroke:#27ae60;
    classDef shared fill:#fcf3cf,stroke:#f1c40f;
    classDef external fill:#f0f0f0,stroke:#888,color:#000;

    click SA "https://github.com/daneden/solstice/blob/main/Solstice/SolsticeApp.swift"
    click WE "https://github.com/daneden/solstice/blob/main/Widget/WidgetBundle.swift"
    click WA "https://github.com/daneden/solstice/blob/main/watchOS/ContentView.swift"
    click IE "https://github.com/daneden/solstice/blob/main/Intents/SolsticeShortcutsProvider.swift"
    click RP "https://github.com/daneden/solstice/blob/main/Packages/RealityKitContent/Package.swift"
    click PD "https://github.com/daneden/solstice/blob/main/Data Model/Persistence.swift"
    click HM "https://github.com/daneden/solstice/blob/main/Solstice/Helpers/SolsticeCalculator.swift"
    click UD "https://github.com/daneden/solstice/blob/main/Solstice/Charts/DaylightChart.swift"
    click EXV "https://github.com/daneden/solstice/blob/main/Solstice/Extensions/Color+toHex.swift"
    click STORE "https://github.com/daneden/solstice/blob/main/Solstice/StoreKitConfiguration.storekit"
    click LOC "https://github.com/daneden/solstice/blob/main/Solstice/Helpers/LocationSearchService.swift"
    click NOTF "https://github.com/daneden/solstice/blob/main/Solstice/Helpers/NotificationManager.swift"
    click SIRI "https://github.com/daneden/solstice/blob/main/Intents/GetSunriseTime.swift"
```
