# alex2772/kuni architecture

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

- Interactive diagram: https://gitdiagram.com/alex2772/kuni
- Repository: https://github.com/alex2772/kuni

## Overview

Kuni is a Telegram-based LLM character: incoming Telegram activity is formatted as context and notifications, processed by worker-driven chat logic and an OpenAI-compatible model, then acted on through Telegram tools. Its documented capabilities also include persistent diary/RAG memory and sleep consolidation, working memory, media handling, speech, web search, and an optional LLM proxy. The supplied excerpts establish the main entry point and selected interfaces; several capability branches are documented or indexed but their detailed runtime wiring was not sampled.

Main entry points: [`src/main.cpp`](https://github.com/alex2772/kuni/blob/master/src/main.cpp) (Application flow), [`src/telegram/TelegramClientImpl.cpp`](https://github.com/alex2772/kuni/blob/master/src/telegram/TelegramClientImpl.cpp) (Telegram client), [`src/Worker.cpp`](https://github.com/alex2772/kuni/blob/master/src/Worker.cpp) (Notification workers), [`src/proxy_server/context_bridge.cpp`](https://github.com/alex2772/kuni/blob/master/src/proxy_server/context_bridge.cpp) (Proxy context bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Conversation runtime"]
  node_main["Application flow<br/>[main.cpp]"]
  node_workers["Notification workers<br/>[Worker.cpp]"]
  node_notifications["Notification queue"]
  node_tg_format["Telegram formatting<br/>[telegram.cpp]"]
  node_config["Runtime configuration<br/>[config.h]"]
end

subgraph group_memory["Memory and context"]
  node_diary[("Diary memory<br/>[Diary.h]")]
  node_context_bridge["Proxy context bridge<br/>[context_bridge.cpp]"]
end

subgraph group_capabilities["Model capabilities"]
  node_tools["Telegram tools"]
  node_prompts["Prompt definitions<br/>[prompts.h]"]
  node_image["Image generation<br/>[ImageGenerator.h]"]
  node_video["Video processing<br/>[video.cpp]"]
  node_speech["Speech generation<br/>[VoiceGenerator.cpp]"]
  node_web_search["Web search<br/>[WebSearch.cpp]"]
end

subgraph group_integrations["External integrations"]
  node_tg_client["Telegram client"]
  node_telegram_api["Telegram TDLib"]
  node_chat_api["Chat model API<br/>[OpenAIChatImpl.h]"]
  node_openai_api["OpenAI-compatible service"]
  node_proxy["LLM proxy<br/>[proxy_server.cpp]"]
  node_stable_diffusion["Stable Diffusion"]
  node_speech_services["Speech services"]
end

node_telegram_user(("Telegram user"))

node_telegram_user -->|"sends activity"| node_tg_client
node_tg_client -->|"uses TDLib"| node_telegram_api
node_main -->|"configures client"| node_tg_client
node_main -.->|"runs conversations"| node_workers
node_main -.->|"routes events"| node_notifications
node_workers -->|"processes queue"| node_notifications
node_main -->|"formats messages"| node_tg_format
node_main -->|"requests model"| node_chat_api
node_chat_api -.->|"calls endpoint"| node_openai_api
node_main -->|"dispatches tool calls"| node_tools
node_tools -.->|"issues Telegram actions"| node_tg_client
node_main -.->|"uses memory"| node_diary
node_main -->|"uses prompts"| node_prompts
node_proxy -->|"records sessions"| node_context_bridge
node_context_bridge -->|"saves summaries"| node_diary
node_main -->|"starts optional proxy"| node_proxy
node_main -->|"configures image generation"| node_image
node_image -.->|"generates images"| node_stable_diffusion
node_main -->|"uses video handling"| node_video
node_main -.->|"uses speech capability"| node_speech
node_speech -.->|"requests voice output"| node_speech_services
node_main -.->|"uses search capability"| node_web_search
node_main -->|"reads settings"| node_config

click node_main "https://github.com/alex2772/kuni/blob/master/src/main.cpp"
click node_workers "https://github.com/alex2772/kuni/blob/master/src/Worker.cpp"
click node_notifications "https://github.com/alex2772/kuni/blob/master/src/NotificationManager.h"
click node_tg_client "https://github.com/alex2772/kuni/blob/master/src/telegram/TelegramClientImpl.cpp"
click node_tg_format "https://github.com/alex2772/kuni/blob/master/src/llmui/telegram.cpp"
click node_tools "https://github.com/alex2772/kuni/tree/master/src/tools"
click node_chat_api "https://github.com/alex2772/kuni/blob/master/src/OpenAIChatImpl.h"
click node_diary "https://github.com/alex2772/kuni/blob/master/src/Diary.h"
click node_context_bridge "https://github.com/alex2772/kuni/blob/master/src/proxy_server/context_bridge.cpp"
click node_proxy "https://github.com/alex2772/kuni/blob/master/src/proxy_server/proxy_server.cpp"
click node_prompts "https://github.com/alex2772/kuni/blob/master/src/prompts.h"
click node_image "https://github.com/alex2772/kuni/blob/master/src/ImageGenerator.h"
click node_stable_diffusion "https://github.com/alex2772/kuni/blob/master/src/StableDiffusionClientImpl.cpp"
click node_video "https://github.com/alex2772/kuni/blob/master/src/llmui/video.cpp"
click node_speech "https://github.com/alex2772/kuni/blob/master/src/speech/VoiceGenerator.cpp"
click node_speech_services "https://github.com/alex2772/kuni/blob/master/src/speech/ElevenLabsClient.cpp"
click node_web_search "https://github.com/alex2772/kuni/blob/master/src/WebSearch.cpp"
click node_config "https://github.com/alex2772/kuni/blob/master/src/config.h"

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_main,node_workers,node_notifications,node_tg_format,node_config,node_telegram_user toneBlue
class node_diary,node_context_bridge toneAmber
class node_tools,node_prompts,node_image,node_video,node_speech,node_web_search toneMint
class node_tg_client,node_telegram_api,node_chat_api,node_openai_api,node_proxy,node_stable_diffusion,node_speech_services toneRose
```

## Components

### Conversation runtime

- [Application flow](https://github.com/alex2772/kuni/blob/master/src/main.cpp): `src/main.cpp`
- [Notification workers](https://github.com/alex2772/kuni/blob/master/src/Worker.cpp): `src/Worker.cpp`
- [Notification queue](https://github.com/alex2772/kuni/blob/master/src/NotificationManager.h): `src/NotificationManager.h`
- [Telegram formatting](https://github.com/alex2772/kuni/blob/master/src/llmui/telegram.cpp): `src/llmui/telegram.cpp`
- [Runtime configuration](https://github.com/alex2772/kuni/blob/master/src/config.h): `src/config.h`

### Memory and context

- [Diary memory](https://github.com/alex2772/kuni/blob/master/src/Diary.h): `src/Diary.h`
- [Proxy context bridge](https://github.com/alex2772/kuni/blob/master/src/proxy_server/context_bridge.cpp): `src/proxy_server/context_bridge.cpp`

### Model capabilities

- [Telegram tools](https://github.com/alex2772/kuni/tree/master/src/tools): `src/tools`
- [Prompt definitions](https://github.com/alex2772/kuni/blob/master/src/prompts.h): `src/prompts.h`
- [Image generation](https://github.com/alex2772/kuni/blob/master/src/ImageGenerator.h): `src/ImageGenerator.h`
- [Video processing](https://github.com/alex2772/kuni/blob/master/src/llmui/video.cpp): `src/llmui/video.cpp`
- [Speech generation](https://github.com/alex2772/kuni/blob/master/src/speech/VoiceGenerator.cpp): `src/speech/VoiceGenerator.cpp`
- [Web search](https://github.com/alex2772/kuni/blob/master/src/WebSearch.cpp): `src/WebSearch.cpp`

### External integrations

- [Telegram client](https://github.com/alex2772/kuni/blob/master/src/telegram/TelegramClientImpl.cpp): `src/telegram/TelegramClientImpl.cpp`
- **Telegram TDLib**
- [Chat model API](https://github.com/alex2772/kuni/blob/master/src/OpenAIChatImpl.h): `src/OpenAIChatImpl.h`
- **OpenAI-compatible service**
- [LLM proxy](https://github.com/alex2772/kuni/blob/master/src/proxy_server/proxy_server.cpp): `src/proxy_server/proxy_server.cpp`
- [Stable Diffusion](https://github.com/alex2772/kuni/blob/master/src/StableDiffusionClientImpl.cpp): `src/StableDiffusionClientImpl.cpp`
- [Speech services](https://github.com/alex2772/kuni/blob/master/src/speech/ElevenLabsClient.cpp): `src/speech/ElevenLabsClient.cpp`

### Other components

- **Telegram user**

## Connections

- Telegram user → Telegram client: sends activity
- Telegram client → Telegram TDLib: uses TDLib
- Application flow → Telegram client: configures client (evidence: `src/main.cpp`)
- Application flow → Notification workers: runs conversations
- Application flow → Notification queue: routes events
- Notification workers → Notification queue: processes queue (evidence: `src/Worker.cpp`)
- Application flow → Telegram formatting: formats messages (evidence: `src/main.cpp`)
- Application flow → Chat model API: requests model (evidence: `src/main.cpp`)
- Chat model API → OpenAI-compatible service: calls endpoint
- Application flow → Telegram tools: dispatches tool calls (evidence: `src/main.cpp`)
- Telegram tools → Telegram client: issues Telegram actions
- Application flow → Diary memory: uses memory
- Application flow → Prompt definitions: uses prompts (evidence: `src/main.cpp`)
- LLM proxy → Proxy context bridge: records sessions (evidence: `src/proxy_server/context_bridge.cpp`)
- Proxy context bridge → Diary memory: saves summaries (evidence: `src/proxy_server/context_bridge.cpp`)
- Application flow → LLM proxy: starts optional proxy (evidence: `src/main.cpp`)
- Application flow → Image generation: configures image generation (evidence: `src/main.cpp`)
- Image generation → Stable Diffusion: generates images
- Application flow → Video processing: uses video handling (evidence: `src/main.cpp`)
- Application flow → Speech generation: uses speech capability
- Speech generation → Speech services: requests voice output
- Application flow → Web search: uses search capability
- Application flow → Runtime configuration: reads settings (evidence: `src/main.cpp`)
