How rikkahub/rikkahub works
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 ViewModels.
- Those ViewModels 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: rikkahub RikkaHub app · data App data · ai AI pipeline · common Common module
Components 17
Android app
Main RikkaHub Android runtime and UI shell.
- RikkaHub app · Main Compose-based Android application coordinating chat, settings, history, backup, and developer flows.
app/src/main/java/me/rerere/rikkahub - Compose UI · 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 · ConversationSession and ChatService manage streaming, tool use, memory, and message transformation.
app/src/main/java/me/rerere/rikkahub/service - App data · Repositories and data pipelines bridging UI, persistence, providers, search, sync, files, and export/import.
app/src/main/java/me/rerere/rikkahub/data - AI pipeline · 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 · Conversation, message branching, favorites, memory, media, and files persisted through Room and migrations.
app/src/main/java/me/rerere/rikkahub/data/db - Preferences store · DataStore-backed settings and provider configuration with migration helpers.
app/src/main/java/me/rerere/rikkahub/data/datastore - Backup 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 · Shared LLM abstraction with provider manager, shared chat concepts, model registry, and provider adapters.
ai/src/main/java/me/rerere/ai - Search module · Standalone search capability layer with multiple provider implementations and a common service abstraction.
search/src/main/java/me/rerere/search - TTS module · Text-to-speech provider manager plus synthesis, chunking, and playback controllers.
tts/src/main/java/me/rerere/tts - Document module · MuPDF-based document parsing for PDF, DOCX, and PPTX inputs.
document/src/main/java/me/rerere/document - Highlight module · Code highlighting support for rendered chat content and markdown.
highlight/src/main/java/me/rerere/highlight - Common module · 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 · 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 · 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 · Standalone Python terminal app for translation management and dead-entry cleanup.
locale-tui/src
Connections 22
- 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.