# rikkahub/rikkahub architecture

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

- Interactive diagram: https://gitdiagram.com/rikkahub/rikkahub
- Repository: https://github.com/rikkahub/rikkahub

## Overview

1. **Repository shape**
   - This is a multi-module Kotlin/Android monorepo centered on the **RikkaHub** Android app.
   - It also contains a **separate embedded web API/server**, a **React-based web UI**, a **Python localization TUI**, and several reusable Android library modules (`ai`, `search`, `tts`, `document`, `highlight`, `common`).

2. **Primary product boundary: the Android app**
   - `app` is the main runtime and UI shell.
   - It uses **Jetpack Compose** for all screens, **Koin** for dependency injection, **Room** for local persistence, and **DataStore** for settings/provider configuration.
   - The app is organized around feature pages such as chat, assistant management, settings, backup, history, search, translation, image generation, logs, and debug/developer tools.

3. **Core interaction flow**
   - User actions enter through Compose pages and their `ViewModel`s.
   - Those `ViewModel`s call repositories/services in `app/data`, which then coordinate:
     - local state (`Room`, `DataStore`)
     - model/provider calls (`ai` module)
     - search services (`search` module)
     - TTS playback (`tts` module)
     - document parsing (`document` module)
     - sync/export/import pipelines
   - The chat experience is not just a simple request/response UI; it is orchestrated by `ChatService` and `ConversationSession`, which manage streaming, tool use, memory, and message transformations.

4. **AI provider abstraction**
   - The `ai` module is the lowest-level LLM integration layer.
   - It defines shared chat concepts (`MessageRole`, `Reasoning`, `Tool`, `Usage`) and a provider abstraction (`Provider`, `ProviderManager`, `ProviderSetting`, `ModelRegistry`).
   - Concrete providers include **OpenAI**, **Claude**, and **Google/Vertex** paths, with provider-specific request/message adapters and streaming utilities.
   - This module is designed so the app can switch models/providers without changing the UI layer.

5. **Prompting, transforms, and agent behavior**
   - The app’s AI pipeline includes a significant transformation layer under `app/data/ai`.
   - Prompts are specialized by task: translation, OCR, compression, title summary, suggestion, learning mode, etc.
   - Transformers rewrite or post-process inputs/outputs, including:
     - prompt injection protection
     - regex-based output extraction
     - template expansion
     - think-tag parsing
     - time reminders
     - OCR/document-to-prompt conversion
   - This is a key architectural boundary: raw user content is normalized before it reaches the provider, and model output is parsed before it reaches the UI.

6. **Conversation and local data model**
   - The app persists conversational state in Room with entities and DAOs for:
     - conversations
     - message nodes / branching
     - favorites
     - memory
     - generated media
     - managed files
   - The schema history in `app/schemas` and the explicit migration classes show that the database is a long-lived core subsystem.
   - Conversation branching, favorites, and memory are first-class features, not just UI embellishments.

7. **Settings and provider configuration**
   - User preferences and provider settings live in DataStore via `PreferencesStore` and migration helpers.
   - Provider configuration, default providers, and import/export of assistant settings are handled in the app layer and exposed through dedicated settings pages.
   - The assistant pages in `ui/pages/assistant/detail` let users configure prompts, request headers/body, local tools, memory, MCP, and other behavior per assistant.

8. **Search, MCP, and TTS as external capability layers**
   - `search` is a standalone module with multiple provider implementations: Bing, Brave, Exa, Tavily, Perplexity, SearXNG, Jina, Firecrawl, and others.
   - `tts` is another separate module with a provider manager and multiple speech vendors, plus audio playback and chunking/synthesis controllers.
   - MCP support lives in `app/data/ai/mcp`, with config, status, manager, and transport implementations for SSE and streamable HTTP.
   - These are all capability modules that plug into chat/assistant behavior rather than being independent app features.

9. **Document, OCR, and rich media handling**
   - `document` wraps MuPDF-based parsing for PDF/DOCX/PPTX and exposes parsers used by the app’s document pipeline.
   - The app also contains transformers for turning images/base64 into local files, OCR, and document-as-prompt conversion.
   - The `highlight` module provides code highlighting support for rendered chat content and markdown rendering.
   - This means messages are multimodal: text, images, documents, code blocks, and structured outputs all have dedicated handling paths.

10. **Persistence, sync, and import/export**
   - The app supports backup and synchronization through:
     - import/export hooks
     - WebDAV sync
     - S3 sync with explicit AWS Signature V4 support
     - provider imports such as Cherry Studio
   - Data export is not limited to a database dump; it includes assistant/provider settings and conversation-related artifacts.
   - The backup UI is a separate feature area with tabs for import/export, reminders, S3, and WebDAV.

