# legacydroid/android_packages_apps_luminaai architecture

> Architecture diagram of the GitHub repository legacydroid/android_packages_apps_luminaai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/legacydroid/android_packages_apps_luminaai
- Repository: https://github.com/legacydroid/android_packages_apps_luminaai

## Overview

LuminaAI is an Android system-overlay assistant: the user opens a fullscreen chat, the session coordinates assistant replies and tool calls, and results appear in the overlay. Its main branches are system tools, persistent memory and resumable history, and the optional Live2D avatar. The README documents capabilities whose detailed wiring was not sampled; those are included only where the documented ownership is clear.

Main entry points: [`src/com/legacydroid/luminaai/data/ToolRegistry.kt`](https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/data/ToolRegistry.kt) (Tool registry), [`src/com/legacydroid/luminaai/LuminaSession.kt`](https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/LuminaSession.kt) (Assistant session), [`src/com/legacydroid/luminaai/LuminaOverlayActivity.kt`](https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/LuminaOverlayActivity.kt) (Overlay activity), [`src/com/legacydroid/luminaai/LuminaRoot.kt`](https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/LuminaRoot.kt) (Overlay composition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Overlay and chat"]
  node_activity["Overlay activity"]
  node_root["Overlay composition<br/>[LuminaRoot.kt]"]
  node_chat["Chat overlay"]
end

subgraph group_assistant["Assistant workflow"]
  node_session["Assistant session<br/>[LuminaSession.kt]"]
  node_api["Assistant API<br/>[LumiApi.kt]"]
  node_registry["Tool registry<br/>[ToolRegistry.kt]"]
end

subgraph group_data["Memory and history"]
  node_history[("Chat history<br/>[HistoryStore.kt]")]
  node_memory[("Long-term memory<br/>[MemoryStore.kt]")]
end

subgraph group_tools["System capabilities"]
  node_clipboard["Clipboard tools<br/>[ClipboardTools.kt]"]
  node_systemtools["Device tools<br/>[SystemTools.kt]"]
  node_notifications["Notification buffer<br/>[NotificationHub.kt]"]
  node_search[("Local search index")]
  node_privacy["Privacy audit<br/>[PrivacyAudit.kt]"]
end

subgraph group_avatar["Live2D avatar"]
  node_livecontroller["Avatar controller"]
  node_avatarview["Avatar view<br/>[LuminaAvatar.kt]"]
  node_bridge["Kotlin JNI bridge<br/>[Live2DBridge.kt]"]
  node_nativebridge["Native JNI bridge<br/>[JniBridgeC.cpp]"]
  node_engine["Render engine<br/>[Live2DEngine.cpp]"]
  node_model["Cubism model<br/>[SampleModel.cpp]"]
  node_texture["Texture manager"]
end

node_user(("User"))
node_android["Android system"]
node_api_service["Assistant service"]

node_user -->|"opens"| node_activity
node_activity -->|"hosts"| node_root
node_activity -->|"awakens"| node_session
node_root -->|"renders"| node_chat
node_chat -->|"sends input"| node_session
node_session -->|"requests reply"| node_api
node_api -->|"sends request"| node_api_service
node_api_service -->|"returns reply"| node_api
node_session -->|"dispatches tools"| node_registry
node_registry -->|"executes"| node_systemtools
node_registry -->|"executes"| node_clipboard
node_registry -->|"reads"| node_notifications
node_registry -->|"searches"| node_search
node_registry -->|"audits"| node_privacy
node_registry -->|"manages"| node_memory
node_session -->|"saves sessions"| node_history
node_session -->|"loads memories"| node_memory
node_systemtools -->|"reads and controls"| node_android
node_clipboard -->|"accesses clipboard"| node_android
node_notifications -->|"receives notifications"| node_android
node_search -->|"queries records"| node_android
node_privacy -->|"checks permissions"| node_android
node_registry -.->|"controls avatar"| node_livecontroller
node_root -.->|"shows avatar"| node_avatarview
node_avatarview -.->|"drives rendering"| node_livecontroller
node_livecontroller -->|"calls native methods"| node_bridge
node_bridge -->|"invokes JNI"| node_nativebridge
node_nativebridge -->|"forwards calls"| node_engine
node_engine -->|"renders and animates"| node_model
node_model -->|"loads textures"| node_texture

click node_activity "https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/LuminaOverlayActivity.kt"
click node_root "https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/LuminaRoot.kt"
click node_chat "https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/ui/components/LuminaChatOverlay.kt"
click node_session "https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/LuminaSession.kt"
click node_api "https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/data/LumiApi.kt"
click node_registry "https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/data/ToolRegistry.kt"
click node_history "https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/data/HistoryStore.kt"
click node_memory "https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/data/MemoryStore.kt"
click node_clipboard "https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/data/ClipboardTools.kt"
click node_systemtools "https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/data/SystemTools.kt"
click node_notifications "https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/data/NotificationHub.kt"
click node_search "https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/data/LocalSearchIndex.kt"
click node_privacy "https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/data/PrivacyAudit.kt"
click node_livecontroller "https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/live2d/Live2DController.kt"
click node_avatarview "https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/live2d/LuminaAvatar.kt"
click node_bridge "https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/live2d/Live2DBridge.kt"
click node_nativebridge "https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/live2d/cpp/JniBridgeC.cpp"
click node_engine "https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/live2d/cpp/Live2DEngine.cpp"
click node_model "https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/live2d/cpp/SampleModel.cpp"
click node_texture "https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/live2d/cpp/LAppTextureManager.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_activity,node_root,node_chat,node_user toneBlue
class node_session,node_api,node_registry toneAmber
class node_history,node_memory toneMint
class node_clipboard,node_systemtools,node_notifications,node_search,node_privacy toneRose
class node_livecontroller,node_avatarview,node_bridge,node_nativebridge,node_engine,node_model,node_texture,node_android,node_api_service toneIndigo
```

## Components

### Overlay and chat

- [Overlay activity](https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/LuminaOverlayActivity.kt): `src/com/legacydroid/luminaai/LuminaOverlayActivity.kt`
- [Overlay composition](https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/LuminaRoot.kt): `src/com/legacydroid/luminaai/LuminaRoot.kt`
- [Chat overlay](https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/ui/components/LuminaChatOverlay.kt): `src/com/legacydroid/luminaai/ui/components/LuminaChatOverlay.kt`

### Assistant workflow

- [Assistant session](https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/LuminaSession.kt): `src/com/legacydroid/luminaai/LuminaSession.kt`
- [Assistant API](https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/data/LumiApi.kt): `src/com/legacydroid/luminaai/data/LumiApi.kt`
- [Tool registry](https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/data/ToolRegistry.kt): `src/com/legacydroid/luminaai/data/ToolRegistry.kt`

### Memory and history

- [Chat history](https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/data/HistoryStore.kt): `src/com/legacydroid/luminaai/data/HistoryStore.kt`
- [Long-term memory](https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/data/MemoryStore.kt): `src/com/legacydroid/luminaai/data/MemoryStore.kt`

### System capabilities

- [Clipboard tools](https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/data/ClipboardTools.kt): `src/com/legacydroid/luminaai/data/ClipboardTools.kt`
- [Device tools](https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/data/SystemTools.kt): `src/com/legacydroid/luminaai/data/SystemTools.kt`
- [Notification buffer](https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/data/NotificationHub.kt): `src/com/legacydroid/luminaai/data/NotificationHub.kt`
- [Local search index](https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/data/LocalSearchIndex.kt): `src/com/legacydroid/luminaai/data/LocalSearchIndex.kt`
- [Privacy audit](https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/data/PrivacyAudit.kt): `src/com/legacydroid/luminaai/data/PrivacyAudit.kt`

### Live2D avatar

- [Avatar controller](https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/live2d/Live2DController.kt): `src/com/legacydroid/luminaai/live2d/Live2DController.kt`
- [Avatar view](https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/live2d/LuminaAvatar.kt): `src/com/legacydroid/luminaai/live2d/LuminaAvatar.kt`
- [Kotlin JNI bridge](https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/src/com/legacydroid/luminaai/live2d/Live2DBridge.kt): `src/com/legacydroid/luminaai/live2d/Live2DBridge.kt`
- [Native JNI bridge](https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/live2d/cpp/JniBridgeC.cpp): `live2d/cpp/JniBridgeC.cpp`
- [Render engine](https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/live2d/cpp/Live2DEngine.cpp): `live2d/cpp/Live2DEngine.cpp`
- [Cubism model](https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/live2d/cpp/SampleModel.cpp): `live2d/cpp/SampleModel.cpp`
- [Texture manager](https://github.com/legacydroid/android_packages_apps_luminaai/blob/legacydroid-14/live2d/cpp/LAppTextureManager.cpp): `live2d/cpp/LAppTextureManager.cpp`

### Other components

- **User**
- **Android system**
- **Assistant service**

## Connections

- User → Overlay activity: opens
- Overlay activity → Overlay composition: hosts
- Overlay activity → Assistant session: awakens
- Overlay composition → Chat overlay: renders
- Chat overlay → Assistant session: sends input
- Assistant session → Assistant API: requests reply
- Assistant API → Assistant service: sends request
- Assistant service → Assistant API: returns reply
- Assistant session → Tool registry: dispatches tools
- Tool registry → Device tools: executes
- Tool registry → Clipboard tools: executes
- Tool registry → Notification buffer: reads
- Tool registry → Local search index: searches
- Tool registry → Privacy audit: audits
- Tool registry → Long-term memory: manages
- Assistant session → Chat history: saves sessions
- Assistant session → Long-term memory: loads memories
- Device tools → Android system: reads and controls
- Clipboard tools → Android system: accesses clipboard
- Notification buffer → Android system: receives notifications
- Local search index → Android system: queries records
- Privacy audit → Android system: checks permissions
- Tool registry → Avatar controller: controls avatar
- Overlay composition → Avatar view: shows avatar
- Avatar view → Avatar controller: drives rendering
- Avatar controller → Kotlin JNI bridge: calls native methods
- Kotlin JNI bridge → Native JNI bridge: invokes JNI
- Native JNI bridge → Render engine: forwards calls
- Render engine → Cubism model: renders and animates
- Cubism model → Texture manager: loads textures