# reagent-systems/spark architecture

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

- Interactive diagram: https://gitdiagram.com/reagent-systems/spark
- Repository: https://github.com/reagent-systems/spark

## Overview

##### Project Type and Purpose
- Mobile full-stack app (Android) with on-device LLM inference plus a local API server.
- Clean-architecture/MVVM layered design.

##### File Structure
- app/src/main/java/com/example/spark/presentation – Jetpack Compose UI + ViewModels (Presentation layer).
- app/src/main/java/com/example/spark/domain – Domain models & repository interfaces (Domain layer).
- app/src/main/java/com/example/spark/data – Repository implementations, download/persistence/file managers (Data layer).
- app/src/main/java/com/example/spark/network/server – Ktor API server.
- utils – Token/auth helpers, performance & network utilities.
- AndroidManifest, resources, Gradle scripts for build/deployment.

##### README for Additional Insights
- Uses MediaPipe for on-device LLM inference.
- Ktor for local HTTP API.
- Jetpack Compose for UI.
- Model downloads from HuggingFace.

##### Main Components & Relationships
a. Presentation Layer
– Jetpack Compose screens & UI components
– ViewModels (ChatViewModel, ModelDownloadViewModel, ServerViewModel, etc.)
b. Domain Layer
– LLMRepository, UpdateRepository interfaces
– Domain models (LLMModel, UpdateModels)
c. Data Layer
– LLMRepositoryImpl & UpdateRepositoryImpl
– ModelDownloadManager (downloads from HF), ModelFileManager + ModelPersistenceManager
– Network API models (ApiModels) for server
d. Inference Engine
– MediaPipe LLM Inference (native library)
e. Local API Server
– Ktor server (ApiServer) listening on port 8080
– Exposes endpoints (/v1/models, /v1/chat/completions)
f. External Systems
– HuggingFace model hosting (for downloads)
– HTTP clients (other apps) calling the local API