11. **Embedded web server and external web UI**
   - The `web` module is the Android-side server runtime; it exposes routes for conversations, files, settings, and AI icons.
   - `WebServerService`, `WebServerManager`, and `NsdServiceRegistrar` indicate that the app can publish a local network service and serve an API to other clients.
   - `web-ui` is a separate React app that consumes this API and mirrors major chat workflows: conversation browsing, message rendering, input composition, settings, and workbench features.
   - Architecturally, the Android app is the source of truth, and the web UI is a client of the embedded service rather than an independent backend.

12. **Shared infrastructure and utilities**
   - `common` contains reusable HTTP, SSE, cache, and Android utility code shared by multiple modules.
   - The app also has its own utility layer for JSON, markdown, clipboard, notifications, crash handling, updates, and time/string helpers.
   - These libraries keep networking and serialization consistent across the provider modules, sync modules, and web server.

13. **Localization and build/tooling**
   - `locale-tui` is a standalone Python tool for managing Android string translations and dead-entry cleanup.
   - The repository has release automation in GitHub Actions, baseline profile generation for app startup performance, and multilingual resources in the Android app.
   - There are also repo-specific Claude/agent skill files and scripts, which support maintenance but do not change the runtime architecture.

14. **High-level diagram view**
   - The central node is the **Android app**.
   - Its major outbound edges go to:
     - LLM providers via `ai`
     - search providers via `search`
     - speech providers via `tts`
     - document parsers via `document`
     - local storage via Room/DataStore
     - sync targets via WebDAV/S3
     - embedded local web clients via `web` and `web-ui`
   - Most feature screens are thin Compose presentations over these shared services and repositories, with the chat subsystem acting as the main orchestration hub.

