How xororz/local-dream works
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.