##### Important Patterns & Principles
- MVVM + Clean Architecture (separate Presentation / Domain / Data)
- Repository pattern for data access & abstraction
- Single-Activity Compose with modular UI components
- Local-first (no cloud) architecture emphasizing privacy
- Asynchronous, callback/flow-based data flows

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    subgraph "External Systems"
        HF["HuggingFace Model Hosting"]:::external
        HTTPClient["HTTP Clients"]:::external
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        MediaPipeEngine["MediaPipe LLM Inference Engine"]:::infra
        ApiServer["Ktor ApiServer\nGET /v1/models\nPOST /v1/chat/completions"]:::infra
    end

    %% Data Layer
    subgraph "Data Layer"
        LLMRepoImpl["LLMRepositoryImpl"]:::data
        UpdateRepoImpl["UpdateRepositoryImpl"]:::data
        ModelDownloadManager["ModelDownloadManager"]:::data
        ModelFileManager["ModelFileManager"]:::data
        ModelPersistenceManager["ModelPersistenceManager"]:::data
        ApiModels["ApiModels"]:::data
        LocalStorage["Local Storage\n(models)"]:::storage
    end

    %% Domain Layer
    subgraph "Domain Layer"
        LLMRepoIfc["LLMRepository (interface)"]:::domain
        UpdateRepoIfc["UpdateRepository (interface)"]:::domain
        DomainModels["Domain Models"]:::domain
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        UIComponents["Compose UI Components"]:::presentation
        ChatVM["ChatViewModel"]:::presentation
        DownloadVM["ModelDownloadViewModel"]:::presentation
        ServerVM["ServerViewModel"]:::presentation
        MainActivity["MainActivity"]:::presentation
    end

    %% Utilities
    subgraph "Utilities"
        HFAuth["HuggingFaceAuth"]:::utils
        ModelCatalog["ModelCatalog"]:::utils
        NetworkUtils["NetworkUtils"]:::utils
        PerformanceUtils["PerformanceUtils"]:::utils
    end

    %% Android Manifest
    AndroidManifest["AndroidManifest.xml"]:::external

    %% User Flow
    User["User"]:::external
    User -->|taps| UIComponents
    UIComponents -->|events| ChatVM
    UIComponents -->|events| DownloadVM
    UIComponents -->|events| ServerVM
    MainActivity --> UIComponents

    %% Presentation to Domain
    ChatVM -->|calls| LLMRepoIfc
    DownloadVM -->|calls| UpdateRepoIfc
    ServerVM -->|calls| LLMRepoIfc
    ServerVM -->|calls| UpdateRepoIfc

    %% Domain to Data
    LLMRepoIfc -->|implemented by| LLMRepoImpl
    UpdateRepoIfc -->|implemented by| UpdateRepoImpl

    %% Data managers
    LLMRepoImpl -->|uses| MediaPipeEngine
    LLMRepoImpl -->|reads/writes| LocalStorage
    UpdateRepoImpl -->|uses| ModelDownloadManager
    UpdateRepoImpl -->|uses| ModelFileManager
    UpdateRepoImpl -->|uses| ModelPersistenceManager
    ModelDownloadManager -->|downloads from| HF
    ModelDownloadManager -->|stores to| LocalStorage

    %% API Models
    ApiServer -->|serializes| ApiModels

    %% HTTP Flow
    HTTPClient -->|HTTP calls| ApiServer
    ApiServer -->|invokes| LLMRepoIfc
    ApiServer -->|invokes| UpdateRepoIfc
    ApiServer -->|calls| MediaPipeEngine
    ApiServer -->|responds| HTTPClient

    %% Utilities usage
    ModelDownloadManager -->|auth| HFAuth
    ModelDownloadManager -->|catalog| ModelCatalog
    ModelFileManager -->|network| NetworkUtils
    ModelPersistenceManager -->|performance| PerformanceUtils

    %% Android Manifest link
    ApiServer -->|declared in| AndroidManifest

    %% Click Events
    click UIComponents "https://github.com/reagent-systems/spark/tree/master/Spark/app/src/main/java/com/example/spark/presentation/ui"
    click MainActivity "https://github.com/reagent-systems/spark/blob/master/Spark/app/src/main/java/com/example/spark/MainActivity.kt"
    click ChatVM "https://github.com/reagent-systems/spark/tree/master/Spark/app/src/main/java/com/example/spark/presentation/viewmodel"
    click DownloadVM "https://github.com/reagent-systems/spark/tree/master/Spark/app/src/main/java/com/example/spark/presentation/viewmodel"
    click ServerVM "https://github.com/reagent-systems/spark/tree/master/Spark/app/src/main/java/com/example/spark/presentation/viewmodel"
    click LLMRepoIfc "https://github.com/reagent-systems/spark/blob/master/Spark/app/src/main/java/com/example/spark/domain/repository/LLMRepository.kt"
    click UpdateRepoIfc "https://github.com/reagent-systems/spark/blob/master/Spark/app/src/main/java/com/example/spark/domain/repository/UpdateRepository.kt"
    click DomainModels "https://github.com/reagent-systems/spark/tree/master/Spark/app/src/main/java/com/example/spark/domain/models"
    click LLMRepoImpl "https://github.com/reagent-systems/spark/blob/master/Spark/app/src/main/java/com/example/spark/data/repository/LLMRepositoryImpl.kt"
    click UpdateRepoImpl "https://github.com/reagent-systems/spark/blob/master/Spark/app/src/main/java/com/example/spark/data/repository/UpdateRepositoryImpl.kt"
    click ModelDownloadManager "https://github.com/reagent-systems/spark/blob/master/Spark/app/src/main/java/com/example/spark/data/repository/ModelDownloadManager.kt"
    click ModelFileManager "https://github.com/reagent-systems/spark/blob/master/Spark/app/src/main/java/com/example/spark/data/repository/ModelFileManager.kt"
    click ModelPersistenceManager "https://github.com/reagent-systems/spark/blob/master/Spark/app/src/main/java/com/example/spark/data/repository/ModelPersistenceManager.kt"
    click ApiModels "https://github.com/reagent-systems/spark/blob/master/Spark/app/src/main/java/com/example/spark/network/api/ApiModels.kt"
    click ApiServer "https://github.com/reagent-systems/spark/blob/master/Spark/app/src/main/java/com/example/spark/network/server/ApiServer.kt"
    click HFAuth "https://github.com/reagent-systems/spark/blob/master/Spark/app/src/main/java/com/example/spark/utils/HuggingFaceAuth.kt"
    click ModelCatalog "https://github.com/reagent-systems/spark/blob/master/Spark/app/src/main/java/com/example/spark/utils/ModelCatalog.kt"
    click NetworkUtils "https://github.com/reagent-systems/spark/blob/master/Spark/app/src/main/java/com/example/spark/utils/NetworkUtils.kt"
    click PerformanceUtils "https://github.com/reagent-systems/spark/blob/master/Spark/app/src/main/java/com/example/spark/utils/PerformanceUtils.kt"
    click AndroidManifest "https://github.com/reagent-systems/spark/blob/master/Spark/app/src/main/AndroidManifest.xml"
    click UIComponents "https://github.com/reagent-systems/spark/tree/master/Spark/app/src/main/java/com/example/spark/ui/theme"

    %% Styles
    classDef presentation fill:#cce5ff,stroke:#2b6cb0,color:#000
    classDef domain fill:#d4edda,stroke:#2f855a,color:#000
    classDef data fill:#fff3cd,stroke:#dd6b20,color:#000
    classDef infra fill:#e9d8fd,stroke:#6b46c1,color:#000
    classDef external fill:#e2e8f0,stroke:#4a5568,color:#000
    classDef utils fill:#faf089,stroke:#d69e2e,color:#000
    classDef storage fill:#f0fff4,stroke:#38a169,color:#000
```
