# xargonwan/synthetic_heart architecture

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

- Interactive diagram: https://gitdiagram.com/xargonwan/synthetic_heart
- Repository: https://github.com/xargonwan/synthetic_heart

## Overview

Synthetic Heart is a modular, persistent AI-persona framework: people interact through chat interfaces or its WebUI, while the system routes turns through response generation and action handling. Its wider product includes switchable model engines, durable memory and personality, plugins for autonomous growth and integrations, and a VRM avatar experience. The graph combines README-documented capabilities with relationships supported by the supplied source index; unsampled subsystems are included where the README establishes their role, without asserting unverified internal calls.

Main entry points: [`interface`](https://github.com/xargonwan/synthetic_heart/tree/develop/interface) (Chat interfaces), [`core/auto_response.py`](https://github.com/xargonwan/synthetic_heart/blob/develop/core/auto_response.py) (Response orchestration), [`core/message_queue.py`](https://github.com/xargonwan/synthetic_heart/blob/develop/core/message_queue.py) (Message routing), [`core/core_initializer.py`](https://github.com/xargonwan/synthetic_heart/blob/develop/core/core_initializer.py) (Component discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and routing"]
  node_startup["Runtime startup<br/>[main.py]"]
  node_bootstrap["Component discovery"]
  node_queue["Message routing<br/>[message_queue.py]"]
end

subgraph group_cognition["Conversation and cognition"]
  node_response["Response orchestration<br/>[auto_response.py]"]
  node_prompt["Prompt assembly<br/>[prompt_engine.py]"]
  node_actions["Action parsing<br/>[action_parser.py]"]
end

subgraph group_identity["Persistent identity"]
  node_history["Memory recall<br/>[history_engine.py]"]
  node_chatcache[("Chat history cache")]
  node_persona["Persona state<br/>[persona_manager.py]"]
  node_database[("Persistent database<br/>[db.py]")]
  node_emotion["Emotion subsystem<br/>[emotion_manager.py]"]
end

subgraph group_extensions["Engines and plugins"]
  node_engines["Model engine registry<br/>[cortex_registry.py]"]
  node_model["Model engines"]
  node_endpoints["External endpoints<br/>[registry.py]"]
  node_plugins["Plugins and growth"]
  node_voice["Voice engines"]
  node_websearch["Web search<br/>[search_engine.py]"]
end

subgraph group_experience["Interfaces and avatar"]
  node_interface["Chat interfaces"]
  node_webui["WebUI<br/>[webui.py]"]
  node_avatar["VRM avatar"]
end

node_person(("Person"))
node_external["Model provider"]

node_person -->|"starts conversation"| node_interface
node_interface -.->|"submits turns"| node_queue
node_person -->|"configures Synth"| node_webui
node_startup -->|"initializes components"| node_bootstrap
node_startup -->|"starts processing"| node_queue
node_bootstrap -->|"discovers interfaces"| node_interface
node_bootstrap -->|"discovers plugins"| node_plugins
node_queue -.->|"dispatches turns"| node_response
node_response -->|"requests prompt"| node_prompt
node_response -->|"parses actions"| node_actions
node_response -->|"enqueues messages"| node_queue
node_prompt -->|"recalls context"| node_history
node_history -->|"reads history"| node_chatcache
node_prompt -.->|"selects engine"| node_engines
node_engines -->|"loads engine"| node_model
node_endpoints -.->|"connects providers"| node_external
node_persona -.->|"persists state"| node_database
node_plugins -.->|"stores memories"| node_database
node_emotion -.->|"shapes behavior"| node_persona
node_voice -.->|"enables voice"| node_interface
node_interface -.->|"presents avatar"| node_avatar
node_plugins -.->|"offers search"| node_websearch

click node_startup "https://github.com/xargonwan/synthetic_heart/blob/develop/main.py"
click node_bootstrap "https://github.com/xargonwan/synthetic_heart/blob/develop/core/core_initializer.py"
click node_queue "https://github.com/xargonwan/synthetic_heart/blob/develop/core/message_queue.py"
click node_interface "https://github.com/xargonwan/synthetic_heart/tree/develop/interface"
click node_webui "https://github.com/xargonwan/synthetic_heart/blob/develop/core/webui.py"
click node_response "https://github.com/xargonwan/synthetic_heart/blob/develop/core/auto_response.py"
click node_prompt "https://github.com/xargonwan/synthetic_heart/blob/develop/core/prompt_engine.py"
click node_history "https://github.com/xargonwan/synthetic_heart/blob/develop/core/history_engine.py"
click node_chatcache "https://github.com/xargonwan/synthetic_heart/blob/develop/core/chat_history_cache.py"
click node_actions "https://github.com/xargonwan/synthetic_heart/blob/develop/core/action_parser.py"
click node_engines "https://github.com/xargonwan/synthetic_heart/blob/develop/core/cortex_registry.py"
click node_model "https://github.com/xargonwan/synthetic_heart/tree/develop/engines/external_engines"
click node_endpoints "https://github.com/xargonwan/synthetic_heart/blob/develop/core/external_endpoints/registry.py"
click node_persona "https://github.com/xargonwan/synthetic_heart/blob/develop/core/persona_manager.py"
click node_database "https://github.com/xargonwan/synthetic_heart/blob/develop/core/db.py"
click node_plugins "https://github.com/xargonwan/synthetic_heart/tree/develop/plugins"
click node_emotion "https://github.com/xargonwan/synthetic_heart/blob/develop/plugins/emotion_manager/emotion_manager.py"
click node_voice "https://github.com/xargonwan/synthetic_heart/tree/develop/plugins/auris_engines"
click node_avatar "https://github.com/xargonwan/synthetic_heart/tree/develop/frontend/src/composables/vrm"
click node_websearch "https://github.com/xargonwan/synthetic_heart/blob/develop/plugins/web_search/search_engine.py"

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_startup,node_bootstrap,node_queue toneBlue
class node_response,node_prompt,node_actions toneAmber
class node_history,node_chatcache,node_persona,node_database,node_emotion toneMint
class node_engines,node_model,node_endpoints,node_plugins,node_voice,node_websearch toneRose
class node_interface,node_webui,node_avatar,node_person,node_external toneIndigo
```

## Components

### Runtime and routing

- [Runtime startup](https://github.com/xargonwan/synthetic_heart/blob/develop/main.py): `main.py`
- [Component discovery](https://github.com/xargonwan/synthetic_heart/blob/develop/core/core_initializer.py): `core/core_initializer.py`
- [Message routing](https://github.com/xargonwan/synthetic_heart/blob/develop/core/message_queue.py): `core/message_queue.py`

### Conversation and cognition

- [Response orchestration](https://github.com/xargonwan/synthetic_heart/blob/develop/core/auto_response.py): `core/auto_response.py`
- [Prompt assembly](https://github.com/xargonwan/synthetic_heart/blob/develop/core/prompt_engine.py): `core/prompt_engine.py`
- [Action parsing](https://github.com/xargonwan/synthetic_heart/blob/develop/core/action_parser.py): `core/action_parser.py`

### Persistent identity

- [Memory recall](https://github.com/xargonwan/synthetic_heart/blob/develop/core/history_engine.py): `core/history_engine.py`
- [Chat history cache](https://github.com/xargonwan/synthetic_heart/blob/develop/core/chat_history_cache.py): `core/chat_history_cache.py`
- [Persona state](https://github.com/xargonwan/synthetic_heart/blob/develop/core/persona_manager.py): `core/persona_manager.py`
- [Persistent database](https://github.com/xargonwan/synthetic_heart/blob/develop/core/db.py): `core/db.py`
- [Emotion subsystem](https://github.com/xargonwan/synthetic_heart/blob/develop/plugins/emotion_manager/emotion_manager.py): `plugins/emotion_manager/emotion_manager.py`

### Engines and plugins

- [Model engine registry](https://github.com/xargonwan/synthetic_heart/blob/develop/core/cortex_registry.py): `core/cortex_registry.py`
- [Model engines](https://github.com/xargonwan/synthetic_heart/tree/develop/engines/external_engines): `engines/external_engines`
- [External endpoints](https://github.com/xargonwan/synthetic_heart/blob/develop/core/external_endpoints/registry.py): `core/external_endpoints/registry.py`
- [Plugins and growth](https://github.com/xargonwan/synthetic_heart/tree/develop/plugins): `plugins`
- [Voice engines](https://github.com/xargonwan/synthetic_heart/tree/develop/plugins/auris_engines): `plugins/auris_engines`
- [Web search](https://github.com/xargonwan/synthetic_heart/blob/develop/plugins/web_search/search_engine.py): `plugins/web_search/search_engine.py`

### Interfaces and avatar

- [Chat interfaces](https://github.com/xargonwan/synthetic_heart/tree/develop/interface): `interface`
- [WebUI](https://github.com/xargonwan/synthetic_heart/blob/develop/core/webui.py): `core/webui.py`
- [VRM avatar](https://github.com/xargonwan/synthetic_heart/tree/develop/frontend/src/composables/vrm): `frontend/src/composables/vrm`

### Other components

- **Person**
- **Model provider**

## Connections

- Person → Chat interfaces: starts conversation (evidence: `README.md`)
- Chat interfaces → Message routing: submits turns
- Person → WebUI: configures Synth (evidence: `README.md`)
- Runtime startup → Component discovery: initializes components (evidence: `main.py`)
- Runtime startup → Message routing: starts processing (evidence: `main.py`)
- Component discovery → Chat interfaces: discovers interfaces (evidence: `core/core_initializer.py`)
- Component discovery → Plugins and growth: discovers plugins (evidence: `core/core_initializer.py`)
- Message routing → Response orchestration: dispatches turns (evidence: `core/auto_response.py`)
- Response orchestration → Prompt assembly: requests prompt (evidence: `core/auto_response.py`)
- Response orchestration → Action parsing: parses actions (evidence: `core/auto_response.py`)
- Response orchestration → Message routing: enqueues messages (evidence: `core/auto_response.py`)
- Prompt assembly → Memory recall: recalls context (evidence: `core/prompt_engine.py`)
- Memory recall → Chat history cache: reads history (evidence: `core/history_engine.py`)
- Prompt assembly → Model engine registry: selects engine (evidence: `core/prompt_engine.py`)
- Model engine registry → Model engines: loads engine (evidence: `core/cortex_registry.py`)
- External endpoints → Model provider: connects providers
- Persona state → Persistent database: persists state
- Plugins and growth → Persistent database: stores memories (evidence: `plugins/bio_manager/bio_manager.py`)
- Emotion subsystem → Persona state: shapes behavior
- Voice engines → Chat interfaces: enables voice
- Chat interfaces → VRM avatar: presents avatar
- Plugins and growth → Web search: offers search (evidence: `plugins/rift_vessel/knowledge_client.py`)
