# sinhs0301-prog/kimbiseo architecture

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

- Interactive diagram: https://gitdiagram.com/sinhs0301-prog/kimbiseo
- Repository: https://github.com/sinhs0301-prog/kimbiseo

## Overview

KimBiseo is a local Windows voice assistant with a desktop character pet. The main workflow runs from the conversation UI or microphone through a session that handles speech recognition, turn-taking, memory and tools, then selects a brain and speaks a response; pet signals accompany the conversation. Settings, onboarding, system information and signed updates are separate product capabilities. Relationships for unsampled modules are included only where the README or source index documents them; dashed edges indicate unverified links.

Main entry points: [`app/core/session.py`](https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/core/session.py) (Conversation session), [`app/main.py`](https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/main.py) (Local app server), [`app/core/brain.py`](https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/core/brain.py) (Brain backends), [`voice`](https://github.com/sinhs0301-prog/kimbiseo/tree/main/voice) (Voice servers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Conversation"]
  node_ui["Conversation UI<br/>[app.js]"]
  node_main["Local app server<br/>[main.py]"]
  node_session["Conversation session<br/>[session.py]"]
  node_turns["Turn handling<br/>[turns.py]"]
  node_memory[("Conversation memory<br/>[memory.py]")]
end

subgraph group_brain_tools["Brain and tools"]
  node_brain["Brain backends<br/>[brain.py]"]
  node_cli_brain["CLI brains<br/>[cli_brain.py]"]
  node_cli_detect["CLI detection<br/>[cli_detect.py]"]
  node_tools["Tool registry<br/>[registry.py]"]
  node_tool_handlers["Basic tool handlers<br/>[handlers.py]"]
end

subgraph group_voice["Voice"]
  node_stt["Speech recognition<br/>[stt.py]"]
  node_tts["Speech synthesis<br/>[tts.py]"]
  node_voice_link["Voice service link<br/>[voice_link.py]"]
  node_voice_services["Voice servers"]
end

subgraph group_pet["Desktop pet"]
  node_pet_link["Pet signal adapter<br/>[face.py]"]
  node_pet_app["Pet application<br/>[main.js]"]
  node_pet_server["Pet HTTP server<br/>[server.js]"]
  node_pet_renderer["Pet renderer<br/>[real.js]"]
end

subgraph group_settings_update["Settings and updates"]
  node_settings_api["Settings API<br/>[settings_api.py]"]
  node_config[("Configuration<br/>[config.py]")]
  node_wizard["Setup wizard<br/>[wizard.js]"]
  node_update["Update manager<br/>[update.py]"]
  node_updater["Update worker<br/>[updater.py]"]
end

node_user(("User"))
node_cli_services["Claude and Codex"]
node_brain_services["AI services"]
node_microphone(("Microphone"))
node_speakers(("Speakers"))

node_user -->|"enters requests"| node_ui
node_ui -->|"connects via WebRTC"| node_main
node_main -->|"starts session"| node_session
node_microphone -.->|"sends audio"| node_session
node_session -->|"handles turns"| node_turns
node_session -->|"uses recognition"| node_stt
node_session -->|"creates brain"| node_brain
node_session -->|"loads and saves"| node_memory
node_session -->|"registers tools"| node_tools
node_session -->|"uses synthesis"| node_tts
node_session -.->|"links voice service"| node_voice_link
node_stt -.->|"uses speech service"| node_voice_services
node_tts -.->|"uses speech service"| node_voice_services
node_voice_services -.->|"outputs speech"| node_speakers
node_brain -->|"dispatches CLI mode"| node_cli_brain
node_cli_brain -->|"invokes local CLI"| node_cli_services
node_brain -.->|"sends requests"| node_brain_services
node_tools -->|"loads handlers"| node_tool_handlers
node_main -->|"serves settings"| node_settings_api
node_settings_api -->|"reads and saves"| node_config
node_wizard -.->|"configures assistant"| node_main
node_main -->|"exposes updates"| node_update
node_update -->|"starts update worker"| node_updater
node_session -.->|"sends conversation events"| node_pet_link
node_main -->|"sends pet commands"| node_pet_link
node_pet_link -->|"posts signals"| node_pet_server
node_pet_app -->|"starts server"| node_pet_server
node_pet_app -.->|"displays character"| node_pet_renderer

click node_ui "https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/ui/app.js"
click node_main "https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/main.py"
click node_session "https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/core/session.py"
click node_turns "https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/core/turns.py"
click node_memory "https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/core/memory.py"
click node_brain "https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/core/brain.py"
click node_cli_brain "https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/core/cli_brain.py"
click node_cli_detect "https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/core/cli_detect.py"
click node_tools "https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/tools/registry.py"
click node_tool_handlers "https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/tools/basic/handlers.py"
click node_stt "https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/core/stt.py"
click node_tts "https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/core/tts.py"
click node_voice_link "https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/core/voice_link.py"
click node_voice_services "https://github.com/sinhs0301-prog/kimbiseo/tree/main/voice"
click node_settings_api "https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/core/settings_api.py"
click node_config "https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/core/config.py"
click node_wizard "https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/ui/wizard.js"
click node_update "https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/core/update.py"
click node_updater "https://github.com/sinhs0301-prog/kimbiseo/blob/main/installer/updater.py"
click node_pet_link "https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/pet_link/face.py"
click node_pet_app "https://github.com/sinhs0301-prog/kimbiseo/blob/main/pet/main.js"
click node_pet_server "https://github.com/sinhs0301-prog/kimbiseo/blob/main/pet/server.js"
click node_pet_renderer "https://github.com/sinhs0301-prog/kimbiseo/blob/main/pet/renderer/real.js"

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_ui,node_main,node_session,node_turns,node_memory,node_user toneBlue
class node_brain,node_cli_brain,node_cli_detect,node_tools,node_tool_handlers toneAmber
class node_stt,node_tts,node_voice_link,node_voice_services toneMint
class node_pet_link,node_pet_app,node_pet_server,node_pet_renderer toneRose
class node_settings_api,node_config,node_wizard,node_update,node_updater,node_cli_services,node_brain_services,node_microphone,node_speakers toneIndigo
```

## Components

### Conversation

- [Conversation UI](https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/ui/app.js): `app/ui/app.js`
- [Local app server](https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/main.py): `app/main.py`
- [Conversation session](https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/core/session.py): `app/core/session.py`
- [Turn handling](https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/core/turns.py): `app/core/turns.py`
- [Conversation memory](https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/core/memory.py): `app/core/memory.py`

### Brain and tools

- [Brain backends](https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/core/brain.py): `app/core/brain.py`
- [CLI brains](https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/core/cli_brain.py): `app/core/cli_brain.py`
- [CLI detection](https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/core/cli_detect.py): `app/core/cli_detect.py`
- [Tool registry](https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/tools/registry.py): `app/tools/registry.py`
- [Basic tool handlers](https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/tools/basic/handlers.py): `app/tools/basic/handlers.py`

### Voice

- [Speech recognition](https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/core/stt.py): `app/core/stt.py`
- [Speech synthesis](https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/core/tts.py): `app/core/tts.py`
- [Voice service link](https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/core/voice_link.py): `app/core/voice_link.py`
- [Voice servers](https://github.com/sinhs0301-prog/kimbiseo/tree/main/voice): `voice`

### Desktop pet

- [Pet signal adapter](https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/pet_link/face.py): `app/pet_link/face.py`
- [Pet application](https://github.com/sinhs0301-prog/kimbiseo/blob/main/pet/main.js): `pet/main.js`
- [Pet HTTP server](https://github.com/sinhs0301-prog/kimbiseo/blob/main/pet/server.js): `pet/server.js`
- [Pet renderer](https://github.com/sinhs0301-prog/kimbiseo/blob/main/pet/renderer/real.js): `pet/renderer/real.js`

### Settings and updates

- [Settings API](https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/core/settings_api.py): `app/core/settings_api.py`
- [Configuration](https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/core/config.py): `app/core/config.py`
- [Setup wizard](https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/ui/wizard.js): `app/ui/wizard.js`
- [Update manager](https://github.com/sinhs0301-prog/kimbiseo/blob/main/app/core/update.py): `app/core/update.py`
- [Update worker](https://github.com/sinhs0301-prog/kimbiseo/blob/main/installer/updater.py): `installer/updater.py`

### Other components

- **User**
- **Claude and Codex**
- **AI services**
- **Microphone**
- **Speakers**

## Connections

- User → Conversation UI: enters requests
- Conversation UI → Local app server: connects via WebRTC (evidence: `app/main.py`)
- Local app server → Conversation session: starts session (evidence: `app/main.py`)
- Microphone → Conversation session: sends audio
- Conversation session → Turn handling: handles turns (evidence: `app/core/session.py`)
- Conversation session → Speech recognition: uses recognition (evidence: `app/core/session.py`)
- Conversation session → Brain backends: creates brain (evidence: `app/core/session.py`)
- Conversation session → Conversation memory: loads and saves (evidence: `app/core/session.py`)
- Conversation session → Tool registry: registers tools (evidence: `app/core/session.py`)
- Conversation session → Speech synthesis: uses synthesis (evidence: `app/core/session.py`)
- Conversation session → Voice service link: links voice service
- Speech recognition → Voice servers: uses speech service
- Speech synthesis → Voice servers: uses speech service
- Voice servers → Speakers: outputs speech
- Brain backends → CLI brains: dispatches CLI mode (evidence: `app/core/brain.py`)
- CLI brains → Claude and Codex: invokes local CLI (evidence: `app/core/cli_brain.py`)
- Brain backends → AI services: sends requests
- Tool registry → Basic tool handlers: loads handlers (evidence: `app/tools/registry.py`)
- Local app server → Settings API: serves settings (evidence: `app/main.py`)
- Settings API → Configuration: reads and saves (evidence: `app/core/settings_api.py`)
- Setup wizard → Local app server: configures assistant
- Local app server → Update manager: exposes updates (evidence: `app/main.py`)
- Update manager → Update worker: starts update worker (evidence: `app/core/update.py`)
- Conversation session → Pet signal adapter: sends conversation events
- Local app server → Pet signal adapter: sends pet commands (evidence: `app/main.py`)
- Pet signal adapter → Pet HTTP server: posts signals (evidence: `app/pet_link/face.py`)
- Pet application → Pet HTTP server: starts server (evidence: `pet/main.js`)
- Pet application → Pet renderer: displays character