# gluonfield/enchanted architecture

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

- Interactive diagram: https://gitdiagram.com/gluonfield/enchanted
- Repository: https://github.com/gluonfield/enchanted

## Overview

##### Main Components
- Frontend (UI): There are separate UI folders for iOS, macOS, and shared UI components. Include chat interfaces, settings panels, conversation history views, and platform-specific views (e.g., MenuBar on macOS, prompt panels, voice components, etc.).
- Application Logic: The central Application entry point (EnchantedApp.swift) and the use of Stores (e.g., AppStore, ConversationStore) indicate a clear separation of state management.
- Services Layer: Several service classes (Clipboard, Haptics, Hotkey, OllamaService, SpeechService, SwiftDataService, etc.) handle business logic (networking to the Ollama server, speech synthesis, text-to-speech, etc.).
- Models/Data: Models for language models, notifications, conversations, and custom SwiftData models represent domain entities.
- Extensions & Helpers: These add additional functionality to standard types and provide utility methods across the app.
- External Dependencies: The app requires a connection to an externally hosted Ollama server (the README outlines how to set up server endpoints). This is your external API dependency.

##### Relationships and Data Flows
- The UI components interact with the Stores for state management, which drive the chat messages, conversation history, and settings.
- Stores and Models connect with the Services layer. For example, the OllamaService sends/receives API requests to the Ollama server, while SpeechService manages text-to-speech.
- The Helpers and Extensions augment functionality (e.g., accessibility, image handling, formatting) across the UI and backend logic.
- There is data persistence through SwiftData (a folder dedicated to SwiftData models and operations).

##### Important Architectural Patterns
- Separation of Concerns: Notice clear divisions between the UI layer (presentation), the business logic layer (services/stores), and the data layer (models/SwiftData).
- Cross-Platform Design: The architecture differentiates platform-specific components (in UI/macOS, UI/iOS, etc.) while keeping shared UI code in UI/Shared.
- Modular Design: Each directory represents a module or layer (Services, Models, Extensions, etc.), making the system highly extensible and easier to maintain.
- Dependency Injection and Data Flow: The use of Stores to mediate state, with their reliance on Services, shows the influence of modern SwiftUI best practices.

##### Relevant Technologies and Frameworks
- Swift and SwiftUI for user interfaces.
- Xcode project structure and tools.
- SwiftData for local data persistence.
- Integration with Ollama server (an open-source, locally hosted ML model server).
- Use of Apple-specific frameworks (for accessibility, text-to-speech, and platform-specific UI elements).

##### Elements
- Inter-module interactions: indicate that the UI references shared UI components and that platform-specific UIs extend or utilize the shared logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend (UI)
    subgraph "Frontend (UI)"
        FC1["Shared UI Components"]:::ui
        FC2["iOS UI Components"]:::ui
        FC3["macOS UI Components"]:::ui
    end

    %% Application Logic / Stores
    subgraph "Application Logic"
        AL1["Main Entry"]:::app
        AL2["State Management Stores"]:::app
    end

    %% Services Layer
    subgraph "Services Layer"
        S1["Ollama Service"]:::svc
        S2["Clipboard Service"]:::svc
        S3["Haptics Service"]:::svc
        S4["Hotkey Service"]:::svc
        S5["Speech Service"]:::svc
        S6["SwiftData Service"]:::svc
        S7["Throttler Service"]:::svc
    end

    %% Models & Data
    subgraph "Models/Data"
        M1["Domain Models"]:::model
        M2["Persistence Models (SwiftData)"]:::model
    end

    %% Extensions & Helpers
    subgraph "Extensions & Helpers"
        EH1["Extensions"]:::ext
        EH2["Helpers"]:::ext
    end

    %% External Dependency
    EA["Ollama Server"]:::external

    %% Connections
    %% UI to Application Logic
    FC1 -->|"triggersState"| AL2
    FC2 -->|"triggersState"| AL2
    FC3 -->|"triggersState"| AL2

    %% Application Logic internal connection
    AL1 --> AL2

    %% Application Logic to Services Layer
    AL2 -->|"calls"| S1
    AL2 -->|"calls"| S2
    AL2 -->|"calls"| S3
    AL2 -->|"calls"| S4
    AL2 -->|"calls"| S5
    AL2 -->|"calls"| S6
    AL2 -->|"calls"| S7

    %% Services to External API
    S1 -->|"APIRequests"| EA

    %% Services to Models/Data
    S6 -->|"persistsData"| M2

    %% Application Logic to Models/Data
    AL2 -->|"managesState"| M1

    %% Extensions & Helpers to UI and Application Logic
    EH1 -->|"supports"| FC1
    EH2 -->|"assists"| AL2

    %% Class Definitions for Colour-coding
    classDef ui fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef app fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef svc fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef model fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef ext fill:#d1c4e9,stroke:#333,stroke-width:2px;
    classDef external fill:#ffdead,stroke:#333,stroke-width:2px;

    %% Click Events
    click FC1 "https://github.com/gluonfield/enchanted/tree/main/Enchanted/UI/Shared"
    click FC2 "https://github.com/gluonfield/enchanted/tree/main/Enchanted/UI/iOS"
    click FC3 "https://github.com/gluonfield/enchanted/tree/main/Enchanted/UI/macOS"
    click AL1 "https://github.com/gluonfield/enchanted/blob/main/Enchanted/Application/EnchantedApp.swift"
    click AL2 "https://github.com/gluonfield/enchanted/tree/main/Enchanted/Stores"
    click S1 "https://github.com/gluonfield/enchanted/blob/main/Enchanted/Services/OllamaService.swift"
    click S2 "https://github.com/gluonfield/enchanted/blob/main/Enchanted/Services/Clipboard.swift"
    click S3 "https://github.com/gluonfield/enchanted/blob/main/Enchanted/Services/HapticsService.swift"
    click S4 "https://github.com/gluonfield/enchanted/blob/main/Enchanted/Services/HotkeyService.swift"
    click S5 "https://github.com/gluonfield/enchanted/blob/main/Enchanted/Services/SpeechService.swift"
    click S6 "https://github.com/gluonfield/enchanted/blob/main/Enchanted/Services/SwiftDataService.swift"
    click S7 "https://github.com/gluonfield/enchanted/blob/main/Enchanted/Services/Throttler.swift"
    click M1 "https://github.com/gluonfield/enchanted/tree/main/Enchanted/Models"
    click M2 "https://github.com/gluonfield/enchanted/tree/main/Enchanted/SwiftData/Models"
    click EH1 "https://github.com/gluonfield/enchanted/tree/main/Enchanted/Extensions"
    click EH2 "https://github.com/gluonfield/enchanted/tree/main/Enchanted/Helpers"
```
