# nerve-sparks/iris_android architecture

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

- Interactive diagram: https://gitdiagram.com/nerve-sparks/iris_android
- Repository: https://github.com/nerve-sparks/iris_android

## Overview

##### Main Components
- UI Layer: This includes all the screens and components under the “app/src/main/java/com/nervesparks/iris/ui” package. It comprises screens like ChatScreen, AboutScreen, ModelsScreen, ParametersScreen, and UI components (e.g., ChatSection, DownloadModal) that form the graphical interface.
- Application Logic / ViewModel: Elements such as MainViewModel and possibly other helper classes form the mediator between the UI and underlying business logic. This layer encapsulates user interactions and state management.
- Data Management: The “app/src/main/java/com/nervesparks/iris/data” folder (e.g., UserPreferencesRespository) manages configuration, user settings, and possibly the model download metadata.
- Native Module (llama): The “llama” directory contains the native (C/C++) code along with its JNI integration (such as LLamaAndroid.kt). This part of the system wraps underlying llama.cpp functionality to execute machine learning tasks offline.
- Model & Download Manager: Since the app downloads GGUF models from Hugging Face, clearly denote the module or component responsible for model downloading, storage, and selection logic.
- External/Platform Services: Represent interactions with Android’s system services such as Text-to-Speech, Speech-to-Text (as noted in the README), as well as Android’s debugging and deployment mechanisms.

##### Relationships and Data Flow
- How the UI components (screens and custom components) connect to the MainViewModel, which processes user input and manages presentation logic.
- From the ViewModel, illustrate interactions with the data repository for retrieving user preferences, saving settings, and managing downloaded models.

##### Architectural Patterns and Technologies
- Use of the MVVM pattern: clearly display separate layers for Model (data), ViewModel (logic), and View (UI).
- Integration of native C++ code via a dedicated module (llama) that relies on JNI bridging (as indicated by the java and cpp code).
- Mention any Android-specific libraries or build technologies (e.g., Gradle, CMake for the native build) that have configuration files (build.gradle.kts, CMakeLists.txt) present in the project.
- How the customizable parameters (e.g., n_threads, top_k, etc.) are provided as configurations to the engine.

- A block for the Android UI Layer that contains screens like MainChatScreen, ChatScreen, SettingsScreen, etc.
- A block for the Application Logic / MVVM Layer showing MainActivity, MainViewModel.
- A block for Data/Repository showing UserPreferencesRepository and download management logic.
- Optional blocks representing external services (Hugging Face for model downloads) and Android system services (Speech-to-Text/Text-to-Speech).

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Android UI Layer
    subgraph "Android UI Layer"
        UI["UI Layer"]:::ui
        ChatScreen["ChatScreen"]:::ui
        AboutScreen["AboutScreen"]:::ui
        ModelsScreen["ModelsScreen"]:::ui
        ParametersScreen["ParametersScreen"]:::ui
    end

    %% Application Logic (MVVM)
    subgraph "Application Logic (MVVM)"
        MainVM["MainViewModel"]:::logic
    end

    %% Data Management
    subgraph "Data Management"
        Repo["UserPreferencesRepository"]:::data
        DownloadMgr["Model Download Manager"]:::data
    end

    %% Native Integration
    subgraph "Native Integration"
        LLamaBridge["LLamaAndroid Bridge"]:::native
        NativeEngine["Native C++ Engine"]:::native
    end

    %% External Services
    subgraph "External Services"
        HuggingFace["Hugging Face Service"]:::external
        AndroidServices["Android System TTS/STT"]:::external
    end

    %% Connections
    %% UI Layer interactions
    UI -->|"user_input"| MainVM
    ChatScreen -->|"user_action"| MainVM
    AboutScreen -->|"user_action"| MainVM
    ModelsScreen -->|"user_action"| MainVM
    ParametersScreen -->|"user_action"| MainVM

    %% Application Logic interactions
    MainVM -->|"fetch_config"| Repo
    MainVM -->|"initiate_download"| DownloadMgr
    MainVM -->|"invoke_native"| LLamaBridge
    MainVM -->|"voice_services"| AndroidServices

    %% Native Integration interactions
    LLamaBridge -->|"JNI_call"| NativeEngine
    NativeEngine -- "JNI_response" --> LLamaBridge
    LLamaBridge -->|"native_response"| MainVM

    %% Data Management interactions with external model download
    DownloadMgr -->|"download_model"| HuggingFace
    HuggingFace -- "model_data" --> DownloadMgr

    %% Styling classes
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef logic fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef data fill:#FFDAB9,stroke:#000,stroke-width:2px;
    classDef native fill:#F08080,stroke:#000,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:2px;

    %% Click Events
    click UI "https://github.com/nerve-sparks/iris_android/tree/master/app/src/main/java/com/nervesparks/iris/ui"
    click MainVM "https://github.com/nerve-sparks/iris_android/blob/master/app/src/main/java/com/nervesparks/iris/MainViewModel.kt"
    click Repo "https://github.com/nerve-sparks/iris_android/blob/master/app/src/main/java/com/nervesparks/iris/data/UserPreferencesRespository.kt"
    click LLamaBridge "https://github.com/nerve-sparks/iris_android/blob/master/llama/src/main/java/android/llama/cpp/LLamaAndroid.kt"
    click NativeEngine "https://github.com/nerve-sparks/iris_android/tree/master/llama/src/main/cpp"
    click DownloadMgr "https://github.com/nerve-sparks/iris_android/blob/master/app/src/main/java/com/nervesparks/iris/Downloadable.kt"
```
