# pranav-sketch-cc/kayal1 architecture

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

- Interactive diagram: https://gitdiagram.com/pranav-sketch-cc/kayal1
- Repository: https://github.com/pranav-sketch-cc/kayal1

## Overview

Mark LVII is a desktop voice assistant with a graphical HUD. The main workflow runs from user input through the application runtime and model/tool handling to an action or spoken response. Its broader product includes configurable model and speech providers, persistent memory, background tasks and scheduled routines, plus desktop controls and web research. The source index and excerpts support the main runtime and several subsystem relationships; unsampled capabilities are represented as components where the tree supports them, without guessing their call paths.

Main entry points: [`Mark-LVII-main/main.py`](https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/main.py) (App runtime), [`Mark-LVII-main/core/tasks/engine.py`](https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/core/tasks/engine.py) (Task scheduler), [`Mark-LVII-main/gui/window.py`](https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/gui/window.py) (Assistant window), [`Mark-LVII-main/core/tasks/brain.py`](https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/core/tasks/brain.py) (Task brain)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Assistant runtime"]
  node_app["App runtime<br/>[main.py]"]
  node_action_loader["Action loader<br/>[action_loader.py]"]
end

subgraph group_conversation["Conversation and tools"]
  node_brain["Task brain<br/>[brain.py]"]
  node_gemini["Gemini calls<br/>[gemini.py]"]
  node_web_search["Web search<br/>[web_search.py]"]
  node_outcome["Tool outcomes<br/>[outcome.py]"]
end

subgraph group_automation["Tasks and routines"]
  node_task_engine["Task scheduler<br/>[engine.py]"]
  node_task_store[("Task store<br/>[store.py]")]
  node_research["Task research<br/>[research.py]"]
  node_routine_engine["Routine scheduler<br/>[engine.py]"]
  node_routine_rules["Routine rules<br/>[rules.py]"]
end

subgraph group_platform["Providers and state"]
  node_provider_pipeline["Speech pipeline<br/>[engine_pipeline.py]"]
  node_provider_registry["Provider registry<br/>[registry.py]"]
  node_openai_provider["OpenAI-compatible<br/>[llm_openai.py]"]
  node_config[("Configuration<br/>[config_manager.py]")]
  node_memory[("Assistant memory<br/>[memory_manager.py]")]
end

subgraph group_interface["Desktop interface"]
  node_ui["UI entry<br/>[ui.py]"]
  node_window["Assistant window<br/>[window.py]"]
  node_overlays["HUD overlays<br/>[overlays.py]"]
  node_dashboard["Dashboard server<br/>[server.py]"]
end

node_user(("User"))
node_external_model{{"Model service"}}
node_desktop{{"Desktop and apps"}}

node_user -->|"initiates"| node_app
node_app -->|"loads actions"| node_action_loader
node_app -->|"starts UI"| node_ui
node_ui -->|"builds window"| node_window
node_ui -->|"uses overlays"| node_overlays
node_window -->|"opens panels"| node_overlays
node_window -->|"uses tasks"| node_task_engine
node_window -->|"uses routines"| node_routine_engine
node_window -->|"uses calls"| node_gemini
node_brain -->|"calls model"| node_gemini
node_brain -->|"loads tools"| node_action_loader
node_brain -->|"selects provider"| node_provider_registry
node_task_engine -->|"runs rounds"| node_brain
node_task_engine -->|"persists tasks"| node_task_store
node_task_engine -->|"uses research"| node_research
node_routine_engine -->|"checks triggers"| node_routine_rules
node_web_search -->|"fallback search"| node_gemini
node_web_search -->|"formats result"| node_outcome
node_provider_registry -->|"builds provider"| node_openai_provider
node_provider_pipeline -->|"selects providers"| node_provider_registry
node_provider_pipeline -.->|"sends requests"| node_external_model
node_gemini -->|"reads key"| node_config
node_brain -->|"reads settings"| node_config
node_task_engine -->|"uses memory"| node_memory
node_app -->|"uses memory"| node_memory
node_app -.->|"starts service"| node_dashboard
node_action_loader -.->|"dispatches actions"| node_desktop

