# xororz/local-dream architecture

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

- Interactive diagram: https://gitdiagram.com/xororz/local-dream
- Repository: https://github.com/xororz/local-dream

## Overview

##### Main Architectural Components
▪ User Interface (UI) Layer – Represents the Android components written in Kotlin. This includes MainActivity.kt, UI screens (ModelListScreen.kt, ModelRunScreen.kt), themes, and navigation components.
▪ Service & Data Layer – Encompasses services such as BackendService.kt, BackgroundGenerationService.kt, DownloadManager.kt, FileVerification.kt, Preferences, and Model management. This layer manages data handling, download of model files, and settings.
▪ Native Inference Engine – Contains the C++ code in the "app/src/main/cpp" folder. This module integrates:
- The Qualcomm QNN SDK for NPU acceleration (with pre-supplied safety_checker.mnn assets).
- MNN framework for CPU inference.
- Several 3rd party libraries such as cpp-httplib, json, tokenizers-cpp, xtensor, and more.
- Core inference modules like DPMSolverMultistepScheduler.hpp, QnnModel.hpp, SDUtils.hpp, and the main.cpp that likely initializes the native pipeline.
▪ Build & Configuration Modules – While not part of the “runtime architecture,” they are important to note since the project leverages Gradle (for Android), CMake (to build the C++ code), and settings in files like gradle.properties, build.gradle.kts, and CMakePresets.json which indicate configurable paths for the Android NDK and QNN SDK.

##### Relationships and Interactions
▪ The UI layer (Android Activities, Screens, and Navigation) interacts with the service layer via API calls for model downloading and triggering generation processes.
▪ Service components call into the native inference engine (using JNI bridges in the app’s structure) to perform the heavy lifting of image generation.
▪ The native layer uses integrated third-party libraries and SDKs (QNN for NPU tasks, MNN for CPU tasks) to perform the actual inference computations.
▪ Model files and assets (e.g., the safety_checker.mnn file) and downloaded models are referenced by both the native layer and the data management services.
▪ The build and configuration modules ensure that correct dependencies and paths (such as QNN_SDK_ROOT and ANDROID_NDK_ROOT) are set up for both development and production builds.

##### Architectural Patterns and Design Principles
▪ Separation of Concerns – Different layers (UI, Services, Native Inference) are clearly segregated. Each layer has its defined responsibilities (view rendering, business/data logic, computation).
▪ Integration of Native and Managed Code – The design embraces a hybrid approach with the JNI bridge to allow smooth communication between Kotlin/Java and C++.
▪ Modular Build Configuration – Use of CMake scripts and Gradle/Kotlin-based build scripts indicates an emphasis on a reproducible and flexible build process.
▪ Support for Multiple Execution Modes – The architecture supports toggling between NPU-accelerated and CPU inference modes, clearly reflecting design decisions around performance optimization and device compatibility.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        UI1["UI Components"]:::ui
        UI2["UI Screens"]:::ui
        UI3["UI Theme"]:::ui
    end

    %% Service & Data Layer
    subgraph "Service & Data Layer"
        S1["Backend & Generation Service"]:::service
        S2["Data Management (Download & Verification)"]:::service
        S3["Navigation"]:::service
    end

    %% Native Inference Engine (C++ with QNN & MNN)
    subgraph "Native Inference Engine (C++ with QNN & MNN)"
        N1["C++ Native Core Modules"]:::native
        N2["Third-Party Libraries"]:::native
        N3["Safety Checker Asset"]:::native
    end

    %% Build & Configuration Modules
    subgraph "Build & Configuration Modules"
        B1["Android Build Config"]:::build
        B2["CMake Build Config"]:::build
        B3["Project Build Config"]:::build
    end

    %% Connections between layers
    UI1 -->|"triggers"| S1
    UI2 -->|"navigates"| S3
    S1 -->|"JNI_call"| N1
    S2 -->|"providesModelAssets"| N1
    N1 -->|"returnsResults"| UI1

    %% Connections from Build & Configuration Modules
    B1 -->|"ConfiguresUI"| UI1
    B2 -->|"BuildsNative"| N1
    B3 -->|"SetsUpService"| S1

    %% Click Events for UI Layer
    click UI1 "https://github.com/xororz/local-dream/tree/master/app/src/main/java/io/github/xororz/localdream/ui"
    click UI2 "https://github.com/xororz/local-dream/tree/master/app/src/main/java/io/github/xororz/localdream/ui/screens"
    click UI3 "https://github.com/xororz/local-dream/tree/master/app/src/main/java/io/github/xororz/localdream/ui/theme"

    %% Click Events for Service & Data Layer
    click S1 "https://github.com/xororz/local-dream/tree/master/app/src/main/java/io/github/xororz/localdream/service"
    click S2 "https://github.com/xororz/local-dream/tree/master/app/src/main/java/io/github/xororz/localdream/data"
    click S3 "https://github.com/xororz/local-dream/tree/master/app/src/main/java/io/github/xororz/localdream/navigation"

    %% Click Events for Native Inference Engine
    click N1 "https://github.com/xororz/local-dream/tree/master/app/src/main/cpp/src"
    click N2 "https://github.com/xororz/local-dream/tree/master/app/src/main/cpp/3rdparty"
    click N3 "https://github.com/xororz/local-dream/blob/master/app/src/filter/assets/safety_checker.mnn"

    %% Click Events for Build & Configuration Modules
    click B1 "https://github.com/xororz/local-dream/blob/master/app/build.gradle.kts"
    click B2 "https://github.com/xororz/local-dream/blob/master/app/src/main/cpp/CMakeLists.txt"
    click B3 "https://github.com/xororz/local-dream/blob/master/gradle.properties"

    %% Styles
    classDef ui fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef service fill:#A9DFBF,stroke:#229954,stroke-width:2px;
    classDef native fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef build fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
```
