# dimillian/icecubesapp architecture

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

- Interactive diagram: https://gitdiagram.com/dimillian/icecubesapp
- Repository: https://github.com/dimillian/icecubesapp

## Overview

##### Project Type and Purpose
- IceCubesApp is a modular, cross-platform (iOS, macOS, iPadOS, visionOS) SwiftUI client for the Mastodon social network.
- It uses a package-based architecture (Swift Packages) and MVVM for clear separation of concerns: UI, business logic, network, models, and data persistence.

##### File Structure Analysis
- Top-Level Targets:
- IceCubesApp: the main SwiftUI application.
- IceCubesActionExtension, IceCubesShareExtension, IceCubesNotifications, IceCubesAppWidgetsExtension, IceCubesAppIntents: Apple extensions (Action, Share, Push Service, Widgets, Siri Shortcuts).
- Packages Directory: each folder is a Swift Package focused on a domain:
- Models (data structures, Codable)
- Network (HTTP Clients, Mastodon endpoint definitions, streaming)
- Env (app environment & preferences, caching, Keychain, iCloud sync, telemetry)
- StatusKit (post editor UI components + business logic)
- Account & AppAccount (account management, secure token storage, login flows)
- Timeline, Explore, Conversations, Notifications, Lists, MediaUI, DesignSystem: domain-specific UI + ViewModels.
- CI & Config: ci_scripts, .xcconfig template, GitHub workflows.

##### Key Architectural Insights from README
- MVVM pattern across packages: Views ←→ ViewModels ←→ Models/Services.
- Modular separation: each feature is its own package to simplify maintenance and reuse.
- Data Persistence: Bodega (SQLite wrapper) for caching home timeline; UserDefaults for position; iCloud for syncing tag groups, drafts, remote timelines.
- Network: Mastodon REST + streaming websockets; OpenAI API client for AI features.
- Extensions: APNS proxy for push, Siri intents, share & action extensions for system integration, WidgetKit for widgets.

a. Main Components
- Presentation Layer: SwiftUI Views in IceCubesApp target + Widgets + Extensions.
- MVVM Layer: ViewModels in each package (e.g., TimelineViewModel, StatusEditorViewModel).
- Domain Services:
– Network Package (Client, Endpoints, StreamingClients)
– StatusKit (editor business logic, AI integration)
– Env (Preferences, Account Store, Cache managers)
- Data Layer:
– Models Package (Mastodon entities, SwiftData local models)
– Persistence (Bodega/SQLite, UserDefaults, iCloud Key-Value)
– Keychain for OAuth tokens
- External Services: Mastodon instances (REST & Streaming API), OpenAI API, APNS via Push Proxy, iCloud, Siri Intents, WidgetKit.

b. Relationships & Data Flow
3. Network Client communicates with Mastodon REST for CRUD operations; Streaming Client keeps websocket open for live updates.
4. Responses decode into Models, persisted in Bodega or SwiftData local stores.
5. Env components sync user preferences and drafts via iCloud K-V; Keychain for tokens.
6. Push Notification Extension receives APNS payloads via proxy, decodes & routes to main app.
7. Share/Action Extensions invoke the app’s compose flows using shared packages (StatusKit).
8. WidgetKit fetches data from Env & Network to render small widget UI.
9. Siri Intents call AppIntentService to handle shortcuts & deep links.

c. Architectural Patterns & Principles
- MVVM for testable UI and separation of concerns.
- Modular packaging to isolate features and reduce build times.
- Single Responsibility: each package owns one domain.
- Dependency inversion: ViewModels depend on protocols/services, not concrete implementations.
- Reactive updates: SwiftUI’s state binding keeps UI in sync with model changes.

