# damirasainov/aikoru architecture

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

- Interactive diagram: https://gitdiagram.com/damirasainov/aikoru
- Repository: https://github.com/damirasainov/aikoru

## Overview

AIKORU is an offline Russian/Kazakh spatial-awareness assistant for blind and low-vision users. Its main workflow captures camera frames, detects and tracks objects, interprets scene changes, and speaks useful alerts; users can also issue voice commands to describe a scene, find an object, or manage familiar faces. The web interface exposes video, events, command entry, and face controls. The graph follows the README and shown source references; some internal orchestration details are unsampled, so only documented or indexed relationships are shown.

Main entry points: [`aikoru/assistant.py`](https://github.com/damirasainov/aikoru/blob/main/aikoru/assistant.py) (Assistant orchestrator), [`aikoru/web.py`](https://github.com/damirasainov/aikoru/blob/main/aikoru/web.py) (Web server and API), [`aikoru/tts.py`](https://github.com/damirasainov/aikoru/blob/main/aikoru/tts.py) (Prioritized speech output), [`aikoru/camera.py`](https://github.com/damirasainov/aikoru/blob/main/aikoru/camera.py) (Frame capture)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application control"]
  node_launcher["Runtime entry<br/>[__main__.py]"]
  node_configuration["Configuration<br/>[config.py]"]
  node_assistant["Assistant orchestrator<br/>[assistant.py]"]
end

subgraph group_perception["Camera perception"]
  node_camera["Frame capture<br/>[camera.py]"]
  node_detector["Object detection and tracking<br/>[detector.py]"]
  node_scene["Scene and track state<br/>[scene.py]"]
  node_faces[("Familiar face recognition<br/>[faces.py]")]
end

subgraph group_interaction["Voice and commands"]
  node_voice["Wake word and speech input<br/>[voice.py]"]
  node_commands["Command interpretation<br/>[commands.py]"]
  node_lexicon["Bilingual lexicon and phrases<br/>[lexicon.py]"]
end

subgraph group_response["Assistant responses"]
  node_translator["NLLB translation<br/>[translator.py]"]
  node_vlm["Scene description and questions<br/>[vlm.py]"]
  node_speaker["Prioritized speech output<br/>[tts.py]"]
end

subgraph group_interface["Web interface"]
  node_web_server["Web server and API<br/>[web.py]"]
  node_web_client["Web interface<br/>[app.js]"]
end

node_user(("User"))
node_microphone(("Microphone"))
node_headphones(("Headphones"))
node_browser(("Browser"))
node_camera_device(("USB camera"))

node_user -->|"speaks commands"| node_microphone
node_microphone -->|"provides audio"| node_voice
node_voice -->|"delivers command"| node_assistant
node_assistant -->|"parses command"| node_commands
node_commands -->|"looks up objects"| node_lexicon
node_assistant -->|"loads settings"| node_configuration
node_launcher -->|"starts runtime"| node_assistant
node_camera_device -->|"supplies frames"| node_camera
node_assistant -->|"reads frames"| node_camera
node_assistant -->|"scans frames"| node_detector
node_detector -->|"provides tracked detections"| node_scene
node_assistant -->|"updates scene"| node_scene
node_assistant -->|"identifies familiar people"| node_faces
node_assistant -->|"translates object queries"| node_translator
node_assistant -->|"requests scene description"| node_vlm
node_assistant -->|"queues spoken response"| node_speaker
node_speaker -->|"formats speech"| node_lexicon
node_speaker -->|"plays speech"| node_headphones
node_assistant -->|"starts interface"| node_web_server
node_web_server -->|"serves camera frames"| node_camera
node_web_server -->|"routes commands and controls"| node_assistant
node_web_server -->|"serves interface assets"| node_web_client
node_browser -->|"requests interface and API"| node_web_server
node_web_client -->|"renders controls and events"| node_browser

click node_launcher "https://github.com/damirasainov/aikoru/blob/main/aikoru/__main__.py"
click node_configuration "https://github.com/damirasainov/aikoru/blob/main/aikoru/config.py"
click node_assistant "https://github.com/damirasainov/aikoru/blob/main/aikoru/assistant.py"
click node_camera "https://github.com/damirasainov/aikoru/blob/main/aikoru/camera.py"
click node_detector "https://github.com/damirasainov/aikoru/blob/main/aikoru/detector.py"
click node_scene "https://github.com/damirasainov/aikoru/blob/main/aikoru/scene.py"
click node_faces "https://github.com/damirasainov/aikoru/blob/main/aikoru/faces.py"
click node_voice "https://github.com/damirasainov/aikoru/blob/main/aikoru/voice.py"
click node_commands "https://github.com/damirasainov/aikoru/blob/main/aikoru/commands.py"
click node_lexicon "https://github.com/damirasainov/aikoru/blob/main/aikoru/lexicon.py"
click node_translator "https://github.com/damirasainov/aikoru/blob/main/aikoru/translator.py"
click node_vlm "https://github.com/damirasainov/aikoru/blob/main/aikoru/vlm.py"
click node_speaker "https://github.com/damirasainov/aikoru/blob/main/aikoru/tts.py"
click node_web_server "https://github.com/damirasainov/aikoru/blob/main/aikoru/web.py"
click node_web_client "https://github.com/damirasainov/aikoru/blob/main/aikoru/web/app.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_launcher,node_configuration,node_assistant,node_user,node_browser toneBlue
class node_camera,node_detector,node_scene,node_faces toneAmber
class node_voice,node_commands,node_lexicon toneMint
class node_translator,node_vlm,node_speaker toneRose
class node_web_server,node_web_client,node_microphone,node_headphones,node_camera_device toneIndigo
```

## Components

### Application control

- [Runtime entry](https://github.com/damirasainov/aikoru/blob/main/aikoru/__main__.py): `aikoru/__main__.py`
- [Configuration](https://github.com/damirasainov/aikoru/blob/main/aikoru/config.py): `aikoru/config.py`
- [Assistant orchestrator](https://github.com/damirasainov/aikoru/blob/main/aikoru/assistant.py): `aikoru/assistant.py`

### Camera perception

- [Frame capture](https://github.com/damirasainov/aikoru/blob/main/aikoru/camera.py): `aikoru/camera.py`
- [Object detection and tracking](https://github.com/damirasainov/aikoru/blob/main/aikoru/detector.py): `aikoru/detector.py`
- [Scene and track state](https://github.com/damirasainov/aikoru/blob/main/aikoru/scene.py): `aikoru/scene.py`
- [Familiar face recognition](https://github.com/damirasainov/aikoru/blob/main/aikoru/faces.py): `aikoru/faces.py`

### Voice and commands

- [Wake word and speech input](https://github.com/damirasainov/aikoru/blob/main/aikoru/voice.py): `aikoru/voice.py`
- [Command interpretation](https://github.com/damirasainov/aikoru/blob/main/aikoru/commands.py): `aikoru/commands.py`
- [Bilingual lexicon and phrases](https://github.com/damirasainov/aikoru/blob/main/aikoru/lexicon.py): `aikoru/lexicon.py`

### Assistant responses

- [NLLB translation](https://github.com/damirasainov/aikoru/blob/main/aikoru/translator.py): `aikoru/translator.py`
- [Scene description and questions](https://github.com/damirasainov/aikoru/blob/main/aikoru/vlm.py): `aikoru/vlm.py`
- [Prioritized speech output](https://github.com/damirasainov/aikoru/blob/main/aikoru/tts.py): `aikoru/tts.py`

### Web interface

- [Web server and API](https://github.com/damirasainov/aikoru/blob/main/aikoru/web.py): `aikoru/web.py`
- [Web interface](https://github.com/damirasainov/aikoru/blob/main/aikoru/web/app.js): `aikoru/web/app.js`

### Other components

- **User**
- **Microphone**
- **Headphones**
- **Browser**
- **USB camera**

## Connections

- User → Microphone: speaks commands (evidence: `README.md`)
- Microphone → Wake word and speech input: provides audio (evidence: `README.md`)
- Wake word and speech input → Assistant orchestrator: delivers command (evidence: `README.md`)
- Assistant orchestrator → Command interpretation: parses command (evidence: `aikoru/assistant.py`)
- Command interpretation → Bilingual lexicon and phrases: looks up objects (evidence: `aikoru/commands.py`)
- Assistant orchestrator → Configuration: loads settings (evidence: `aikoru/__main__.py`)
- Runtime entry → Assistant orchestrator: starts runtime (evidence: `aikoru/__main__.py`)
- USB camera → Frame capture: supplies frames (evidence: `README.md`)
- Assistant orchestrator → Frame capture: reads frames (evidence: `README.md`)
- Assistant orchestrator → Object detection and tracking: scans frames (evidence: `README.md`)
- Object detection and tracking → Scene and track state: provides tracked detections (evidence: `aikoru/scene.py`)
- Assistant orchestrator → Scene and track state: updates scene (evidence: `README.md`)
- Assistant orchestrator → Familiar face recognition: identifies familiar people (evidence: `README.md`)
- Assistant orchestrator → NLLB translation: translates object queries (evidence: `README.md`)
- Assistant orchestrator → Scene description and questions: requests scene description (evidence: `README.md`)
- Assistant orchestrator → Prioritized speech output: queues spoken response (evidence: `README.md`)
- Prioritized speech output → Bilingual lexicon and phrases: formats speech (evidence: `aikoru/tts.py`)
- Prioritized speech output → Headphones: plays speech (evidence: `README.md`)
- Assistant orchestrator → Web server and API: starts interface (evidence: `aikoru/assistant.py`)
- Web server and API → Frame capture: serves camera frames (evidence: `aikoru/web.py`)
- Web server and API → Assistant orchestrator: routes commands and controls (evidence: `aikoru/web.py`)
- Web server and API → Web interface: serves interface assets (evidence: `README.md`)
- Browser → Web server and API: requests interface and API (evidence: `README.md`)
- Web interface → Browser: renders controls and events (evidence: `README.md`)