Main entry points: [`app/src/main/java/me/rerere/rikkahub`](https://github.com/rikkahub/rikkahub/tree/master/app/src/main/java/me/rerere/rikkahub) (RikkaHub app), [`app/src/main/java/me/rerere/rikkahub/data`](https://github.com/rikkahub/rikkahub/tree/master/app/src/main/java/me/rerere/rikkahub/data) (App data), [`app/src/main/java/me/rerere/rikkahub/data/ai`](https://github.com/rikkahub/rikkahub/tree/master/app/src/main/java/me/rerere/rikkahub/data/ai) (AI pipeline), [`common/src/main/java/me/rerere/common`](https://github.com/rikkahub/rikkahub/tree/master/common/src/main/java/me/rerere/common) (Common module)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_android["Android app"]
  node_app["RikkaHub app<br/>android shell"]
  node_app_ui["Compose UI<br/>screens"]
  node_app_service["Chat service<br/>orchestration"]
  node_app_data["App data<br/>repositories"]
  node_app_ai["AI pipeline<br/>prompt+transform"]
  node_app_db[("Room store<br/>persistence")]
  node_app_ds[("Preferences store<br/>datastore")]
  node_app_sync["Backup sync"]
end

subgraph group_libs["Shared modules"]
  node_ai["AI module<br/>llm core"]
  node_search["Search module<br/>search providers"]
  node_tts["TTS module<br/>speech providers"]
  node_document["Document module<br/>parsers"]
  node_highlight["Highlight module<br/>code rendering"]
  node_common["Common module<br/>shared infra"]
end

subgraph group_web["Web clients"]
  node_app_web["Web server<br/>embedded api"]
  node_web_ui["Web UI<br/>react client"]
end

subgraph group_tools["Tooling"]
  node_locale_tui["Locale TUI<br/>python tool"]
end

node_app -->|"renders"| node_app_ui
node_app -->|"drives"| node_app_service
node_app -->|"uses"| node_app_data
node_app -->|"persists"| node_app_db
node_app -->|"stores settings"| node_app_ds
node_app -->|"builds prompts"| node_app_ai
node_app -->|"backs up"| node_app_sync
node_app_data -->|"calls"| node_ai
node_app_data -->|"searches"| node_search
node_app_data -->|"speaks"| node_tts
node_app_data -->|"parses"| node_document
node_app_ai -->|"adapts to"| node_ai
node_app_ai -->|"tools"| node_search
node_app_ai -->|"tools"| node_tts
node_app_web -->|"serves data"| node_app_data
node_web_ui -->|"consumes"| node_app_web
node_common -->|"supports"| node_ai
node_common -->|"supports"| node_search
node_common -->|"supports"| node_tts
node_locale_tui -->|"maintains i18n"| node_app
node_app -->|"renders code"| node_highlight
node_app -->|"multimodal input"| node_document

click node_app "https://github.com/rikkahub/rikkahub/tree/master/app/src/main/java/me/rerere/rikkahub"
click node_app_ui "https://github.com/rikkahub/rikkahub/tree/master/app/src/main/java/me/rerere/rikkahub/ui"
click node_app_service "https://github.com/rikkahub/rikkahub/tree/master/app/src/main/java/me/rerere/rikkahub/service"
click node_app_data "https://github.com/rikkahub/rikkahub/tree/master/app/src/main/java/me/rerere/rikkahub/data"
click node_app_ai "https://github.com/rikkahub/rikkahub/tree/master/app/src/main/java/me/rerere/rikkahub/data/ai"
click node_app_db "https://github.com/rikkahub/rikkahub/tree/master/app/src/main/java/me/rerere/rikkahub/data/db"
click node_app_ds "https://github.com/rikkahub/rikkahub/tree/master/app/src/main/java/me/rerere/rikkahub/data/datastore"
click node_app_sync "https://github.com/rikkahub/rikkahub/tree/master/app/src/main/java/me/rerere/rikkahub/data/sync"
click node_app_web "https://github.com/rikkahub/rikkahub/tree/master/web/src/main/java/me/rerere/rikkahub/web"
click node_web_ui "https://github.com/rikkahub/rikkahub/tree/master/web-ui/app"
click node_ai "https://github.com/rikkahub/rikkahub/tree/master/ai/src/main/java/me/rerere/ai"
click node_search "https://github.com/rikkahub/rikkahub/tree/master/search/src/main/java/me/rerere/search"
click node_tts "https://github.com/rikkahub/rikkahub/tree/master/tts/src/main/java/me/rerere/tts"
click node_document "https://github.com/rikkahub/rikkahub/tree/master/document/src/main/java/me/rerere/document"
click node_highlight "https://github.com/rikkahub/rikkahub/tree/master/highlight/src/main/java/me/rerere/highlight"
click node_common "https://github.com/rikkahub/rikkahub/tree/master/common/src/main/java/me/rerere/common"
click node_locale_tui "https://github.com/rikkahub/rikkahub/tree/master/locale-tui/src"

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_app,node_app_ui,node_app_service,node_app_data,node_app_ai,node_app_db,node_app_ds,node_app_sync toneBlue
class node_ai,node_search,node_tts,node_document,node_highlight,node_common toneAmber
class node_app_web,node_web_ui toneMint
class node_locale_tui toneRose
```

## Components

### Android app

Main RikkaHub Android runtime and UI shell.

- [RikkaHub app](https://github.com/rikkahub/rikkahub/tree/master/app/src/main/java/me/rerere/rikkahub): android shell · Main Compose-based Android application coordinating chat, settings, history, backup, and developer flows. · `app/src/main/java/me/rerere/rikkahub`
- [Compose UI](https://github.com/rikkahub/rikkahub/tree/master/app/src/main/java/me/rerere/rikkahub/ui): screens · Feature pages, shared components, and UI state for chat, assistant, settings, backup, search, translation, and debug. · `app/src/main/java/me/rerere/rikkahub/ui`
- [Chat service](https://github.com/rikkahub/rikkahub/tree/master/app/src/main/java/me/rerere/rikkahub/service): orchestration · ConversationSession and ChatService manage streaming, tool use, memory, and message transformation. · `app/src/main/java/me/rerere/rikkahub/service`
- [App data](https://github.com/rikkahub/rikkahub/tree/master/app/src/main/java/me/rerere/rikkahub/data): repositories · Repositories and data pipelines bridging UI, persistence, providers, search, sync, files, and export/import. · `app/src/main/java/me/rerere/rikkahub/data`
- [AI pipeline](https://github.com/rikkahub/rikkahub/tree/master/app/src/main/java/me/rerere/rikkahub/data/ai): prompt+transform · Prompt templates, transformers, request logging, tool wiring, and MCP support inside the app layer. · `app/src/main/java/me/rerere/rikkahub/data/ai`
- [Room store](https://github.com/rikkahub/rikkahub/tree/master/app/src/main/java/me/rerere/rikkahub/data/db): persistence · Conversation, message branching, favorites, memory, media, and files persisted through Room and migrations. · `app/src/main/java/me/rerere/rikkahub/data/db`
- [Preferences store](https://github.com/rikkahub/rikkahub/tree/master/app/src/main/java/me/rerere/rikkahub/data/datastore): datastore · DataStore-backed settings and provider configuration with migration helpers. · `app/src/main/java/me/rerere/rikkahub/data/datastore`
- [Backup sync](https://github.com/rikkahub/rikkahub/tree/master/app/src/main/java/me/rerere/rikkahub/data/sync): sync · Import/export, WebDAV, S3, and provider migration flows for user data and settings. · `app/src/main/java/me/rerere/rikkahub/data/sync`

### Shared modules

Reusable capability libraries used by the app and server.

- [AI module](https://github.com/rikkahub/rikkahub/tree/master/ai/src/main/java/me/rerere/ai): llm core · Shared LLM abstraction with provider manager, shared chat concepts, model registry, and provider adapters. · `ai/src/main/java/me/rerere/ai`
- [Search module](https://github.com/rikkahub/rikkahub/tree/master/search/src/main/java/me/rerere/search): search providers · Standalone search capability layer with multiple provider implementations and a common service abstraction. · `search/src/main/java/me/rerere/search`
- [TTS module](https://github.com/rikkahub/rikkahub/tree/master/tts/src/main/java/me/rerere/tts): speech providers · Text-to-speech provider manager plus synthesis, chunking, and playback controllers. · `tts/src/main/java/me/rerere/tts`
- [Document module](https://github.com/rikkahub/rikkahub/tree/master/document/src/main/java/me/rerere/document): parsers · MuPDF-based document parsing for PDF, DOCX, and PPTX inputs. · `document/src/main/java/me/rerere/document`
- [Highlight module](https://github.com/rikkahub/rikkahub/tree/master/highlight/src/main/java/me/rerere/highlight): code rendering · Code highlighting support for rendered chat content and markdown. · `highlight/src/main/java/me/rerere/highlight`
- [Common module](https://github.com/rikkahub/rikkahub/tree/master/common/src/main/java/me/rerere/common): shared infra · Shared HTTP, SSE, cache, and Android utility primitives used across modules. · `common/src/main/java/me/rerere/common`

### Web clients

Embedded server and separate browser UI client.

- [Web server](https://github.com/rikkahub/rikkahub/tree/master/web/src/main/java/me/rerere/rikkahub/web): embedded api · Android-hosted local API runtime exposing conversations, files, settings, and AI icons over the network. · `web/src/main/java/me/rerere/rikkahub/web`
- [Web UI](https://github.com/rikkahub/rikkahub/tree/master/web-ui/app): react client · Separate React app that consumes the embedded API for chat browsing, composing, settings, and workbench features. · `web-ui/app`

### Tooling

Standalone maintenance and release support tools.

- [Locale TUI](https://github.com/rikkahub/rikkahub/tree/master/locale-tui/src): python tool · Standalone Python terminal app for translation management and dead-entry cleanup. · `locale-tui/src`

## Connections

- RikkaHub app → Compose UI: renders · Compose pages and shared UI make up the product shell.
- RikkaHub app → Chat service: drives · User actions flow into chat orchestration services.
- RikkaHub app → App data: uses · ViewModels and services coordinate through repositories and data pipelines.
- RikkaHub app → Room store: persists · Primary conversational and media state lives in Room.
- RikkaHub app → Preferences store: stores settings · Provider and app preferences are managed in DataStore.
- RikkaHub app → AI pipeline: builds prompts · The app assembles prompts, tools, and transformations before provider calls.
- RikkaHub app → Backup sync: backs up · Import/export and remote sync are handled in the app layer.
- App data → AI module: calls · Repositories and services invoke the shared LLM provider layer.
- App data → Search module: searches · Search features delegate to the shared search capability module.
- App data → TTS module: speaks · TTS playback and synthesis are routed through the speech module.
- App data → Document module: parses · Document and OCR pipelines depend on the document parser module.
- AI pipeline → AI module: adapts to · App-level prompts and transformers feed the provider abstraction.
- AI pipeline → Search module: tools · Search is exposed as an assistant tool capability.
- AI pipeline → TTS module: tools · Speech-related actions integrate through the TTS capability layer.
- Web server → App data: serves data · Embedded API endpoints expose app-owned conversations, files, and settings.
- Web UI → Web server: consumes · The React client talks to the local embedded server API.
- Common module → AI module: supports · Shared HTTP, SSE, and serialization utilities underpin provider integrations.
- Common module → Search module: supports · Search providers reuse the shared networking and cache primitives.
- Common module → TTS module: supports · Speech providers share common request and stream utilities.
- Locale TUI → RikkaHub app: maintains i18n · The Python tool manages Android string resources for the app.
- RikkaHub app → Highlight module: renders code · Chat and markdown rendering use code highlighting support.
- RikkaHub app → Document module: multimodal input · Documents are converted into promptable content inside the app pipeline.