d. Key Technologies & Frameworks
- SwiftUI, Combine (implied by MVVM and streaming)
- Swift Package Manager for modularization
- URLSession & WebSockets (Network)
- Bodega (SQLite wrapper) & SwiftData
- iCloud Key-Value storage & CloudKit (for sync)
- Keychain Services (secure token storage)
- APNS & NotificationService Extension
- WidgetKit & Intents

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        UI["UI (SwiftUI Views)"]:::internal
        ActionExt["Action Extension"]:::internal
        ShareExt["Share Extension"]:::internal
        PushExt["Push Notifications"]:::internal
        WidgetsExt["WidgetKit Extension"]:::internal
        SiriIntents["Siri Intents"]:::internal
    end

    %% MVVM / Features
    subgraph "MVVM / Feature Packages"
        direction TB
        Account["Account"]:::internal
        AppAccount["AppAccount"]:::internal
        Timeline["Timeline"]:::internal
        Explore["Explore"]:::internal
        Conversations["Conversations"]:::internal
        NotificationsFeature["Notifications"]:::internal
        Lists["Lists"]:::internal
        MediaUI["MediaUI"]:::internal
        DesignSystem["DesignSystem"]:::internal
    end

    %% Domain Services
    subgraph "Domain Services"
        direction TB
        Network["Network Client & Endpoints"]:::internal
        OpenAI["OpenAI API Client"]:::internal
        Env["Environment & Preferences"]:::internal
        StatusKit["Status Editor & AI Integration"]:::internal
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Models["Models (Mastodon Entities, SwiftData)"]:::data
        Persistence["Timeline Cache (Bodega/SQLite)"]:::data
        Keychain["Keychain (OAuth Tokens)"]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Mastodon["Mastodon REST & Streaming API"]:::external
        OpenAISvc["OpenAI API"]:::external
        APNS["APNS via Push Proxy"]:::external
        iCloud["iCloud K-V Store"]:::external
        SiriSvc["Siri Intents Service"]:::external
    end

    %% Connections Presentation -> MVVM
    UI -->|"binds to"| Account
    UI -->|"binds to"| Timeline
    UI -->|"binds to"| Explore
    UI -->|"binds to"| Conversations
    UI -->|"binds to"| NotificationsFeature
    UI -->|"binds to"| Lists
    UI -->|"binds to"| MediaUI
    UI -->|"binds to"| DesignSystem

    ActionExt -->|"uses core packages"| StatusKit
    ShareExt -->|"uses core packages"| StatusKit
    PushExt -->|"receives APNS"| APNS
    WidgetsExt -->|"fetches data via"| Env
    SiriIntents -->|"calls intents via"| Env

    %% MVVM -> Domain Services
    Account -->|"uses services"| Env
    AppAccount -->|"uses services"| Keychain
    Timeline -->|"calls"| Network
    Explore -->|"calls"| Network
    Conversations -->|"calls"| Network
    NotificationsFeature -->|"calls"| Network
    Lists -->|"calls"| Network
    MediaUI -->|"renders media using"| Network
    DesignSystem -->|"shared UI"| StatusKit

    StatusKit -->|"calls AI client"| OpenAI
    StatusKit -->|"orchestrates"| Env

    %% Domain Services -> Data Layer & External
    Network -->|"CRUD operations"| Mastodon
    Network -->|"websocket streaming"| Mastodon
    Network -->|"uses"| OpenAISvc
    Env -->|"syncs prefs"| iCloud
    Env -->|"stores telemetry"| iCloud
    Env -->|"uses"| Keychain
    Persistence -->|"stores decoded models"| Models

    Network -->|"decodes into"| Models
    Models -->|"persisted in"| Persistence

    APNS -->|"push payloads to"| PushExt
    SiriSvc -->|"triggers"| SiriIntents

    %% Click Events
    click UI "https://github.com/dimillian/icecubesapp/tree/main/IceCubesApp/App"
    click ActionExt "https://github.com/dimillian/icecubesapp/tree/main/IceCubesActionExtension"
    click ShareExt "https://github.com/dimillian/icecubesapp/tree/main/IceCubesShareExtension"
    click PushExt "https://github.com/dimillian/icecubesapp/tree/main/IceCubesNotifications"
    click WidgetsExt "https://github.com/dimillian/icecubesapp/tree/main/IceCubesAppWidgetsExtension"
    click SiriIntents "https://github.com/dimillian/icecubesapp/tree/main/IceCubesAppIntents"
    click Account "https://github.com/dimillian/icecubesapp/tree/main/Packages/Account"
    click AppAccount "https://github.com/dimillian/icecubesapp/tree/main/Packages/AppAccount"
    click Timeline "https://github.com/dimillian/icecubesapp/tree/main/Packages/Timeline"
    click Explore "https://github.com/dimillian/icecubesapp/tree/main/Packages/Explore"
    click Conversations "https://github.com/dimillian/icecubesapp/tree/main/Packages/Conversations"
    click NotificationsFeature "https://github.com/dimillian/icecubesapp/tree/main/Packages/Notifications"
    click Lists "https://github.com/dimillian/icecubesapp/tree/main/Packages/Lists"
    click MediaUI "https://github.com/dimillian/icecubesapp/tree/main/Packages/MediaUI"
    click DesignSystem "https://github.com/dimillian/icecubesapp/tree/main/Packages/DesignSystem"
    click Network "https://github.com/dimillian/icecubesapp/tree/main/Packages/Network"
    click OpenAI "https://github.com/dimillian/icecubesapp/blob/main/Packages/Network/Sources/Network/OpenAIClient.swift"
    click Env "https://github.com/dimillian/icecubesapp/tree/main/Packages/Env"
    click StatusKit "https://github.com/dimillian/icecubesapp/tree/main/Packages/StatusKit"
    click Models "https://github.com/dimillian/icecubesapp/tree/main/Packages/Models"
    click Persistence "https://github.com/dimillian/icecubesapp/blob/main/Packages/Timeline/Sources/Timeline/actors/TimelineCache.swift"

    %% Styles
    classDef internal fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef data fill:#c8e6c9,stroke:#43a047,color:#1b5e20;
    classDef external fill:#ffe0b2,stroke:#fb8c00,color:#e65100;
```