click node_app "https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/main.py"
click node_action_loader "https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/core/action_loader.py"
click node_brain "https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/core/tasks/brain.py"
click node_gemini "https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/core/gemini.py"
click node_web_search "https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/actions/web_search.py"
click node_outcome "https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/core/outcome.py"
click node_task_engine "https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/core/tasks/engine.py"
click node_task_store "https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/core/tasks/store.py"
click node_research "https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/core/tasks/research.py"
click node_routine_engine "https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/core/routines/engine.py"
click node_routine_rules "https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/core/routines/rules.py"
click node_provider_pipeline "https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/providers/engine_pipeline.py"
click node_provider_registry "https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/providers/registry.py"
click node_openai_provider "https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/providers/llm_openai.py"
click node_config "https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/memory/config_manager.py"
click node_memory "https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/memory/memory_manager.py"
click node_ui "https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/ui.py"
click node_window "https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/gui/window.py"
click node_overlays "https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/gui/overlays.py"
click node_dashboard "https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/dashboard/server.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_app,node_action_loader,node_user toneBlue
class node_brain,node_gemini,node_web_search,node_outcome toneAmber
class node_task_engine,node_task_store,node_research,node_routine_engine,node_routine_rules toneMint
class node_provider_pipeline,node_provider_registry,node_openai_provider,node_config,node_memory toneRose
class node_ui,node_window,node_overlays,node_dashboard,node_external_model,node_desktop toneIndigo
```

## Components

### Assistant runtime

- [App runtime](https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/main.py): `Mark-LVII-main/main.py`
- [Action loader](https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/core/action_loader.py): `Mark-LVII-main/core/action_loader.py`

### Conversation and tools

- [Task brain](https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/core/tasks/brain.py): `Mark-LVII-main/core/tasks/brain.py`
- [Gemini calls](https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/core/gemini.py): `Mark-LVII-main/core/gemini.py`
- [Web search](https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/actions/web_search.py): `Mark-LVII-main/actions/web_search.py`
- [Tool outcomes](https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/core/outcome.py): `Mark-LVII-main/core/outcome.py`

### Tasks and routines

- [Task scheduler](https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/core/tasks/engine.py): `Mark-LVII-main/core/tasks/engine.py`
- [Task store](https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/core/tasks/store.py): `Mark-LVII-main/core/tasks/store.py`
- [Task research](https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/core/tasks/research.py): `Mark-LVII-main/core/tasks/research.py`
- [Routine scheduler](https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/core/routines/engine.py): `Mark-LVII-main/core/routines/engine.py`
- [Routine rules](https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/core/routines/rules.py): `Mark-LVII-main/core/routines/rules.py`

### Providers and state

- [Speech pipeline](https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/providers/engine_pipeline.py): `Mark-LVII-main/providers/engine_pipeline.py`
- [Provider registry](https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/providers/registry.py): `Mark-LVII-main/providers/registry.py`
- [OpenAI-compatible](https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/providers/llm_openai.py): `Mark-LVII-main/providers/llm_openai.py`
- [Configuration](https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/memory/config_manager.py): `Mark-LVII-main/memory/config_manager.py`
- [Assistant memory](https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/memory/memory_manager.py): `Mark-LVII-main/memory/memory_manager.py`

### Desktop interface

- [UI entry](https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/ui.py): `Mark-LVII-main/ui.py`
- [Assistant window](https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/gui/window.py): `Mark-LVII-main/gui/window.py`
- [HUD overlays](https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/gui/overlays.py): `Mark-LVII-main/gui/overlays.py`
- [Dashboard server](https://github.com/pranav-sketch-cc/kayal1/blob/main/Mark-LVII-main/dashboard/server.py): `Mark-LVII-main/dashboard/server.py`

### Other components

- **User**
- **Model service**
- **Desktop and apps**

## Connections

- User → App runtime: initiates (evidence: `Mark-LVII-main/main.py`)
- App runtime → Action loader: loads actions (evidence: `Mark-LVII-main/main.py`)
- App runtime → UI entry: starts UI (evidence: `Mark-LVII-main/main.py`)
- UI entry → Assistant window: builds window (evidence: `Mark-LVII-main/ui.py`)
- UI entry → HUD overlays: uses overlays (evidence: `Mark-LVII-main/ui.py`)
- Assistant window → HUD overlays: opens panels (evidence: `Mark-LVII-main/gui/window.py`)
- Assistant window → Task scheduler: uses tasks (evidence: `Mark-LVII-main/gui/window.py`)
- Assistant window → Routine scheduler: uses routines (evidence: `Mark-LVII-main/gui/window.py`)
- Assistant window → Gemini calls: uses calls (evidence: `Mark-LVII-main/gui/window.py`)
- Task brain → Gemini calls: calls model (evidence: `Mark-LVII-main/core/tasks/brain.py`)
- Task brain → Action loader: loads tools (evidence: `Mark-LVII-main/core/tasks/brain.py`)
- Task brain → Provider registry: selects provider (evidence: `Mark-LVII-main/core/tasks/brain.py`)
- Task scheduler → Task brain: runs rounds (evidence: `Mark-LVII-main/core/tasks/engine.py`)
- Task scheduler → Task store: persists tasks (evidence: `Mark-LVII-main/core/tasks/engine.py`)
- Task scheduler → Task research: uses research (evidence: `Mark-LVII-main/core/tasks/engine.py`)
- Routine scheduler → Routine rules: checks triggers (evidence: `Mark-LVII-main/core/routines/engine.py`)
- Web search → Gemini calls: fallback search (evidence: `Mark-LVII-main/actions/web_search.py`)
- Web search → Tool outcomes: formats result (evidence: `Mark-LVII-main/actions/web_search.py`)
- Provider registry → OpenAI-compatible: builds provider (evidence: `Mark-LVII-main/providers/registry.py`)
- Speech pipeline → Provider registry: selects providers (evidence: `Mark-LVII-main/providers/engine_pipeline.py`)
- Speech pipeline → Model service: sends requests
- Gemini calls → Configuration: reads key (evidence: `Mark-LVII-main/core/gemini.py`)
- Task brain → Configuration: reads settings (evidence: `Mark-LVII-main/core/tasks/brain.py`)
- Task scheduler → Assistant memory: uses memory (evidence: `Mark-LVII-main/core/tasks/engine.py`)
- App runtime → Assistant memory: uses memory (evidence: `Mark-LVII-main/main.py`)
- App runtime → Dashboard server: starts service (evidence: `Mark-LVII-main/main.py`)
- Action loader → Desktop and apps: dispatches actions
