# vali-98/chatterui architecture

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

- Interactive diagram: https://gitdiagram.com/vali-98/chatterui
- Repository: https://github.com/vali-98/chatterui

## Overview

ChatterUI is a native mobile frontend for chatting with characters or assistants through either on-device models or remote APIs. The main workflow is to select a character and chat, build a prompt from chat and character context, route generation to local inference or a configured API, then display the response. The app also manages characters, chat history, connections, formatting, sampler settings, lorebooks, users, and TTS. Some screen-to-state and database links are documented only at the product level; those links are dashed where source evidence was not sampled.

Main entry points: [`lib/state/Characters.ts`](https://github.com/vali-98/chatterui/blob/master/lib/state/Characters.ts) (Character state), [`lib/engine/Inference.ts`](https://github.com/vali-98/chatterui/blob/master/lib/engine/Inference.ts) (Inference router), [`lib/engine/API/APIBuilder.ts`](https://github.com/vali-98/chatterui/blob/master/lib/engine/API/APIBuilder.ts) (API request builder), [`lib/engine/API/ContextBuilder.ts`](https://github.com/vali-98/chatterui/blob/master/lib/engine/API/ContextBuilder.ts) (Context builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Chat experience"]
  node_character_ui["Character browser<br/>[index.tsx]"]
  node_chat_ui["Chat screen<br/>[index.tsx]"]
end

subgraph group_generation["Generation"]
  node_inference["Inference router<br/>[Inference.ts]"]
  node_context["Context builder<br/>[ContextBuilder.ts]"]
  node_sources["Context sources<br/>[index.ts]"]
  node_lore_source["Lorebook source<br/>[lorebookSource.ts]"]
  node_local_inference["Local inference<br/>[LocalInference.ts]"]
  node_llama["Llama runtime<br/>[LlamaLocal.ts]"]
  node_api_builder["API request builder<br/>[APIBuilder.ts]"]
  node_api_defaults["API providers<br/>[DefaultAPI.ts]"]
end

subgraph group_management["Content and settings"]
  node_character_editor["Character editor"]
  node_connections["Connection manager<br/>[index.tsx]"]
  node_formatting["Formatting manager<br/>[index.tsx]"]
  node_samplers["Sampler settings<br/>[index.tsx]"]
  node_lorebooks["Lorebook manager<br/>[index.tsx]"]
  node_users["User manager<br/>[index.tsx]"]
  node_tts["TTS manager"]
  node_model_manager["Model manager<br/>[index.tsx]"]
  node_settings["App settings<br/>[index.tsx]"]
end

subgraph group_persistence["State and persistence"]
  node_chat_state["Chat state<br/>[Chat.ts]"]
  node_character_state["Character state<br/>[Characters.ts]"]
  node_sqlite[("App database<br/>[schema.ts]")]
  node_author_notes["Author notes<br/>[AuthorNotes.ts]"]
  node_mmkv[("MMKV storage<br/>[MMKV.ts]")]
  node_startup["Startup setup<br/>[Startup.ts]"]
  node_theme["Theme state<br/>[ThemeManager.ts]"]
  node_logger["Log state<br/>[Logger.ts]"]
end

node_user(("Mobile user"))
node_remote_service{{"Remote model APIs"}}

node_user -.->|"browses characters"| node_character_ui
node_user -.->|"chats"| node_chat_ui
node_character_ui -.->|"selects character"| node_character_state
node_chat_ui -.->|"requests generation"| node_inference
node_inference -->|"routes local"| node_local_inference
node_inference -->|"routes remote"| node_api_builder
node_inference -->|"loads sources"| node_sources
node_inference -->|"reads chat state"| node_chat_state
node_inference -->|"reads character state"| node_character_state
node_local_inference -->|"builds prompt"| node_context
node_local_inference -->|"runs model"| node_llama
node_api_builder -->|"builds request context"| node_context
node_api_builder -.->|"sends request"| node_remote_service
node_api_builder -.->|"uses provider config"| node_api_defaults
node_sources -->|"registers source"| node_lore_source
node_context -->|"reads chat content"| node_chat_state
node_context -->|"reads character data"| node_character_state
node_chat_ui -.->|"manages chats"| node_chat_state
node_character_editor -.->|"edits characters"| node_character_state
node_connections -.->|"configures connections"| node_api_builder
node_formatting -.->|"configures formatting"| node_context
node_samplers -.->|"configures samplers"| node_api_builder
node_lorebooks -.->|"manages lorebooks"| node_lore_source
node_users -.->|"manages user card"| node_character_state
node_model_manager -.->|"manages local models"| node_llama
node_tts -.->|"provides speech"| node_chat_ui
node_settings -.->|"configures appearance"| node_theme
node_character_state -->|"persists state"| node_mmkv
node_logger -->|"persists logs"| node_mmkv
node_theme -->|"persists colors"| node_mmkv
node_author_notes -->|"reads and writes notes"| node_sqlite
node_startup -->|"initializes user data"| node_character_state
node_startup -->|"runs migrations"| node_sqlite
node_chat_state -.->|"stores chat data"| node_sqlite

click node_character_ui "https://github.com/vali-98/chatterui/blob/master/app/screens/CharacterListScreen/index.tsx"
click node_chat_ui "https://github.com/vali-98/chatterui/blob/master/app/screens/ChatScreen/index.tsx"
click node_chat_state "https://github.com/vali-98/chatterui/blob/master/lib/state/Chat.ts"
click node_character_state "https://github.com/vali-98/chatterui/blob/master/lib/state/Characters.ts"
click node_inference "https://github.com/vali-98/chatterui/blob/master/lib/engine/Inference.ts"
click node_context "https://github.com/vali-98/chatterui/blob/master/lib/engine/API/ContextBuilder.ts"
click node_sources "https://github.com/vali-98/chatterui/blob/master/lib/engine/DataSources/index.ts"
click node_lore_source "https://github.com/vali-98/chatterui/blob/master/lib/engine/DataSources/lorebookSource.ts"
click node_local_inference "https://github.com/vali-98/chatterui/blob/master/lib/engine/LocalInference.ts"
click node_llama "https://github.com/vali-98/chatterui/blob/master/lib/engine/Local/LlamaLocal.ts"
click node_api_builder "https://github.com/vali-98/chatterui/blob/master/lib/engine/API/APIBuilder.ts"
click node_api_defaults "https://github.com/vali-98/chatterui/blob/master/lib/engine/API/DefaultAPI.ts"
click node_character_editor "https://github.com/vali-98/chatterui/blob/master/app/screens/CharacterEditorScreen.tsx"
click node_connections "https://github.com/vali-98/chatterui/blob/master/app/screens/ConnectionsManagerScreen/index.tsx"
click node_formatting "https://github.com/vali-98/chatterui/blob/master/app/screens/FormattingManagerScreen/index.tsx"
click node_samplers "https://github.com/vali-98/chatterui/blob/master/app/screens/SamplerManagerScreen/index.tsx"
click node_lorebooks "https://github.com/vali-98/chatterui/blob/master/app/screens/LorebookManagerScreen/index.tsx"
click node_users "https://github.com/vali-98/chatterui/blob/master/app/screens/UserManagerScreen/index.tsx"
click node_tts "https://github.com/vali-98/chatterui/blob/master/app/screens/TTSManagerScreen.tsx"
click node_model_manager "https://github.com/vali-98/chatterui/blob/master/app/screens/ModelManagerScreen/index.tsx"
click node_settings "https://github.com/vali-98/chatterui/blob/master/app/screens/AppSettingsScreen/index.tsx"
click node_sqlite "https://github.com/vali-98/chatterui/blob/master/db/schema.ts"
click node_author_notes "https://github.com/vali-98/chatterui/blob/master/lib/state/AuthorNotes.ts"
click node_mmkv "https://github.com/vali-98/chatterui/blob/master/lib/storage/MMKV.ts"
click node_startup "https://github.com/vali-98/chatterui/blob/master/lib/utils/Startup.ts"
click node_theme "https://github.com/vali-98/chatterui/blob/master/lib/theme/ThemeManager.ts"
click node_logger "https://github.com/vali-98/chatterui/blob/master/lib/state/Logger.ts"

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_character_ui,node_chat_ui,node_user toneBlue
class node_inference,node_context,node_sources,node_lore_source,node_local_inference,node_llama,node_api_builder,node_api_defaults toneAmber
class node_character_editor,node_connections,node_formatting,node_samplers,node_lorebooks,node_users,node_tts,node_model_manager,node_settings,node_remote_service toneMint
class node_chat_state,node_character_state,node_sqlite,node_author_notes,node_mmkv,node_startup,node_theme,node_logger toneRose
```

## Components

### Chat experience

- [Character browser](https://github.com/vali-98/chatterui/blob/master/app/screens/CharacterListScreen/index.tsx): `app/screens/CharacterListScreen/index.tsx`
- [Chat screen](https://github.com/vali-98/chatterui/blob/master/app/screens/ChatScreen/index.tsx): `app/screens/ChatScreen/index.tsx`

### Generation

- [Inference router](https://github.com/vali-98/chatterui/blob/master/lib/engine/Inference.ts): `lib/engine/Inference.ts`
- [Context builder](https://github.com/vali-98/chatterui/blob/master/lib/engine/API/ContextBuilder.ts): `lib/engine/API/ContextBuilder.ts`
- [Context sources](https://github.com/vali-98/chatterui/blob/master/lib/engine/DataSources/index.ts): `lib/engine/DataSources/index.ts`
- [Lorebook source](https://github.com/vali-98/chatterui/blob/master/lib/engine/DataSources/lorebookSource.ts): `lib/engine/DataSources/lorebookSource.ts`
- [Local inference](https://github.com/vali-98/chatterui/blob/master/lib/engine/LocalInference.ts): `lib/engine/LocalInference.ts`
- [Llama runtime](https://github.com/vali-98/chatterui/blob/master/lib/engine/Local/LlamaLocal.ts): `lib/engine/Local/LlamaLocal.ts`
- [API request builder](https://github.com/vali-98/chatterui/blob/master/lib/engine/API/APIBuilder.ts): `lib/engine/API/APIBuilder.ts`
- [API providers](https://github.com/vali-98/chatterui/blob/master/lib/engine/API/DefaultAPI.ts): `lib/engine/API/DefaultAPI.ts`

### Content and settings

- [Character editor](https://github.com/vali-98/chatterui/blob/master/app/screens/CharacterEditorScreen.tsx): `app/screens/CharacterEditorScreen.tsx`
- [Connection manager](https://github.com/vali-98/chatterui/blob/master/app/screens/ConnectionsManagerScreen/index.tsx): `app/screens/ConnectionsManagerScreen/index.tsx`
- [Formatting manager](https://github.com/vali-98/chatterui/blob/master/app/screens/FormattingManagerScreen/index.tsx): `app/screens/FormattingManagerScreen/index.tsx`
- [Sampler settings](https://github.com/vali-98/chatterui/blob/master/app/screens/SamplerManagerScreen/index.tsx): `app/screens/SamplerManagerScreen/index.tsx`
- [Lorebook manager](https://github.com/vali-98/chatterui/blob/master/app/screens/LorebookManagerScreen/index.tsx): `app/screens/LorebookManagerScreen/index.tsx`
- [User manager](https://github.com/vali-98/chatterui/blob/master/app/screens/UserManagerScreen/index.tsx): `app/screens/UserManagerScreen/index.tsx`
- [TTS manager](https://github.com/vali-98/chatterui/blob/master/app/screens/TTSManagerScreen.tsx): `app/screens/TTSManagerScreen.tsx`
- [Model manager](https://github.com/vali-98/chatterui/blob/master/app/screens/ModelManagerScreen/index.tsx): `app/screens/ModelManagerScreen/index.tsx`
- [App settings](https://github.com/vali-98/chatterui/blob/master/app/screens/AppSettingsScreen/index.tsx): `app/screens/AppSettingsScreen/index.tsx`

### State and persistence

- [Chat state](https://github.com/vali-98/chatterui/blob/master/lib/state/Chat.ts): `lib/state/Chat.ts`
- [Character state](https://github.com/vali-98/chatterui/blob/master/lib/state/Characters.ts): `lib/state/Characters.ts`
- [App database](https://github.com/vali-98/chatterui/blob/master/db/schema.ts): `db/schema.ts`
- [Author notes](https://github.com/vali-98/chatterui/blob/master/lib/state/AuthorNotes.ts): `lib/state/AuthorNotes.ts`
- [MMKV storage](https://github.com/vali-98/chatterui/blob/master/lib/storage/MMKV.ts): `lib/storage/MMKV.ts`
- [Startup setup](https://github.com/vali-98/chatterui/blob/master/lib/utils/Startup.ts): `lib/utils/Startup.ts`
- [Theme state](https://github.com/vali-98/chatterui/blob/master/lib/theme/ThemeManager.ts): `lib/theme/ThemeManager.ts`
- [Log state](https://github.com/vali-98/chatterui/blob/master/lib/state/Logger.ts): `lib/state/Logger.ts`

### Other components

- **Mobile user**
- **Remote model APIs**

## Connections

- Mobile user → Character browser: browses characters
- Mobile user → Chat screen: chats
- Character browser → Character state: selects character
- Chat screen → Inference router: requests generation (evidence: `lib/engine/Inference.ts`)
- Inference router → Local inference: routes local (evidence: `lib/engine/Inference.ts`)
- Inference router → API request builder: routes remote (evidence: `lib/engine/Inference.ts`)
- Inference router → Context sources: loads sources (evidence: `lib/engine/Inference.ts`)
- Inference router → Chat state: reads chat state (evidence: `lib/engine/Inference.ts`)
- Inference router → Character state: reads character state (evidence: `lib/engine/Inference.ts`)
- Local inference → Context builder: builds prompt (evidence: `lib/engine/LocalInference.ts`)
- Local inference → Llama runtime: runs model (evidence: `lib/engine/LocalInference.ts`)
- API request builder → Context builder: builds request context (evidence: `lib/engine/API/APIBuilder.ts`)
- API request builder → Remote model APIs: sends request
- API request builder → API providers: uses provider config
- Context sources → Lorebook source: registers source (evidence: `lib/engine/DataSources/index.ts`)
- Context builder → Chat state: reads chat content (evidence: `lib/engine/API/ContextBuilder.ts`)
- Context builder → Character state: reads character data (evidence: `lib/engine/API/ContextBuilder.ts`)
- Chat screen → Chat state: manages chats
- Character editor → Character state: edits characters
- Connection manager → API request builder: configures connections
- Formatting manager → Context builder: configures formatting
- Sampler settings → API request builder: configures samplers
- Lorebook manager → Lorebook source: manages lorebooks
- User manager → Character state: manages user card
- Model manager → Llama runtime: manages local models
- TTS manager → Chat screen: provides speech
- App settings → Theme state: configures appearance
- Character state → MMKV storage: persists state (evidence: `lib/state/Characters.ts`)
- Log state → MMKV storage: persists logs (evidence: `lib/state/Logger.ts`)
- Theme state → MMKV storage: persists colors (evidence: `lib/theme/ThemeManager.ts`)
- Author notes → App database: reads and writes notes (evidence: `lib/state/AuthorNotes.ts`)
- Startup setup → Character state: initializes user data (evidence: `lib/utils/Startup.ts`)
- Startup setup → App database: runs migrations (evidence: `lib/utils/Startup.ts`)
- Chat state → App database: stores chat data