# zeikar/charivo architecture

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

- Interactive diagram: https://gitdiagram.com/zeikar/charivo
- Repository: https://github.com/zeikar/charivo

## Overview

Charivo is a modular TypeScript framework for interactive AI characters. Its principal text workflow accepts a user message through core orchestration, obtains an LLM response (optionally invoking avatar tools), speaks the reply through TTS, and updates a renderer. A parallel realtime workflow streams microphone audio to a realtime provider and returns audio and events to the character. Provider packages offer browser-direct and server-mediated integrations; the README documents these modes, while sampled source confirms selected manager and client dependencies. Unsampled modules are represented at their exact package directories where their capabilities are evident from the README and tree.

Main entry points: [`packages/core/src/index.ts`](https://github.com/zeikar/charivo/blob/main/packages/core/src/index.ts) (Charivo Core), [`packages/llm/src/llm-manager.ts`](https://github.com/zeikar/charivo/blob/main/packages/llm/src/llm-manager.ts) (LLM Manager), [`packages/realtime/src/realtime-manager.ts`](https://github.com/zeikar/charivo/blob/main/packages/realtime/src/realtime-manager.ts) (Realtime Manager), [`packages/render/src/render-manager.ts`](https://github.com/zeikar/charivo/blob/main/packages/render/src/render-manager.ts) (Render Manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Character Orchestration"]
  node_core["Charivo Core<br/>[index.ts]"]
  node_events["Events and State<br/>[bus.ts]"]
end

subgraph group_conversation["Conversation and Tools"]
  node_avatar_tools["Avatar Tools<br/>[index.ts]"]
  node_llm_manager["LLM Manager<br/>[llm-manager.ts]"]
  node_llm_clients["LLM Clients"]
  node_history["Message History"]
end

subgraph group_voice["Voice and Realtime"]
  node_stt_manager["STT Manager<br/>[stt-manager.ts]"]
  node_stt_clients["STT Providers"]
  node_tts_manager["TTS Manager<br/>[tts-manager.ts]"]
  node_tts_clients["TTS Providers"]
  node_realtime_manager["Realtime Manager"]
  node_realtime_instructions["Session Instructions<br/>[instructions.ts]"]
  node_realtime_clients["Realtime Clients"]
end

subgraph group_rendering["Avatar Rendering"]
  node_render_manager["Render Manager<br/>[render-manager.ts]"]
  node_live2d_renderer["Live2D Renderer<br/>[live2d-renderer.ts]"]
  node_iki_renderer["Iki Renderer<br/>[renderer.ts]"]
  node_cubism_model["Cubism Model<br/>[cubismmodel.ts]"]
end

subgraph group_providers["Provider Integrations"]
  node_server_routes["Server Routes"]
  node_provider_services["Provider Services"]
end

node_app(("Application"))

node_app -->|"configures"| node_core
node_app -->|"initializes"| node_render_manager
node_render_manager -->|"wraps"| node_live2d_renderer
node_render_manager -.-> node_iki_renderer
node_live2d_renderer -.-> node_cubism_model
node_app -->|"configures"| node_llm_manager
node_llm_manager -->|"calls"| node_llm_clients
node_llm_manager -->|"manages"| node_history
node_app -->|"registers"| node_avatar_tools
node_llm_manager -->|"invokes"| node_avatar_tools
node_app -->|"sends message"| node_core
node_core -->|"requests reply"| node_llm_manager
node_core -->|"speaks reply"| node_tts_manager
node_tts_manager -->|"plays audio"| node_tts_clients
node_core -->|"updates character"| node_render_manager
node_core -.-> node_events
node_app -->|"configures"| node_realtime_manager
node_app -->|"starts session"| node_realtime_manager
node_realtime_manager -->|"builds session"| node_realtime_instructions
node_realtime_manager -->|"dispatches session"| node_realtime_clients
node_realtime_manager -.->|"streams audio"| node_provider_services
node_app -.-> node_stt_manager
node_stt_manager -.-> node_stt_clients
node_app -->|"uses production routes"| node_server_routes
node_server_routes -->|"mediates requests"| node_provider_services

click node_core "https://github.com/zeikar/charivo/blob/main/packages/core/src/index.ts"
click node_events "https://github.com/zeikar/charivo/blob/main/packages/core/src/bus.ts"
click node_avatar_tools "https://github.com/zeikar/charivo/blob/main/packages/avatar/src/index.ts"
click node_llm_manager "https://github.com/zeikar/charivo/blob/main/packages/llm/src/llm-manager.ts"
click node_llm_clients "https://github.com/zeikar/charivo/tree/main/packages/llm/src"
click node_history "https://github.com/zeikar/charivo/blob/main/packages/llm/src/message-history-manager.ts"
click node_stt_manager "https://github.com/zeikar/charivo/blob/main/packages/stt/src/stt-manager.ts"
click node_stt_clients "https://github.com/zeikar/charivo/tree/main/packages/stt/src"
click node_tts_manager "https://github.com/zeikar/charivo/blob/main/packages/tts/src/tts-manager.ts"
click node_tts_clients "https://github.com/zeikar/charivo/tree/main/packages/tts/src"
click node_realtime_manager "https://github.com/zeikar/charivo/blob/main/packages/realtime/src/realtime-manager.ts"
click node_realtime_instructions "https://github.com/zeikar/charivo/blob/main/packages/realtime/src/instructions.ts"
click node_realtime_clients "https://github.com/zeikar/charivo/tree/main/packages/realtime/src"
click node_render_manager "https://github.com/zeikar/charivo/blob/main/packages/render/src/render-manager.ts"
click node_live2d_renderer "https://github.com/zeikar/charivo/blob/main/packages/render-live2d/src/live2d-renderer.ts"
click node_iki_renderer "https://github.com/zeikar/charivo/blob/main/packages/render-iki/src/renderer.ts"
click node_cubism_model "https://github.com/zeikar/charivo/blob/main/packages/render-live2d/CubismSdkForWeb-5-r.4/Framework/src/model/cubismmodel.ts"
click node_server_routes "https://github.com/zeikar/charivo/tree/main/packages/server/src"

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_core,node_events toneBlue
class node_avatar_tools,node_llm_manager,node_llm_clients,node_history toneAmber
class node_stt_manager,node_stt_clients,node_tts_manager,node_tts_clients,node_realtime_manager,node_realtime_instructions,node_realtime_clients toneMint
class node_render_manager,node_live2d_renderer,node_iki_renderer,node_cubism_model toneRose
class node_server_routes,node_provider_services,node_app toneIndigo
```

## Components

### Character Orchestration

- [Charivo Core](https://github.com/zeikar/charivo/blob/main/packages/core/src/index.ts): `packages/core/src/index.ts`
- [Events and State](https://github.com/zeikar/charivo/blob/main/packages/core/src/bus.ts): `packages/core/src/bus.ts`

### Conversation and Tools

- [Avatar Tools](https://github.com/zeikar/charivo/blob/main/packages/avatar/src/index.ts): `packages/avatar/src/index.ts`
- [LLM Manager](https://github.com/zeikar/charivo/blob/main/packages/llm/src/llm-manager.ts): `packages/llm/src/llm-manager.ts`
- [LLM Clients](https://github.com/zeikar/charivo/tree/main/packages/llm/src): `packages/llm/src`
- [Message History](https://github.com/zeikar/charivo/blob/main/packages/llm/src/message-history-manager.ts): `packages/llm/src/message-history-manager.ts`

### Voice and Realtime

- [STT Manager](https://github.com/zeikar/charivo/blob/main/packages/stt/src/stt-manager.ts): `packages/stt/src/stt-manager.ts`
- [STT Providers](https://github.com/zeikar/charivo/tree/main/packages/stt/src): `packages/stt/src`
- [TTS Manager](https://github.com/zeikar/charivo/blob/main/packages/tts/src/tts-manager.ts): `packages/tts/src/tts-manager.ts`
- [TTS Providers](https://github.com/zeikar/charivo/tree/main/packages/tts/src): `packages/tts/src`
- [Realtime Manager](https://github.com/zeikar/charivo/blob/main/packages/realtime/src/realtime-manager.ts): `packages/realtime/src/realtime-manager.ts`
- [Session Instructions](https://github.com/zeikar/charivo/blob/main/packages/realtime/src/instructions.ts): `packages/realtime/src/instructions.ts`
- [Realtime Clients](https://github.com/zeikar/charivo/tree/main/packages/realtime/src): `packages/realtime/src`

### Avatar Rendering

- [Render Manager](https://github.com/zeikar/charivo/blob/main/packages/render/src/render-manager.ts): `packages/render/src/render-manager.ts`
- [Live2D Renderer](https://github.com/zeikar/charivo/blob/main/packages/render-live2d/src/live2d-renderer.ts): `packages/render-live2d/src/live2d-renderer.ts`
- [Iki Renderer](https://github.com/zeikar/charivo/blob/main/packages/render-iki/src/renderer.ts): `packages/render-iki/src/renderer.ts`
- [Cubism Model](https://github.com/zeikar/charivo/blob/main/packages/render-live2d/CubismSdkForWeb-5-r.4/Framework/src/model/cubismmodel.ts): `packages/render-live2d/CubismSdkForWeb-5-r.4/Framework/src/model/cubismmodel.ts`

### Provider Integrations

- [Server Routes](https://github.com/zeikar/charivo/tree/main/packages/server/src): `packages/server/src`
- **Provider Services**

### Other components

- **Application**

## Connections

- Application → Charivo Core: configures (evidence: `README.md`)
- Application → Render Manager: initializes (evidence: `README.md`)
- Render Manager → Live2D Renderer: wraps (evidence: `README.md`)
- Render Manager → Iki Renderer
- Live2D Renderer → Cubism Model
- Application → LLM Manager: configures (evidence: `README.md`)
- LLM Manager → LLM Clients: calls (evidence: `README.md`)
- LLM Manager → Message History: manages (evidence: `packages/llm/src/llm-manager.ts`)
- Application → Avatar Tools: registers (evidence: `README.md`)
- LLM Manager → Avatar Tools: invokes (evidence: `README.md`)
- Application → Charivo Core: sends message (evidence: `README.md`)
- Charivo Core → LLM Manager: requests reply (evidence: `README.md`)
- Charivo Core → TTS Manager: speaks reply (evidence: `README.md`)
- TTS Manager → TTS Providers: plays audio (evidence: `packages/tts/src/tts-manager.ts`)
- Charivo Core → Render Manager: updates character (evidence: `README.md`)
- Charivo Core → Events and State (evidence: `packages/core/src/index.ts`)
- Application → Realtime Manager: configures (evidence: `README.md`)
- Application → Realtime Manager: starts session (evidence: `README.md`)
- Realtime Manager → Session Instructions: builds session (evidence: `packages/realtime/src/realtime-manager.ts`)
- Realtime Manager → Realtime Clients: dispatches session (evidence: `packages/realtime/src/realtime-manager.ts`)
- Realtime Manager → Provider Services: streams audio
- Application → STT Manager
- STT Manager → STT Providers
- Application → Server Routes: uses production routes (evidence: `README.md`)
- Server Routes → Provider Services: mediates requests (evidence: `README.md`)
