# jrsmdev/violet architecture

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

## Overview

Yuki is an AI VTuber companion for live streaming: it accepts chat, voice, and game context, chooses persona-driven reactions, generates dialogue and speech, and presents the result through an avatar and OBS widgets. The graph highlights chat/voice and gameplay as distinct inputs, with mind, memory, and generation control as internal decision layers. The README documents vision and the broader overlay/game capabilities; source evidence is selective, so unsampled implementation links are omitted rather than inferred.

Main entry points: [`backend/api/stream.py`](https://github.com/jrsmdev/violet/blob/main/backend/api/stream.py) (Stream API), [`backend/main.py`](https://github.com/jrsmdev/violet/blob/main/backend/main.py) (FastAPI Routes), [`backend/services/llm_service.py`](https://github.com/jrsmdev/violet/blob/main/backend/services/llm_service.py) (LLM Service), [`backend/services/mind_service.py`](https://github.com/jrsmdev/violet/blob/main/backend/services/mind_service.py) (Mind & Reactions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interfaces"]
  node_frontend["Web UI<br/>[App.tsx]"]
  node_director["Director Panel<br/>[Director.tsx]"]
  node_overlays["OBS Widgets<br/>[MasterOverlay.tsx]"]
end

subgraph group_runtime["Conversation Runtime"]
  node_api["FastAPI Routes<br/>[main.py]"]
  node_voice_api["Voice Endpoint<br/>[voice.py]"]
  node_pipeline["Dialogue Pipeline<br/>[orchestrator.py]"]
  node_mind["Mind &amp; Reactions<br/>[mind_service.py]"]
  node_llm["LLM Service<br/>[llm_service.py]"]
  node_generation["Generation Control"]
end

subgraph group_streaming["Streaming &amp; Games"]
  node_stream_api["Stream API<br/>[stream.py]"]
  node_game_bridge["Game Bridge<br/>[game_bridge.py]"]
  node_osu["osu! Reactions<br/>[osu_service.py]"]
  node_studio["Studio Services<br/>[studio_service.py]"]
  node_vision["Vision<br/>[vision_service.py]"]
end

subgraph group_support["State &amp; Speech"]
  node_tts["Speech Synthesis<br/>[tts_service.py]"]
  node_memory[("Conversation Memory<br/>[memory_service.py]")]
  node_events["Event Bus<br/>[event_bus.py]"]
end

node_streamer(("Streamer"))
node_audience(("Stream Audience"))
node_game(("Connected Game"))
node_ollama["Ollama LLM"]

node_streamer -->|"uses"| node_frontend
node_audience -->|"sends chat"| node_stream_api
node_game -->|"streams context"| node_game_bridge
node_frontend -->|"uploads audio"| node_voice_api
node_api -->|"registers routes"| node_voice_api
node_api -->|"registers routes"| node_stream_api
node_api -->|"registers socket"| node_game_bridge
node_pipeline -->|"calls"| node_llm
node_pipeline -->|"calls"| node_tts
node_pipeline -->|"publishes events"| node_events
node_llm -->|"requests generation"| node_ollama
node_llm -->|"reads and writes"| node_memory
node_llm -->|"publishes thoughts"| node_events
node_mind -->|"uses memory"| node_memory
node_mind -->|"uses controller"| node_generation
node_mind -->|"uses stream service"| node_stream_api
node_osu -->|"broadcasts reactions"| node_stream_api
node_api -->|"serves panel APIs"| node_director
node_director -->|"controls studio"| node_studio
node_stream_api -.->|"feeds overlays"| node_overlays
node_vision -.->|"informs awareness"| node_mind

click node_frontend "https://github.com/jrsmdev/violet/blob/main/frontend/src/App.tsx"
click node_director "https://github.com/jrsmdev/violet/blob/main/frontend/src/Director.tsx"
click node_overlays "https://github.com/jrsmdev/violet/blob/main/frontend/src/MasterOverlay.tsx"
click node_api "https://github.com/jrsmdev/violet/blob/main/backend/main.py"
click node_voice_api "https://github.com/jrsmdev/violet/blob/main/backend/api/voice.py"
click node_stream_api "https://github.com/jrsmdev/violet/blob/main/backend/api/stream.py"
click node_pipeline "https://github.com/jrsmdev/violet/blob/main/backend/pipeline/orchestrator.py"
click node_mind "https://github.com/jrsmdev/violet/blob/main/backend/services/mind_service.py"
click node_llm "https://github.com/jrsmdev/violet/blob/main/backend/services/llm_service.py"
click node_generation "https://github.com/jrsmdev/violet/blob/main/backend/services/generation_controller.py"
click node_tts "https://github.com/jrsmdev/violet/blob/main/backend/services/tts_service.py"
click node_memory "https://github.com/jrsmdev/violet/blob/main/backend/services/memory_service.py"
click node_events "https://github.com/jrsmdev/violet/blob/main/backend/core/event_bus.py"
click node_game_bridge "https://github.com/jrsmdev/violet/blob/main/backend/agent/game_bridge.py"
click node_osu "https://github.com/jrsmdev/violet/blob/main/backend/services/osu_service.py"
click node_studio "https://github.com/jrsmdev/violet/blob/main/backend/services/studio_service.py"
click node_vision "https://github.com/jrsmdev/violet/blob/main/backend/services/vision_service.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_frontend,node_director,node_overlays toneBlue
class node_api,node_voice_api,node_pipeline,node_mind,node_llm,node_generation toneAmber
class node_stream_api,node_game_bridge,node_osu,node_studio,node_vision toneMint
class node_tts,node_memory,node_events toneRose
class node_streamer,node_audience,node_game,node_ollama toneIndigo
```

## Components

### User Interfaces

- [Web UI](https://github.com/jrsmdev/violet/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Director Panel](https://github.com/jrsmdev/violet/blob/main/frontend/src/Director.tsx): `frontend/src/Director.tsx`
- [OBS Widgets](https://github.com/jrsmdev/violet/blob/main/frontend/src/MasterOverlay.tsx): `frontend/src/MasterOverlay.tsx`

### Conversation Runtime

- [FastAPI Routes](https://github.com/jrsmdev/violet/blob/main/backend/main.py): `backend/main.py`
- [Voice Endpoint](https://github.com/jrsmdev/violet/blob/main/backend/api/voice.py): `backend/api/voice.py`
- [Dialogue Pipeline](https://github.com/jrsmdev/violet/blob/main/backend/pipeline/orchestrator.py): `backend/pipeline/orchestrator.py`
- [Mind & Reactions](https://github.com/jrsmdev/violet/blob/main/backend/services/mind_service.py): `backend/services/mind_service.py`
- [LLM Service](https://github.com/jrsmdev/violet/blob/main/backend/services/llm_service.py): `backend/services/llm_service.py`
- [Generation Control](https://github.com/jrsmdev/violet/blob/main/backend/services/generation_controller.py): `backend/services/generation_controller.py`

### Streaming & Games

- [Stream API](https://github.com/jrsmdev/violet/blob/main/backend/api/stream.py): `backend/api/stream.py`
- [Game Bridge](https://github.com/jrsmdev/violet/blob/main/backend/agent/game_bridge.py): `backend/agent/game_bridge.py`
- [osu! Reactions](https://github.com/jrsmdev/violet/blob/main/backend/services/osu_service.py): `backend/services/osu_service.py`
- [Studio Services](https://github.com/jrsmdev/violet/blob/main/backend/services/studio_service.py): `backend/services/studio_service.py`
- [Vision](https://github.com/jrsmdev/violet/blob/main/backend/services/vision_service.py): `backend/services/vision_service.py`

### State & Speech

- [Speech Synthesis](https://github.com/jrsmdev/violet/blob/main/backend/services/tts_service.py): `backend/services/tts_service.py`
- [Conversation Memory](https://github.com/jrsmdev/violet/blob/main/backend/services/memory_service.py): `backend/services/memory_service.py`
- [Event Bus](https://github.com/jrsmdev/violet/blob/main/backend/core/event_bus.py): `backend/core/event_bus.py`

### Other components

- **Streamer**
- **Stream Audience**
- **Connected Game**
- **Ollama LLM**

## Connections

- Streamer → Web UI: uses (evidence: `README.md`)
- Stream Audience → Stream API: sends chat (evidence: `README.md`)
- Connected Game → Game Bridge: streams context (evidence: `README.md`)
- Web UI → Voice Endpoint: uploads audio (evidence: `frontend/src/App.tsx`)
- FastAPI Routes → Voice Endpoint: registers routes (evidence: `backend/main.py`)
- FastAPI Routes → Stream API: registers routes (evidence: `backend/main.py`)
- FastAPI Routes → Game Bridge: registers socket
- Dialogue Pipeline → LLM Service: calls (evidence: `backend/pipeline/orchestrator.py`)
- Dialogue Pipeline → Speech Synthesis: calls (evidence: `backend/pipeline/orchestrator.py`)
- Dialogue Pipeline → Event Bus: publishes events (evidence: `backend/pipeline/orchestrator.py`)
- LLM Service → Ollama LLM: requests generation
- LLM Service → Conversation Memory: reads and writes (evidence: `backend/services/llm_service.py`)
- LLM Service → Event Bus: publishes thoughts (evidence: `backend/services/llm_service.py`)
- Mind & Reactions → Conversation Memory: uses memory (evidence: `backend/services/mind_service.py`)
- Mind & Reactions → Generation Control: uses controller (evidence: `backend/services/mind_service.py`)
- Mind & Reactions → Stream API: uses stream service (evidence: `backend/services/mind_service.py`)
- osu! Reactions → Stream API: broadcasts reactions (evidence: `backend/services/osu_service.py`)
- FastAPI Routes → Director Panel: serves panel APIs
- Director Panel → Studio Services: controls studio
- Stream API → OBS Widgets: feeds overlays (evidence: `README.md`)
- Vision → Mind & Reactions: informs awareness
