# naman-dua/kora architecture

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

- Interactive diagram: https://gitdiagram.com/naman-dua/kora
- Repository: https://github.com/naman-dua/kora

## Overview

Kora is a local-first Windows assistant whose main interaction loop accepts text or speech, routes commands, and returns a UI or spoken response. Specialized workflows cover local-LLM conversation and memory, screen vision, reminders and briefings, document ingestion, web information, and OS actions/plugins. The excerpts show command dispatch, scheduling persistence, and document storage; several README capabilities have only tree-level evidence, so their internal wiring is not expanded. Optional network services are shown separately from local functionality.

Main entry points: [`kora_operator.py`](https://github.com/naman-dua/kora/blob/main/kora_operator.py) (Command Operator), [`main.py`](https://github.com/naman-dua/kora/blob/main/main.py) (Assistant Runtime), [`storage.py`](https://github.com/naman-dua/kora/blob/main/storage.py) (Memory Store), [`actions.py`](https://github.com/naman-dua/kora/blob/main/actions.py) (OS Actions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Assistant Interaction"]
  node_gui["Dashboard UI<br/>[gui.py]"]
  node_voice["Voice I/O<br/>[voice.py]"]
  node_main["Assistant Runtime<br/>[main.py]"]
  node_operator["Command Operator<br/>[kora_operator.py]"]
end

subgraph group_intelligence["Intelligence and Memory"]
  node_brain["Local LLM Brain<br/>[brain.py]"]
  node_memory["Memory Tools<br/>[memory_tools.py]"]
  node_nlp_memory["Fact Memory<br/>[nlp_memory.py]"]
  node_ingest["Document Ingestion<br/>[ingest_docs.py]"]
end

subgraph group_proactive["Vision and Scheduling"]
  node_screen["Screen Analysis<br/>[screen_analysis.py]"]
  node_live_eye["Live Eye<br/>[live_eye.py]"]
  node_tasks["Reminders and Tasks<br/>[tasks.py]"]
  node_briefing["Morning Briefing"]
end

subgraph group_capabilities["Tools and Integrations"]
  node_actions["OS Actions<br/>[actions.py]"]
  node_files["File Operations<br/>[file_ops.py]"]
  node_windows["Window Control<br/>[window_mgmt.py]"]
  node_media["Media Control<br/>[media_control.py]"]
  node_plugins["Plugin System<br/>[plugin_loader.py]"]
  node_search["Web Search<br/>[search_engine.py]"]
  node_weather["Weather<br/>[weather.py]"]
  node_news["News Feed<br/>[news_feed.py]"]
end

subgraph group_state["Persistent State"]
  node_store[("Memory Store<br/>[storage.py]")]
end

node_user(("User"))
node_ollama{{"Ollama"}}
node_web{{"Web Services"}}

node_user -->|"enters text"| node_gui
node_user -->|"speaks"| node_voice
node_gui -->|"submits text"| node_main
node_voice -->|"provides speech"| node_main
node_main -->|"speaks reply"| node_voice
node_main -->|"dispatches command"| node_operator
node_main -->|"checks tasks"| node_tasks
node_operator -->|"executes plan"| node_actions
node_operator -->|"runs search"| node_search
node_operator -->|"analyzes screen"| node_screen
node_operator -->|"handles task memory"| node_tasks
node_operator -->|"reads automations"| node_store
node_tasks -->|"persists schedule"| node_store
node_ingest -->|"stores chunks"| node_store
node_brain -->|"queries model"| node_ollama
node_memory -->|"reads and writes"| node_store
node_nlp_memory -->|"stores facts"| node_store
node_live_eye -.->|"monitors screen"| node_screen
node_actions -->|"uses file tools"| node_files
node_actions -->|"uses window tools"| node_windows
node_actions -->|"uses media tools"| node_media
node_plugins -.->|"loads plugins"| node_web
node_search -->|"queries web"| node_web
node_weather -->|"fetches forecast"| node_web
node_news -->|"fetches news"| node_web
node_briefing -->|"includes weather"| node_weather
node_briefing -->|"includes news"| node_news
node_briefing -->|"includes todos"| node_tasks

click node_gui "https://github.com/naman-dua/kora/blob/main/gui.py"
click node_voice "https://github.com/naman-dua/kora/blob/main/voice.py"
click node_main "https://github.com/naman-dua/kora/blob/main/main.py"
click node_operator "https://github.com/naman-dua/kora/blob/main/kora_operator.py"
click node_brain "https://github.com/naman-dua/kora/blob/main/brain.py"
click node_memory "https://github.com/naman-dua/kora/blob/main/memory_tools.py"
click node_nlp_memory "https://github.com/naman-dua/kora/blob/main/nlp_memory.py"
click node_ingest "https://github.com/naman-dua/kora/blob/main/ingest_docs.py"
click node_screen "https://github.com/naman-dua/kora/blob/main/screen_analysis.py"
click node_live_eye "https://github.com/naman-dua/kora/blob/main/live_eye.py"
click node_tasks "https://github.com/naman-dua/kora/blob/main/tasks.py"
click node_briefing "https://github.com/naman-dua/kora/blob/main/morning_briefing.py"
click node_actions "https://github.com/naman-dua/kora/blob/main/actions.py"
click node_files "https://github.com/naman-dua/kora/blob/main/file_ops.py"
click node_windows "https://github.com/naman-dua/kora/blob/main/window_mgmt.py"
click node_media "https://github.com/naman-dua/kora/blob/main/media_control.py"
click node_plugins "https://github.com/naman-dua/kora/blob/main/plugin_loader.py"
click node_search "https://github.com/naman-dua/kora/blob/main/search_engine.py"
click node_weather "https://github.com/naman-dua/kora/blob/main/weather.py"
click node_news "https://github.com/naman-dua/kora/blob/main/news_feed.py"
click node_store "https://github.com/naman-dua/kora/blob/main/storage.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_gui,node_voice,node_main,node_operator,node_user toneBlue
class node_brain,node_memory,node_nlp_memory,node_ingest toneAmber
class node_screen,node_live_eye,node_tasks,node_briefing toneMint
class node_actions,node_files,node_windows,node_media,node_plugins,node_search,node_weather,node_news toneRose
class node_store,node_ollama,node_web toneIndigo
```

## Components

### Assistant Interaction

- [Dashboard UI](https://github.com/naman-dua/kora/blob/main/gui.py): `gui.py`
- [Voice I/O](https://github.com/naman-dua/kora/blob/main/voice.py): `voice.py`
- [Assistant Runtime](https://github.com/naman-dua/kora/blob/main/main.py): `main.py`
- [Command Operator](https://github.com/naman-dua/kora/blob/main/kora_operator.py): `kora_operator.py`

### Intelligence and Memory

- [Local LLM Brain](https://github.com/naman-dua/kora/blob/main/brain.py): `brain.py`
- [Memory Tools](https://github.com/naman-dua/kora/blob/main/memory_tools.py): `memory_tools.py`
- [Fact Memory](https://github.com/naman-dua/kora/blob/main/nlp_memory.py): `nlp_memory.py`
- [Document Ingestion](https://github.com/naman-dua/kora/blob/main/ingest_docs.py): `ingest_docs.py`

### Vision and Scheduling

- [Screen Analysis](https://github.com/naman-dua/kora/blob/main/screen_analysis.py): `screen_analysis.py`
- [Live Eye](https://github.com/naman-dua/kora/blob/main/live_eye.py): `live_eye.py`
- [Reminders and Tasks](https://github.com/naman-dua/kora/blob/main/tasks.py): `tasks.py`
- [Morning Briefing](https://github.com/naman-dua/kora/blob/main/morning_briefing.py): `morning_briefing.py`

### Tools and Integrations

- [OS Actions](https://github.com/naman-dua/kora/blob/main/actions.py): `actions.py`
- [File Operations](https://github.com/naman-dua/kora/blob/main/file_ops.py): `file_ops.py`
- [Window Control](https://github.com/naman-dua/kora/blob/main/window_mgmt.py): `window_mgmt.py`
- [Media Control](https://github.com/naman-dua/kora/blob/main/media_control.py): `media_control.py`
- [Plugin System](https://github.com/naman-dua/kora/blob/main/plugin_loader.py): `plugin_loader.py`
- [Web Search](https://github.com/naman-dua/kora/blob/main/search_engine.py): `search_engine.py`
- [Weather](https://github.com/naman-dua/kora/blob/main/weather.py): `weather.py`
- [News Feed](https://github.com/naman-dua/kora/blob/main/news_feed.py): `news_feed.py`

### Persistent State

- [Memory Store](https://github.com/naman-dua/kora/blob/main/storage.py): `storage.py`

### Other components

- **User**
- **Ollama**
- **Web Services**

## Connections

- User → Dashboard UI: enters text
- User → Voice I/O: speaks
- Dashboard UI → Assistant Runtime: submits text
- Voice I/O → Assistant Runtime: provides speech
- Assistant Runtime → Voice I/O: speaks reply
- Assistant Runtime → Command Operator: dispatches command
- Assistant Runtime → Reminders and Tasks: checks tasks
- Command Operator → OS Actions: executes plan
- Command Operator → Web Search: runs search
- Command Operator → Screen Analysis: analyzes screen
- Command Operator → Reminders and Tasks: handles task memory
- Command Operator → Memory Store: reads automations
- Reminders and Tasks → Memory Store: persists schedule
- Document Ingestion → Memory Store: stores chunks
- Local LLM Brain → Ollama: queries model
- Memory Tools → Memory Store: reads and writes
- Fact Memory → Memory Store: stores facts
- Live Eye → Screen Analysis: monitors screen
- OS Actions → File Operations: uses file tools
- OS Actions → Window Control: uses window tools
- OS Actions → Media Control: uses media tools
- Plugin System → Web Services: loads plugins
- Web Search → Web Services: queries web
- Weather → Web Services: fetches forecast
- News Feed → Web Services: fetches news
- Morning Briefing → Weather: includes weather
- Morning Briefing → News Feed: includes news
- Morning Briefing → Reminders and Tasks: includes todos