# 00mframadhani00/k.a.i.r.a-project architecture

> Architecture diagram of the GitHub repository 00mframadhani00/k.a.i.r.a-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/00mframadhani00/k.a.i.r.a-project
- Repository: https://github.com/00mframadhani00/k.a.i.r.a-project

## Overview

K.A.I.R.A is a desktop AI assistant and VTuber-oriented chat responder. Its main workflow accepts microphone speech or YouTube live chat, builds conversation context, requests a GPT response, translates it, and produces speech and OBS subtitle files. The runtime is largely orchestrated in run.py; utility modules provide prompting, translation, speech synthesis, and subtitles. Edges reflect the shown calls and file operations. The README names additional streaming technologies, but their integration is not demonstrated in the sampled runtime, so they are not shown as connected components.

Main entry points: [`run.py`](https://github.com/00mframadhani00/k.a.i.r.a-project/blob/master/run.py) (Conversation state), [`utils/promptMaker.py`](https://github.com/00mframadhani00/k.a.i.r.a-project/blob/master/utils/promptMaker.py) (Prompt construction), [`utils/translate.py`](https://github.com/00mframadhani00/k.a.i.r.a-project/blob/master/utils/translate.py) (Translation), [`utils/TTS.py`](https://github.com/00mframadhani00/k.a.i.r.a-project/blob/master/utils/TTS.py) (Speech synthesis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Input"]
  node_audio_capture["Audio capture<br/>[run.py]"]
  node_whisper["Whisper transcription"]
  node_live_chat["Live chat polling<br/>[run.py]"]
end

subgraph group_conversation["Conversation"]
  node_conversation_state["Conversation state<br/>[run.py]"]
  node_identity["Character identity<br/>[identity.txt]"]
  node_conversation_file[("Conversation history<br/>[conversation.json]")]
  node_prompt["Prompt construction<br/>[promptMaker.py]"]
end

subgraph group_response["Response"]
  node_gpt["GPT response"]
  node_translation["Translation<br/>[translate.py]"]
end

subgraph group_presentation["Presentation"]
  node_speech["Speech synthesis<br/>[TTS.py]"]
  node_subtitle["Subtitle files<br/>[subtitle.py]"]
  node_audio_playback["Audio playback<br/>[run.py]"]
end

node_mic(("Microphone user"))
node_youtube(("YouTube chat"))
node_voicevox["VoiceVox engine"]
node_obs(("OBS display"))

node_mic -->|"provides speech"| node_audio_capture
node_audio_capture -->|"submits audio"| node_whisper
node_whisper -->|"adds transcript"| node_conversation_state
node_youtube -->|"provides messages"| node_live_chat
node_live_chat -->|"adds messages"| node_conversation_state
node_conversation_state -->|"writes history"| node_conversation_file
node_conversation_file -->|"loads history"| node_prompt
node_identity -->|"adds identity"| node_prompt
node_conversation_state -->|"requests prompt"| node_prompt
node_prompt -->|"supplies context"| node_gpt
node_gpt -->|"passes response"| node_translation
node_translation -->|"translates text"| node_speech
node_speech -->|"requests synthesis"| node_voicevox
node_translation -->|"sends response"| node_subtitle
node_conversation_state -->|"sends question"| node_subtitle
node_subtitle -->|"writes display files"| node_obs
node_speech -->|"saves audio"| node_audio_playback
node_audio_playback -->|"plays reply"| node_mic

click node_audio_capture "https://github.com/00mframadhani00/k.a.i.r.a-project/blob/master/run.py"
click node_live_chat "https://github.com/00mframadhani00/k.a.i.r.a-project/blob/master/run.py"
click node_conversation_state "https://github.com/00mframadhani00/k.a.i.r.a-project/blob/master/run.py"
click node_identity "https://github.com/00mframadhani00/k.a.i.r.a-project/blob/master/characterConfig/KAIRA/identity.txt"
click node_conversation_file "https://github.com/00mframadhani00/k.a.i.r.a-project/blob/master/conversation.json"
click node_prompt "https://github.com/00mframadhani00/k.a.i.r.a-project/blob/master/utils/promptMaker.py"
click node_translation "https://github.com/00mframadhani00/k.a.i.r.a-project/blob/master/utils/translate.py"
click node_speech "https://github.com/00mframadhani00/k.a.i.r.a-project/blob/master/utils/TTS.py"
click node_subtitle "https://github.com/00mframadhani00/k.a.i.r.a-project/blob/master/utils/subtitle.py"
click node_audio_playback "https://github.com/00mframadhani00/k.a.i.r.a-project/blob/master/run.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_audio_capture,node_whisper,node_live_chat,node_mic toneBlue
class node_conversation_state,node_identity,node_conversation_file,node_prompt toneAmber
class node_gpt,node_translation toneMint
class node_speech,node_subtitle,node_audio_playback toneRose
class node_youtube,node_voicevox,node_obs toneIndigo
```

## Components

### Input

- [Audio capture](https://github.com/00mframadhani00/k.a.i.r.a-project/blob/master/run.py): `run.py`
- **Whisper transcription**
- [Live chat polling](https://github.com/00mframadhani00/k.a.i.r.a-project/blob/master/run.py): `run.py`

### Conversation

- [Conversation state](https://github.com/00mframadhani00/k.a.i.r.a-project/blob/master/run.py): `run.py`
- [Character identity](https://github.com/00mframadhani00/k.a.i.r.a-project/blob/master/characterConfig/KAIRA/identity.txt): `characterConfig/KAIRA/identity.txt`
- [Conversation history](https://github.com/00mframadhani00/k.a.i.r.a-project/blob/master/conversation.json): `conversation.json`
- [Prompt construction](https://github.com/00mframadhani00/k.a.i.r.a-project/blob/master/utils/promptMaker.py): `utils/promptMaker.py`

### Response

- **GPT response**
- [Translation](https://github.com/00mframadhani00/k.a.i.r.a-project/blob/master/utils/translate.py): `utils/translate.py`

### Presentation

- [Speech synthesis](https://github.com/00mframadhani00/k.a.i.r.a-project/blob/master/utils/TTS.py): `utils/TTS.py`
- [Subtitle files](https://github.com/00mframadhani00/k.a.i.r.a-project/blob/master/utils/subtitle.py): `utils/subtitle.py`
- [Audio playback](https://github.com/00mframadhani00/k.a.i.r.a-project/blob/master/run.py): `run.py`

### Other components

- **Microphone user**
- **YouTube chat**
- **VoiceVox engine**
- **OBS display**

## Connections

- Microphone user → Audio capture: provides speech (evidence: `run.py`)
- Audio capture → Whisper transcription: submits audio (evidence: `run.py`)
- Whisper transcription → Conversation state: adds transcript (evidence: `run.py`)
- YouTube chat → Live chat polling: provides messages (evidence: `run.py`)
- Live chat polling → Conversation state: adds messages (evidence: `run.py`)
- Conversation state → Conversation history: writes history (evidence: `run.py`)
- Conversation history → Prompt construction: loads history (evidence: `utils/promptMaker.py`)
- Character identity → Prompt construction: adds identity (evidence: `utils/promptMaker.py`)
- Conversation state → Prompt construction: requests prompt (evidence: `run.py`)
- Prompt construction → GPT response: supplies context
- GPT response → Translation: passes response
- Translation → Speech synthesis: translates text (evidence: `run.py`)
- Speech synthesis → VoiceVox engine: requests synthesis (evidence: `utils/TTS.py`)
- Translation → Subtitle files: sends response (evidence: `run.py`)
- Conversation state → Subtitle files: sends question (evidence: `run.py`)
- Subtitle files → OBS display: writes display files (evidence: `utils/subtitle.py`)
- Speech synthesis → Audio playback: saves audio (evidence: `utils/TTS.py`)
- Audio playback → Microphone user: plays reply (evidence: `run.py`)