# scarlet-raine/synthetic_heart architecture

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

## Overview

Synthetic Heart is a modular, persistent AI-persona application spanning chat interfaces, a WebUI, plugins, and interchangeable model engines. The principal workflow is a human message entering through an interface, being queued and prepared with persona, context, and memory, then handled by an engine and returned through the interface. Separate branches cover persistent identity and growth, speech/avatar presentation, and integrations. The README documents these capabilities, while sampled source evidence is incomplete; edges not directly supported by excerpts or documentation are omitted.

Main entry points: [`core/prompt_engine.py`](https://github.com/scarlet-raine/synthetic_heart/blob/develop/core/prompt_engine.py) (Prompt construction), [`frontend/src/App.vue`](https://github.com/scarlet-raine/synthetic_heart/blob/develop/frontend/src/App.vue) (WebUI client), [`core/db.py`](https://github.com/scarlet-raine/synthetic_heart/blob/develop/core/db.py) (Persistent database), [`core/core_initializer.py`](https://github.com/scarlet-raine/synthetic_heart/blob/develop/core/core_initializer.py) (Component discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime orchestration"]
  node_startup["Application startup<br/>[main.py]"]
  node_initializer["Component discovery"]
  node_queue["Message queue<br/>[message_queue.py]"]
  node_engine_registry["Engine registry<br/>[cortex_registry.py]"]
  node_config[("Configuration registry<br/>[config_manager.py]")]
end

subgraph group_conversation["Conversation and cognition"]
  node_prompt["Prompt construction<br/>[prompt_engine.py]"]
  node_history["Context and recall<br/>[history_engine.py]"]
  node_actions["Action parsing<br/>[action_parser.py]"]
  node_engines["Model engines"]
end

subgraph group_identity["Persistent persona"]
  node_database[("Persistent database<br/>[db.py]")]
  node_persona["Persona state<br/>[persona_manager.py]"]
  node_soul["Emotional identity"]
  node_growth["Reflection and growth"]
end

subgraph group_connectors["Interfaces and integrations"]
  node_interfaces["Chat interfaces"]
  node_webui["WebUI client<br/>[App.vue]"]
  node_plugins["Plugin capabilities"]
  node_web_search["Web search<br/>[search_engine.py]"]
end

subgraph group_presentation["Voice and avatar"]
  node_speech["Speech engines<br/>[vosk_engine.py]"]
  node_avatar["Avatar presentation"]
end

node_human(("Human user"))

node_human -->|"sends message"| node_interfaces
node_human -->|"uses"| node_webui
node_startup -->|"initializes"| node_initializer
node_interfaces -->|"enqueues messages"| node_queue
node_webui -.->|"submits chat"| node_queue
node_queue -.->|"starts response"| node_prompt
node_prompt -->|"recalls context"| node_history
node_prompt -.->|"requests generation"| node_engines
node_engine_registry -->|"loads engines"| node_engines
node_prompt -->|"scopes actions"| node_actions
node_history -->|"reads memory"| node_database
node_persona -->|"persists identity"| node_database
node_soul -.->|"stores emotional state"| node_database
node_growth -.->|"develops memories"| node_database
node_initializer -->|"discovers components"| node_plugins
node_initializer -->|"registers engines"| node_engine_registry
node_plugins -.->|"offers search"| node_web_search
node_engines -.->|"supports speech"| node_speech
node_webui -.->|"presents avatar"| node_avatar
node_interfaces -->|"returns replies"| node_human
node_webui -.->|"shows responses"| node_human

click node_startup "https://github.com/scarlet-raine/synthetic_heart/blob/develop/main.py"
click node_initializer "https://github.com/scarlet-raine/synthetic_heart/blob/develop/core/core_initializer.py"
click node_queue "https://github.com/scarlet-raine/synthetic_heart/blob/develop/core/message_queue.py"
click node_interfaces "https://github.com/scarlet-raine/synthetic_heart/tree/develop/interface"
click node_webui "https://github.com/scarlet-raine/synthetic_heart/blob/develop/frontend/src/App.vue"
click node_prompt "https://github.com/scarlet-raine/synthetic_heart/blob/develop/core/prompt_engine.py"
click node_history "https://github.com/scarlet-raine/synthetic_heart/blob/develop/core/history_engine.py"
click node_actions "https://github.com/scarlet-raine/synthetic_heart/blob/develop/core/action_parser.py"
click node_engines "https://github.com/scarlet-raine/synthetic_heart/tree/develop/engines/external_engines"
click node_engine_registry "https://github.com/scarlet-raine/synthetic_heart/blob/develop/core/cortex_registry.py"
click node_database "https://github.com/scarlet-raine/synthetic_heart/blob/develop/core/db.py"
click node_config "https://github.com/scarlet-raine/synthetic_heart/blob/develop/core/config_manager.py"
click node_persona "https://github.com/scarlet-raine/synthetic_heart/blob/develop/core/persona_manager.py"
click node_soul "https://github.com/scarlet-raine/synthetic_heart/tree/develop/core/soul"
click node_growth "https://github.com/scarlet-raine/synthetic_heart/tree/develop/plugins/grillo"
click node_plugins "https://github.com/scarlet-raine/synthetic_heart/tree/develop/plugins"
click node_web_search "https://github.com/scarlet-raine/synthetic_heart/blob/develop/plugins/web_search/search_engine.py"
click node_speech "https://github.com/scarlet-raine/synthetic_heart/blob/develop/plugins/auris_engines/vosk_engine.py"
click node_avatar "https://github.com/scarlet-raine/synthetic_heart/tree/develop/frontend/src/composables/vrm"

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_initializer,node_queue,node_engine_registry,node_config,node_human toneBlue
class node_prompt,node_history,node_actions,node_engines toneAmber
class node_database,node_persona,node_soul,node_growth toneMint
class node_interfaces,node_webui,node_plugins,node_web_search toneRose
class node_speech,node_avatar toneIndigo
```

## Components

### Runtime orchestration

- [Application startup](https://github.com/scarlet-raine/synthetic_heart/blob/develop/main.py): `main.py`
- [Component discovery](https://github.com/scarlet-raine/synthetic_heart/blob/develop/core/core_initializer.py): `core/core_initializer.py`
- [Message queue](https://github.com/scarlet-raine/synthetic_heart/blob/develop/core/message_queue.py): `core/message_queue.py`
- [Engine registry](https://github.com/scarlet-raine/synthetic_heart/blob/develop/core/cortex_registry.py): `core/cortex_registry.py`
- [Configuration registry](https://github.com/scarlet-raine/synthetic_heart/blob/develop/core/config_manager.py): `core/config_manager.py`

### Conversation and cognition

- [Prompt construction](https://github.com/scarlet-raine/synthetic_heart/blob/develop/core/prompt_engine.py): `core/prompt_engine.py`
- [Context and recall](https://github.com/scarlet-raine/synthetic_heart/blob/develop/core/history_engine.py): `core/history_engine.py`
- [Action parsing](https://github.com/scarlet-raine/synthetic_heart/blob/develop/core/action_parser.py): `core/action_parser.py`
- [Model engines](https://github.com/scarlet-raine/synthetic_heart/tree/develop/engines/external_engines): `engines/external_engines`

### Persistent persona

- [Persistent database](https://github.com/scarlet-raine/synthetic_heart/blob/develop/core/db.py): `core/db.py`
- [Persona state](https://github.com/scarlet-raine/synthetic_heart/blob/develop/core/persona_manager.py): `core/persona_manager.py`
- [Emotional identity](https://github.com/scarlet-raine/synthetic_heart/tree/develop/core/soul): `core/soul`
- [Reflection and growth](https://github.com/scarlet-raine/synthetic_heart/tree/develop/plugins/grillo): `plugins/grillo`

### Interfaces and integrations

- [Chat interfaces](https://github.com/scarlet-raine/synthetic_heart/tree/develop/interface): `interface`
- [WebUI client](https://github.com/scarlet-raine/synthetic_heart/blob/develop/frontend/src/App.vue): `frontend/src/App.vue`
- [Plugin capabilities](https://github.com/scarlet-raine/synthetic_heart/tree/develop/plugins): `plugins`
- [Web search](https://github.com/scarlet-raine/synthetic_heart/blob/develop/plugins/web_search/search_engine.py): `plugins/web_search/search_engine.py`

### Voice and avatar

- [Speech engines](https://github.com/scarlet-raine/synthetic_heart/blob/develop/plugins/auris_engines/vosk_engine.py): `plugins/auris_engines/vosk_engine.py`
- [Avatar presentation](https://github.com/scarlet-raine/synthetic_heart/tree/develop/frontend/src/composables/vrm): `frontend/src/composables/vrm`

### Other components

- **Human user**

## Connections

- Human user → Chat interfaces: sends message
- Human user → WebUI client: uses
- Application startup → Component discovery: initializes (evidence: `main.py`)
- Chat interfaces → Message queue: enqueues messages (evidence: `core/message_queue.py`)
- WebUI client → Message queue: submits chat
- Message queue → Prompt construction: starts response
- Prompt construction → Context and recall: recalls context (evidence: `core/prompt_engine.py`)
- Prompt construction → Model engines: requests generation
- Engine registry → Model engines: loads engines (evidence: `core/cortex_registry.py`)
- Prompt construction → Action parsing: scopes actions (evidence: `core/prompt_engine.py`)
- Context and recall → Persistent database: reads memory (evidence: `core/history_engine.py`)
- Persona state → Persistent database: persists identity
- Emotional identity → Persistent database: stores emotional state
- Reflection and growth → Persistent database: develops memories (evidence: `plugins/grillo/grillo_weekly_review/grillo_weekly_review.py`)
- Component discovery → Plugin capabilities: discovers components (evidence: `core/core_initializer.py`)
- Component discovery → Engine registry: registers engines (evidence: `core/core_initializer.py`)
- Plugin capabilities → Web search: offers search (evidence: `plugins/rift_vessel/knowledge_client.py`)
- Model engines → Speech engines: supports speech
- WebUI client → Avatar presentation: presents avatar
- Chat interfaces → Human user: returns replies
- WebUI client → Human user: shows responses
