# marlon0066/ai-pocket-chat architecture

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

- Interactive diagram: https://gitdiagram.com/marlon0066/ai-pocket-chat
- Repository: https://github.com/marlon0066/ai-pocket-chat

## Overview

AI Pocket Chat is a native Android companion app whose data is stored on-device and whose chat uses a user-configured LLM provider. The principal workflow is chat through the app, with conversation history and character memory informing generation, then a response shown in the conversation. The repository also has distinct story, social, diary, voice, and explorable-world capabilities. The README documents these product branches; sampled sources and the SOURCE INDEX support only some internal links, so unsampled feature wiring is not asserted.

Main entry points: [`app/src/main/java/com/situ/aichat/ui/chat/AssistantTurnEngine.kt`](https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/ui/chat/AssistantTurnEngine.kt) (Chat turn), [`app/src/main/java/com/situ/aichat/data/local/AppDatabase.kt`](https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/data/local/AppDatabase.kt) (On-device database), [`app/src/main/java/com/situ/aichat/prompt/memory/MemoryService.kt`](https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/prompt/memory/MemoryService.kt) (Memory service), [`app/src/main/java/com/situ/aichat/diagnostics/ContextLogService.kt`](https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/diagnostics/ContextLogService.kt) (LLM context and logs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["App experience"]
  node_app["Android app<br/>[MainActivity.kt]"]
end

subgraph group_conversation["Chat and memory"]
  node_chat["Chat turn"]
  node_memory["Memory service<br/>[MemoryService.kt]"]
  node_contextlog["LLM context and logs"]
  node_llm["LLM client<br/>[LlmClient.kt]"]
end

subgraph group_companion["Companion features"]
  node_stories["Interactive stories"]
  node_moments["Social moments"]
  node_diary["Diaries and reviews"]
  node_gifts["Gifts and red packets"]
  node_voice["Voice calls"]
  node_speech["Offline speech recognition<br/>[SherpaSttEngine.kt]"]
  node_world["Explorable world"]
end

subgraph group_platform["Local data and services"]
  node_messages[("Messages")]
  node_conversations[("Conversations")]
  node_characters[("Characters")]
  node_settings["Provider settings"]
  node_database[("On-device database<br/>[AppDatabase.kt]")]
end

node_user(("User"))
node_provider{{"Configured LLM provider"}}

node_user -->|"uses"| node_app
node_app -.->|"starts chat"| node_chat
node_chat -.->|"reads and writes"| node_messages
node_chat -.->|"uses history"| node_conversations
node_chat -.->|"uses character"| node_characters
node_chat -.->|"uses memory"| node_memory
node_memory -->|"reads history"| node_messages
node_memory -->|"requests completion"| node_contextlog
node_contextlog -->|"calls"| node_llm
node_contextlog -.->|"records logs"| node_database
node_llm -.->|"sends requests"| node_provider
node_settings -->|"configures access"| node_provider
node_chat -.->|"returns reply"| node_user
node_user -->|"creates stories"| node_stories
node_user -->|"uses social feed"| node_moments
node_user -->|"uses diaries"| node_diary
node_user -->|"interacts with"| node_gifts
node_user -->|"starts calls"| node_voice
node_voice -.->|"uses speech input"| node_speech
node_user -->|"explores"| node_world
node_messages -.->|"persists in"| node_database
node_conversations -.->|"persists in"| node_database
node_characters -.->|"persists in"| node_database

click node_app "https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/MainActivity.kt"
click node_chat "https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/ui/chat/AssistantTurnEngine.kt"
click node_messages "https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/data/repository/MessageRepository.kt"
click node_conversations "https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/data/repository/ConversationRepository.kt"
click node_characters "https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/data/repository/CharacterRepository.kt"
click node_memory "https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/prompt/memory/MemoryService.kt"
click node_contextlog "https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/diagnostics/ContextLogService.kt"
click node_llm "https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/data/remote/llm/LlmClient.kt"
click node_settings "https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/data/repository/ApiConfigRepository.kt"
click node_stories "https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/story/StoryGenerationService.kt"
click node_moments "https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/moments/MomentChatContextService.kt"
click node_diary "https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/prompt/diary/MonthlyReviewService.kt"
click node_gifts "https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/gift/ProactiveGiftLLMService.kt"
click node_voice "https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/voice/VoiceCallTurnService.kt"
click node_speech "https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/stt/SherpaSttEngine.kt"
click node_world "https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/world/stage/WorldStageService.kt"
click node_database "https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/data/local/AppDatabase.kt"

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_user toneBlue
class node_chat,node_memory,node_contextlog,node_llm toneAmber
class node_stories,node_moments,node_diary,node_gifts,node_voice,node_speech,node_world toneMint
class node_messages,node_conversations,node_characters,node_settings,node_database toneRose
class node_provider toneIndigo
```

## Components

### App experience

- [Android app](https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/MainActivity.kt): `app/src/main/java/com/situ/aichat/MainActivity.kt`

### Chat and memory

- [Chat turn](https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/ui/chat/AssistantTurnEngine.kt): `app/src/main/java/com/situ/aichat/ui/chat/AssistantTurnEngine.kt`
- [Memory service](https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/prompt/memory/MemoryService.kt): `app/src/main/java/com/situ/aichat/prompt/memory/MemoryService.kt`
- [LLM context and logs](https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/diagnostics/ContextLogService.kt): `app/src/main/java/com/situ/aichat/diagnostics/ContextLogService.kt`
- [LLM client](https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/data/remote/llm/LlmClient.kt): `app/src/main/java/com/situ/aichat/data/remote/llm/LlmClient.kt`

### Companion features

- [Interactive stories](https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/story/StoryGenerationService.kt): `app/src/main/java/com/situ/aichat/story/StoryGenerationService.kt`
- [Social moments](https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/moments/MomentChatContextService.kt): `app/src/main/java/com/situ/aichat/moments/MomentChatContextService.kt`
- [Diaries and reviews](https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/prompt/diary/MonthlyReviewService.kt): `app/src/main/java/com/situ/aichat/prompt/diary/MonthlyReviewService.kt`
- [Gifts and red packets](https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/gift/ProactiveGiftLLMService.kt): `app/src/main/java/com/situ/aichat/gift/ProactiveGiftLLMService.kt`
- [Voice calls](https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/voice/VoiceCallTurnService.kt): `app/src/main/java/com/situ/aichat/voice/VoiceCallTurnService.kt`
- [Offline speech recognition](https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/stt/SherpaSttEngine.kt): `app/src/main/java/com/situ/aichat/stt/SherpaSttEngine.kt`
- [Explorable world](https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/world/stage/WorldStageService.kt): `app/src/main/java/com/situ/aichat/world/stage/WorldStageService.kt`

### Local data and services

- [Messages](https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/data/repository/MessageRepository.kt): `app/src/main/java/com/situ/aichat/data/repository/MessageRepository.kt`
- [Conversations](https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/data/repository/ConversationRepository.kt): `app/src/main/java/com/situ/aichat/data/repository/ConversationRepository.kt`
- [Characters](https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/data/repository/CharacterRepository.kt): `app/src/main/java/com/situ/aichat/data/repository/CharacterRepository.kt`
- [Provider settings](https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/data/repository/ApiConfigRepository.kt): `app/src/main/java/com/situ/aichat/data/repository/ApiConfigRepository.kt`
- [On-device database](https://github.com/marlon0066/ai-pocket-chat/blob/main/app/src/main/java/com/situ/aichat/data/local/AppDatabase.kt): `app/src/main/java/com/situ/aichat/data/local/AppDatabase.kt`

### Other components

- **User**
- **Configured LLM provider**

## Connections

- User → Android app: uses (evidence: `README.md`)
- Android app → Chat turn: starts chat
- Chat turn → Messages: reads and writes (evidence: `app/src/main/java/com/situ/aichat/ui/chat/AssistantTurnEngine.kt`)
- Chat turn → Conversations: uses history (evidence: `app/src/main/java/com/situ/aichat/ui/chat/AssistantTurnEngine.kt`)
- Chat turn → Characters: uses character (evidence: `app/src/main/java/com/situ/aichat/ui/chat/AssistantTurnEngine.kt`)
- Chat turn → Memory service: uses memory
- Memory service → Messages: reads history (evidence: `app/src/main/java/com/situ/aichat/prompt/memory/MemoryService.kt`)
- Memory service → LLM context and logs: requests completion (evidence: `app/src/main/java/com/situ/aichat/prompt/memory/MemoryService.kt`)
- LLM context and logs → LLM client: calls (evidence: `app/src/main/java/com/situ/aichat/diagnostics/ContextLogService.kt`)
- LLM context and logs → On-device database: records logs
- LLM client → Configured LLM provider: sends requests
- Provider settings → Configured LLM provider: configures access (evidence: `README.md`)
- Chat turn → User: returns reply
- User → Interactive stories: creates stories (evidence: `README.md`)
- User → Social moments: uses social feed (evidence: `README.md`)
- User → Diaries and reviews: uses diaries (evidence: `README.md`)
- User → Gifts and red packets: interacts with (evidence: `README.md`)
- User → Voice calls: starts calls (evidence: `README.md`)
- Voice calls → Offline speech recognition: uses speech input
- User → Explorable world: explores (evidence: `README.md`)
- Messages → On-device database: persists in
- Conversations → On-device database: persists in
- Characters → On-device database: persists in (evidence: `app/src/main/java/com/situ/aichat/data/repository/CharacterRepository.kt`)
