# xikhar/persona architecture

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

- Interactive diagram: https://gitdiagram.com/xikhar/persona
- Repository: https://github.com/xikhar/persona

## Overview

Persona is a desktop character companion for voice conversations. A user configures a model, animation library, and audio source; the Electron process manages the overlay and listens to the selected playback source, while the renderer animates the character in response. Settings, MCP controls, and optional VRoid Hub integration are distinct supporting workflows. Edges are limited to README statements and relationships visible in the supplied excerpts or SOURCE INDEX; several implementation details were not sampled.

Main entry points: [`electron/main.cts`](https://github.com/xikhar/persona/blob/main/electron/main.cts) (Electron coordinator), [`src/App.tsx`](https://github.com/xikhar/persona/blob/main/src/App.tsx) (Renderer app state), [`src/components/Avatar.tsx`](https://github.com/xikhar/persona/blob/main/src/components/Avatar.tsx) (Avatar rig and motion), [`src/animation-scheduler.ts`](https://github.com/xikhar/persona/blob/main/src/animation-scheduler.ts) (Animation scheduler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop runtime"]
  node_electron["Electron coordinator<br/>[main.cts]"]
  node_window["Overlay window controls<br/>[click-through.cts]"]
end

subgraph group_character["Character renderer"]
  node_renderer["Renderer app state<br/>[App.tsx]"]
  node_scene["3D scene and camera<br/>[Scene.tsx]"]
  node_avatar["Avatar rig and motion<br/>[Avatar.tsx]"]
  node_animcatalog["Animation catalog"]
  node_scheduler["Animation scheduler"]
  node_drag["Drag secondary motion<br/>[drag-inertia.ts]"]
end

subgraph group_configuration["Settings and library"]
  node_settingsui["Settings interface<br/>[SettingsPage.tsx]"]
  node_settingsstore[("Settings persistence<br/>[settings-store.cts]")]
  node_library["Packaged library catalog"]
  node_generator["Animation generation"]
end

subgraph group_integrations["Voice and integrations"]
  node_voice["Voice output listener<br/>[audio-listener.cts]"]
  node_discovery["Voice source discovery"]
  node_voiceexternal(("Playback process or stream"))
  node_mcp["MCP control server<br/>[mcp-server.cts]"]
  node_mcpclient(("MCP client"))
  node_vroidauth["VRoid Hub authentication<br/>[vroid-hub-auth.cts]"]
  node_vroidclient["VRoid Hub client"]
  node_vroidhub(("VRoid Hub service"))
end

node_user(("Desktop user"))

node_user -->|"configures"| node_settingsui
node_settingsui -.->|"saves settings"| node_settingsstore
node_electron -->|"loads settings"| node_settingsstore
node_settingsstore -->|"uses catalog"| node_library
node_electron -->|"starts listener"| node_voice
node_electron -->|"discovers sources"| node_discovery
node_voiceexternal -.->|"provides playback"| node_voice
node_voice -.->|"sends voice state"| node_renderer
node_electron -->|"launches window"| node_renderer
node_user -->|"toggles overlay"| node_window
node_renderer -->|"renders scene"| node_scene
node_scene -->|"renders avatar"| node_avatar
node_avatar -->|"updates animation"| node_scheduler
node_scheduler -->|"selects clips"| node_animcatalog
node_renderer -->|"queues drag motion"| node_drag
node_avatar -->|"applies body lag"| node_drag
node_user -->|"requests controls"| node_mcpclient
node_mcpclient -->|"sends MCP requests"| node_mcp
node_electron -->|"starts server"| node_mcp
node_user -->|"connects account"| node_vroidauth
node_electron -->|"configures auth"| node_vroidauth
node_vroidauth -->|"provides tokens"| node_vroidclient
node_vroidclient -->|"fetches characters"| node_vroidhub
node_generator -->|"uses catalog"| node_library
node_library -.->|"supplies animation media"| node_scheduler

click node_electron "https://github.com/xikhar/persona/blob/main/electron/main.cts"
click node_window "https://github.com/xikhar/persona/blob/main/electron/click-through.cts"
click node_renderer "https://github.com/xikhar/persona/blob/main/src/App.tsx"
click node_scene "https://github.com/xikhar/persona/blob/main/src/components/Scene.tsx"
click node_avatar "https://github.com/xikhar/persona/blob/main/src/components/Avatar.tsx"
click node_animcatalog "https://github.com/xikhar/persona/blob/main/src/animation-catalog.ts"
click node_scheduler "https://github.com/xikhar/persona/blob/main/src/animation-scheduler.ts"
click node_drag "https://github.com/xikhar/persona/blob/main/src/drag-inertia.ts"
click node_settingsui "https://github.com/xikhar/persona/blob/main/src/components/SettingsPage.tsx"
click node_settingsstore "https://github.com/xikhar/persona/blob/main/electron/settings-store.cts"
click node_library "https://github.com/xikhar/persona/blob/main/electron/library-catalog.cts"
click node_generator "https://github.com/xikhar/persona/blob/main/electron/animation-generator.cts"
click node_voice "https://github.com/xikhar/persona/blob/main/electron/audio-listener.cts"
click node_discovery "https://github.com/xikhar/persona/blob/main/electron/voice-source-discovery.cts"
click node_mcp "https://github.com/xikhar/persona/blob/main/electron/mcp-server.cts"
click node_vroidauth "https://github.com/xikhar/persona/blob/main/electron/vroid-hub-auth.cts"
click node_vroidclient "https://github.com/xikhar/persona/blob/main/electron/vroid-hub-client.cts"

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_electron,node_window,node_user toneBlue
class node_renderer,node_scene,node_avatar,node_animcatalog,node_scheduler,node_drag toneAmber
class node_settingsui,node_settingsstore,node_library,node_generator toneMint
class node_voice,node_discovery,node_voiceexternal,node_mcp,node_mcpclient,node_vroidauth,node_vroidclient,node_vroidhub toneRose
```

## Components

### Desktop runtime

- [Electron coordinator](https://github.com/xikhar/persona/blob/main/electron/main.cts): `electron/main.cts`
- [Overlay window controls](https://github.com/xikhar/persona/blob/main/electron/click-through.cts): `electron/click-through.cts`

### Character renderer

- [Renderer app state](https://github.com/xikhar/persona/blob/main/src/App.tsx): `src/App.tsx`
- [3D scene and camera](https://github.com/xikhar/persona/blob/main/src/components/Scene.tsx): `src/components/Scene.tsx`
- [Avatar rig and motion](https://github.com/xikhar/persona/blob/main/src/components/Avatar.tsx): `src/components/Avatar.tsx`
- [Animation catalog](https://github.com/xikhar/persona/blob/main/src/animation-catalog.ts): `src/animation-catalog.ts`
- [Animation scheduler](https://github.com/xikhar/persona/blob/main/src/animation-scheduler.ts): `src/animation-scheduler.ts`
- [Drag secondary motion](https://github.com/xikhar/persona/blob/main/src/drag-inertia.ts): `src/drag-inertia.ts`

### Settings and library

- [Settings interface](https://github.com/xikhar/persona/blob/main/src/components/SettingsPage.tsx): `src/components/SettingsPage.tsx`
- [Settings persistence](https://github.com/xikhar/persona/blob/main/electron/settings-store.cts): `electron/settings-store.cts`
- [Packaged library catalog](https://github.com/xikhar/persona/blob/main/electron/library-catalog.cts): `electron/library-catalog.cts`
- [Animation generation](https://github.com/xikhar/persona/blob/main/electron/animation-generator.cts): `electron/animation-generator.cts`

### Voice and integrations

- [Voice output listener](https://github.com/xikhar/persona/blob/main/electron/audio-listener.cts): `electron/audio-listener.cts`
- [Voice source discovery](https://github.com/xikhar/persona/blob/main/electron/voice-source-discovery.cts): `electron/voice-source-discovery.cts`
- **Playback process or stream**
- [MCP control server](https://github.com/xikhar/persona/blob/main/electron/mcp-server.cts): `electron/mcp-server.cts`
- **MCP client**
- [VRoid Hub authentication](https://github.com/xikhar/persona/blob/main/electron/vroid-hub-auth.cts): `electron/vroid-hub-auth.cts`
- [VRoid Hub client](https://github.com/xikhar/persona/blob/main/electron/vroid-hub-client.cts): `electron/vroid-hub-client.cts`
- **VRoid Hub service**

### Other components

- **Desktop user**

## Connections

- Desktop user → Settings interface: configures (evidence: `README.md`)
- Settings interface → Settings persistence: saves settings
- Electron coordinator → Settings persistence: loads settings (evidence: `electron/main.cts`)
- Settings persistence → Packaged library catalog: uses catalog (evidence: `electron/settings-store.cts`)
- Electron coordinator → Voice output listener: starts listener (evidence: `electron/main.cts`)
- Electron coordinator → Voice source discovery: discovers sources (evidence: `electron/main.cts`)
- Playback process or stream → Voice output listener: provides playback
- Voice output listener → Renderer app state: sends voice state
- Electron coordinator → Renderer app state: launches window (evidence: `README.md`)
- Desktop user → Overlay window controls: toggles overlay (evidence: `README.md`)
- Renderer app state → 3D scene and camera: renders scene (evidence: `src/App.tsx`)
- 3D scene and camera → Avatar rig and motion: renders avatar (evidence: `src/components/Scene.tsx`)
- Avatar rig and motion → Animation scheduler: updates animation (evidence: `src/components/Avatar.tsx`)
- Animation scheduler → Animation catalog: selects clips (evidence: `src/animation-scheduler.ts`)
- Renderer app state → Drag secondary motion: queues drag motion (evidence: `src/App.tsx`)
- Avatar rig and motion → Drag secondary motion: applies body lag (evidence: `src/components/Avatar.tsx`)
- Desktop user → MCP client: requests controls (evidence: `README.md`)
- MCP client → MCP control server: sends MCP requests (evidence: `README.md`)
- Electron coordinator → MCP control server: starts server (evidence: `electron/main.cts`)
- Desktop user → VRoid Hub authentication: connects account (evidence: `README.md`)
- Electron coordinator → VRoid Hub authentication: configures auth (evidence: `electron/main.cts`)
- VRoid Hub authentication → VRoid Hub client: provides tokens (evidence: `electron/vroid-hub-client.cts`)
- VRoid Hub client → VRoid Hub service: fetches characters (evidence: `electron/vroid-hub-client.cts`)
- Animation generation → Packaged library catalog: uses catalog (evidence: `electron/animation-generator.cts`)
- Packaged library catalog → Animation scheduler: supplies animation media
