# yakami129/virtualwife architecture

> Architecture diagram of the GitHub repository yakami129/virtualwife, 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/yakami129/virtualwife
- Repository: https://github.com/yakami129/virtualwife

## Overview

VirtualWife is a virtual-persona chatbot with a Django backend and a VRM-based web client. Its main user journey is configuring a character and model, chatting, and receiving streamed responses that can drive speech and avatar expression; README capabilities also include memory, custom roles, and Bilibili live interaction. The sampled evidence confirms several backend dependencies and ASGI channel wiring, but not the frontend-to-backend request path or all subsystem internals, so those relationships are left unconnected or marked unverified.

Main entry points: [`domain-chatbot/apps/chatbot/chat/chat_service.py`](https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/chat/chat_service.py) (Chat service), [`domain-chatbot/apps/chatbot/insight/bilibili/bili_live_client.py`](https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/insight/bilibili/bili_live_client.py) (Bilibili live client), [`domain-chatbot/apps/chatbot/memory/memory_storage.py`](https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/memory/memory_storage.py) (Memory driver), [`domain-chatvrm/src/pages/index.tsx`](https://github.com/yakami129/virtualwife/blob/main/domain-chatvrm/src/pages/index.tsx) (Web interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_web["Web interface<br/>[index.tsx]"]
  node_settings["Character settings<br/>[settings.tsx]"]
  node_chat_api["Chat API<br/>[chat.ts]"]
end

subgraph group_conversation["Conversation runtime"]
  node_chat_service["Chat service<br/>[chat_service.py]"]
  node_history["Chat history"]
  node_llm_driver["LLM selection"]
  node_llm_providers["LLM providers"]
end

subgraph group_persona["Persona and insight"]
  node_config["System configuration<br/>[sys_config.py]"]
  node_character["Character generation"]
  node_roles["Custom roles"]
  node_reflection["Reflection<br/>[reflection.py]"]
  node_live_client["Bilibili live client"]
  node_live_protocol["Live protocol SDK<br/>[client.py]"]
  node_live_handlers["Live message handlers<br/>[handlers.py]"]
  node_insight_queue["Insight queue"]
end

subgraph group_memory["Memory"]
  node_memory_driver["Memory driver<br/>[memory_storage.py]"]
  node_local_memory[("Local memory")]
  node_milvus_memory[("Milvus memory")]
  node_zep_memory["Zep memory<br/>[zep_memory.py]"]
end

subgraph group_delivery["Speech and avatar"]
  node_stream_queue["Realtime output queue"]
  node_ws_output["WebSocket output<br/>[consumers.py]"]
  node_tts["Speech synthesis<br/>[tts_driver.py]"]
  node_vrm_viewer["VRM avatar viewer<br/>[viewer.ts]"]
  node_expressions["Expression control"]
end

node_user(("User"))

node_user -->|"uses"| node_web
node_web -->|"configures"| node_settings
node_web -.->|"requests chat"| node_chat_api
node_chat_api -.->|"submits chat"| node_chat_service
node_chat_service -->|"loads character"| node_character
node_chat_service -->|"reads config"| node_config
node_chat_service -.->|"generates reply"| node_llm_driver
node_llm_driver -->|"selects provider"| node_llm_providers
node_llm_driver -->|"uses memory types"| node_zep_memory
node_history -->|"uses"| node_zep_memory
node_memory_driver -->|"delegates storage"| node_local_memory
node_memory_driver -->|"delegates storage"| node_milvus_memory
node_config -->|"configures"| node_memory_driver
node_config -->|"configures"| node_reflection
node_live_client -->|"uses client"| node_live_protocol
node_live_client -->|"registers handlers"| node_live_handlers
node_live_client -->|"queues insight"| node_insight_queue
node_insight_queue -->|"forwards messages"| node_stream_queue
node_stream_queue -->|"routes output"| node_ws_output
node_ws_output -.->|"streams updates"| node_vrm_viewer
node_tts -.->|"provides speech"| node_vrm_viewer
node_vrm_viewer -.->|"controls expressions"| node_expressions
node_user -.->|"interacts live"| node_live_client
node_user -.->|"speaks Chinese"| node_tts
node_user -.->|"uses long-term memory"| node_memory_driver
node_user -.->|"customizes role"| node_roles

click node_web "https://github.com/yakami129/virtualwife/blob/main/domain-chatvrm/src/pages/index.tsx"
click node_settings "https://github.com/yakami129/virtualwife/blob/main/domain-chatvrm/src/components/settings.tsx"
click node_chat_api "https://github.com/yakami129/virtualwife/blob/main/domain-chatvrm/src/pages/api/chat.ts"
click node_chat_service "https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/chat/chat_service.py"
click node_history "https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/chat/chat_history_queue.py"
click node_llm_driver "https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/llms/llm_model_strategy.py"
click node_llm_providers "https://github.com/yakami129/virtualwife/tree/main/domain-chatbot/apps/chatbot/llms"
click node_config "https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/config/sys_config.py"
click node_character "https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/character/character_generation.py"
click node_roles "https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/character/role_package_manage.py"
click node_reflection "https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/reflection/reflection.py"
click node_live_client "https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/insight/bilibili/bili_live_client.py"
click node_live_protocol "https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/insight/bilibili/sdk/client.py"
click node_live_handlers "https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/insight/bilibili/sdk/handlers.py"
click node_insight_queue "https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/insight/insight_message_queue.py"
click node_memory_driver "https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/memory/memory_storage.py"
click node_local_memory "https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/memory/local/local_storage_impl.py"
click node_milvus_memory "https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/memory/milvus/milvus_storage_impl.py"
click node_zep_memory "https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/memory/zep/zep_memory.py"
click node_stream_queue "https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/output/realtime_message_queue.py"
click node_ws_output "https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/output/consumers.py"
click node_tts "https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/speech/tts/tts_driver.py"
click node_vrm_viewer "https://github.com/yakami129/virtualwife/blob/main/domain-chatvrm/src/features/vrmViewer/viewer.ts"
click node_expressions "https://github.com/yakami129/virtualwife/blob/main/domain-chatvrm/src/features/emoteController/expressionController.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_web,node_settings,node_chat_api,node_user toneBlue
class node_chat_service,node_history,node_llm_driver,node_llm_providers toneAmber
class node_config,node_character,node_roles,node_reflection,node_live_client,node_live_protocol,node_live_handlers,node_insight_queue toneMint
class node_memory_driver,node_local_memory,node_milvus_memory,node_zep_memory toneRose
class node_stream_queue,node_ws_output,node_tts,node_vrm_viewer,node_expressions toneIndigo
```

## Components

### Web experience

- [Web interface](https://github.com/yakami129/virtualwife/blob/main/domain-chatvrm/src/pages/index.tsx): `domain-chatvrm/src/pages/index.tsx`
- [Character settings](https://github.com/yakami129/virtualwife/blob/main/domain-chatvrm/src/components/settings.tsx): `domain-chatvrm/src/components/settings.tsx`
- [Chat API](https://github.com/yakami129/virtualwife/blob/main/domain-chatvrm/src/pages/api/chat.ts): `domain-chatvrm/src/pages/api/chat.ts`

### Conversation runtime

- [Chat service](https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/chat/chat_service.py): `domain-chatbot/apps/chatbot/chat/chat_service.py`
- [Chat history](https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/chat/chat_history_queue.py): `domain-chatbot/apps/chatbot/chat/chat_history_queue.py`
- [LLM selection](https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/llms/llm_model_strategy.py): `domain-chatbot/apps/chatbot/llms/llm_model_strategy.py`
- [LLM providers](https://github.com/yakami129/virtualwife/tree/main/domain-chatbot/apps/chatbot/llms): `domain-chatbot/apps/chatbot/llms`

### Persona and insight

- [System configuration](https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/config/sys_config.py): `domain-chatbot/apps/chatbot/config/sys_config.py`
- [Character generation](https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/character/character_generation.py): `domain-chatbot/apps/chatbot/character/character_generation.py`
- [Custom roles](https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/character/role_package_manage.py): `domain-chatbot/apps/chatbot/character/role_package_manage.py`
- [Reflection](https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/reflection/reflection.py): `domain-chatbot/apps/chatbot/reflection/reflection.py`
- [Bilibili live client](https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/insight/bilibili/bili_live_client.py): `domain-chatbot/apps/chatbot/insight/bilibili/bili_live_client.py`
- [Live protocol SDK](https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/insight/bilibili/sdk/client.py): `domain-chatbot/apps/chatbot/insight/bilibili/sdk/client.py`
- [Live message handlers](https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/insight/bilibili/sdk/handlers.py): `domain-chatbot/apps/chatbot/insight/bilibili/sdk/handlers.py`
- [Insight queue](https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/insight/insight_message_queue.py): `domain-chatbot/apps/chatbot/insight/insight_message_queue.py`

### Memory

- [Memory driver](https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/memory/memory_storage.py): `domain-chatbot/apps/chatbot/memory/memory_storage.py`
- [Local memory](https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/memory/local/local_storage_impl.py): `domain-chatbot/apps/chatbot/memory/local/local_storage_impl.py`
- [Milvus memory](https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/memory/milvus/milvus_storage_impl.py): `domain-chatbot/apps/chatbot/memory/milvus/milvus_storage_impl.py`
- [Zep memory](https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/memory/zep/zep_memory.py): `domain-chatbot/apps/chatbot/memory/zep/zep_memory.py`

### Speech and avatar

- [Realtime output queue](https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/output/realtime_message_queue.py): `domain-chatbot/apps/chatbot/output/realtime_message_queue.py`
- [WebSocket output](https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/chatbot/output/consumers.py): `domain-chatbot/apps/chatbot/output/consumers.py`
- [Speech synthesis](https://github.com/yakami129/virtualwife/blob/main/domain-chatbot/apps/speech/tts/tts_driver.py): `domain-chatbot/apps/speech/tts/tts_driver.py`
- [VRM avatar viewer](https://github.com/yakami129/virtualwife/blob/main/domain-chatvrm/src/features/vrmViewer/viewer.ts): `domain-chatvrm/src/features/vrmViewer/viewer.ts`
- [Expression control](https://github.com/yakami129/virtualwife/blob/main/domain-chatvrm/src/features/emoteController/expressionController.ts): `domain-chatvrm/src/features/emoteController/expressionController.ts`

### Other components

- **User**

## Connections

- User → Web interface: uses (evidence: `README.md`)
- Web interface → Character settings: configures (evidence: `README.md`)
- Web interface → Chat API: requests chat
- Chat API → Chat service: submits chat
- Chat service → Character generation: loads character (evidence: `domain-chatbot/apps/chatbot/chat/chat_service.py`)
- Chat service → System configuration: reads config (evidence: `domain-chatbot/apps/chatbot/chat/chat_service.py`)
- Chat service → LLM selection: generates reply
- LLM selection → LLM providers: selects provider (evidence: `domain-chatbot/apps/chatbot/llms/llm_model_strategy.py`)
- LLM selection → Zep memory: uses memory types (evidence: `domain-chatbot/apps/chatbot/llms/llm_model_strategy.py`)
- Chat history → Zep memory: uses (evidence: `domain-chatbot/apps/chatbot/chat/chat_history_queue.py`)
- Memory driver → Local memory: delegates storage (evidence: `domain-chatbot/apps/chatbot/memory/memory_storage.py`)
- Memory driver → Milvus memory: delegates storage (evidence: `domain-chatbot/apps/chatbot/memory/memory_storage.py`)
- System configuration → Memory driver: configures (evidence: `domain-chatbot/apps/chatbot/config/sys_config.py`)
- System configuration → Reflection: configures (evidence: `domain-chatbot/apps/chatbot/config/sys_config.py`)
- Bilibili live client → Live protocol SDK: uses client (evidence: `domain-chatbot/apps/chatbot/insight/bilibili/bili_live_client.py`)
- Bilibili live client → Live message handlers: registers handlers (evidence: `domain-chatbot/apps/chatbot/insight/bilibili/bili_live_client.py`)
- Bilibili live client → Insight queue: queues insight (evidence: `domain-chatbot/apps/chatbot/insight/bilibili/bili_live_client.py`)
- Insight queue → Realtime output queue: forwards messages (evidence: `domain-chatbot/apps/chatbot/insight/insight_message_queue.py`)
- Realtime output queue → WebSocket output: routes output
- WebSocket output → VRM avatar viewer: streams updates
- Speech synthesis → VRM avatar viewer: provides speech
- VRM avatar viewer → Expression control: controls expressions
- User → Bilibili live client: interacts live (evidence: `README.md`)
- User → Speech synthesis: speaks Chinese (evidence: `README.md`)
- User → Memory driver: uses long-term memory (evidence: `README.md`)
- User → Custom roles: customizes role (evidence: `README.md`)
