# fatihmakes/mark-lvii architecture

> Architecture diagram of the GitHub repository fatihmakes/mark-lvii, 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/fatihmakes/mark-lvii
- Repository: https://github.com/fatihmakes/mark-lvii

## Overview

Mark LVII is a cross-platform voice assistant whose main workflow is a user request entering the conversation runtime, being handled through discovered tools or long-running tasks, and returning as speech or a HUD update. Separate branches provide persistent background research and configurable routines. The graph also preserves the alternate STT/LLM/TTS engine, provider settings, memory, and the command-center UI. Unsampled capabilities are included only where README or source-index evidence supports them; some internal wiring is therefore omitted.

Main entry points: [`main.py`](https://github.com/fatihmakes/mark-lvii/blob/main/main.py) (Assistant Runtime), [`gui/window.py`](https://github.com/fatihmakes/mark-lvii/blob/main/gui/window.py) (Assistant Window), [`core/tasks/engine.py`](https://github.com/fatihmakes/mark-lvii/blob/main/core/tasks/engine.py) (Task Scheduler), [`core/tasks/brain.py`](https://github.com/fatihmakes/mark-lvii/blob/main/core/tasks/brain.py) (Task Planning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Conversation Runtime"]
  node_main["Assistant Runtime<br/>[main.py]"]
  node_live["Gemini Live<br/>[gemini.py]"]
end

subgraph group_work["Tasks and Routines"]
  node_taskentry["Task Commands"]
  node_taskdesktop["Task Host<br/>[desktop.py]"]
  node_taskengine["Task Scheduler<br/>[engine.py]"]
  node_taskbrain["Task Planning<br/>[brain.py]"]
  node_research["Deep Research<br/>[research.py]"]
  node_taskstore[("Task Checkpoints<br/>[store.py]")]
  node_routineui["Routine Commands<br/>[desktop.py]"]
  node_routineengine["Routine Scheduler<br/>[engine.py]"]
  node_rulerules["Routine Rules<br/>[rules.py]"]
end

subgraph group_skills["Actions and Memory"]
  node_loader["Action Discovery<br/>[action_loader.py]"]
  node_actions["Bundled Actions"]
  node_websearch["Web Search<br/>[web_search.py]"]
  node_outcome["Verified Outcomes<br/>[outcome.py]"]
  node_memory[("Recallable Memory<br/>[memory_manager.py]")]
end

subgraph group_engines["Speech Engines"]
  node_pipeline["Speech Pipeline<br/>[engine_pipeline.py]"]
  node_registry["Provider Registry<br/>[registry.py]"]
  node_llm["Compatible LLM<br/>[llm_openai.py]"]
  node_speech["Speech Providers"]
end

subgraph group_interface["HUD and Settings"]
  node_config[("Assistant Settings<br/>[config_manager.py]")]
  node_providerpanel["Engine Settings<br/>[providers_panel.py]"]
  node_window["Assistant Window<br/>[window.py]"]
  node_hud["Command-Center HUD<br/>[hud.py]"]
  node_overlays["HUD Panels<br/>[overlays.py]"]
  node_dashboard["Remote Dashboard<br/>[server.py]"]
end

node_user(("User"))

node_user -->|"speaks to"| node_main
node_main -->|"runs conversation"| node_live
node_main -->|"loads actions"| node_loader
node_loader -.->|"discovers skills"| node_actions
node_main -->|"dispatches commands"| node_taskentry
node_taskentry -->|"requests task"| node_taskdesktop
node_taskdesktop -->|"schedules work"| node_taskengine
node_taskengine -->|"plans rounds"| node_taskbrain
node_taskengine -->|"runs research"| node_research
node_taskengine -->|"checkpoints state"| node_taskstore
node_research -->|"requests planning"| node_taskbrain
node_research -->|"persists progress"| node_taskstore
node_taskbrain -->|"gets tool definitions"| node_loader
node_taskbrain -->|"uses model calls"| node_live
node_taskentry -->|"formats status"| node_outcome
node_main -->|"sets up routines"| node_routineui
node_routineui -->|"manages schedules"| node_routineengine
node_routineengine -->|"evaluates triggers"| node_rulerules
node_routineengine -.->|"starts tasks"| node_taskstore
node_main -->|"uses memory"| node_memory
node_websearch -->|"uses search fallback"| node_live
node_main -->|"reads settings"| node_config
node_window -->|"starts assistant"| node_main
node_window -->|"presents HUD"| node_hud
node_window -->|"opens panels"| node_overlays
node_window -->|"opens engine settings"| node_providerpanel
node_window -->|"configures routines"| node_routineui
node_window -->|"shows task controls"| node_taskdesktop
node_overlays -->|"shows stored facts"| node_memory
node_overlays -->|"connects remote panel"| node_dashboard
node_providerpanel -->|"lists providers"| node_registry
node_main -->|"selects alternate engine"| node_pipeline
node_pipeline -->|"creates providers"| node_registry
node_registry -->|"loads compatible model"| node_llm
node_pipeline -->|"uses speech components"| node_speech
node_providerpanel -->|"saves engine choices"| node_config

click node_main "https://github.com/fatihmakes/mark-lvii/blob/main/main.py"
click node_live "https://github.com/fatihmakes/mark-lvii/blob/main/core/gemini.py"
click node_loader "https://github.com/fatihmakes/mark-lvii/blob/main/core/action_loader.py"
click node_actions "https://github.com/fatihmakes/mark-lvii/tree/main/actions"
click node_websearch "https://github.com/fatihmakes/mark-lvii/blob/main/actions/web_search.py"
click node_outcome "https://github.com/fatihmakes/mark-lvii/blob/main/core/outcome.py"
click node_memory "https://github.com/fatihmakes/mark-lvii/blob/main/memory/memory_manager.py"
click node_config "https://github.com/fatihmakes/mark-lvii/blob/main/memory/config_manager.py"
click node_taskentry "https://github.com/fatihmakes/mark-lvii/blob/main/actions/background_tasks.py"
click node_taskdesktop "https://github.com/fatihmakes/mark-lvii/blob/main/core/tasks/desktop.py"
click node_taskengine "https://github.com/fatihmakes/mark-lvii/blob/main/core/tasks/engine.py"
click node_taskbrain "https://github.com/fatihmakes/mark-lvii/blob/main/core/tasks/brain.py"
click node_research "https://github.com/fatihmakes/mark-lvii/blob/main/core/tasks/research.py"
click node_taskstore "https://github.com/fatihmakes/mark-lvii/blob/main/core/tasks/store.py"
click node_routineui "https://github.com/fatihmakes/mark-lvii/blob/main/core/routines/desktop.py"
click node_routineengine "https://github.com/fatihmakes/mark-lvii/blob/main/core/routines/engine.py"
click node_rulerules "https://github.com/fatihmakes/mark-lvii/blob/main/core/routines/rules.py"
click node_providerpanel "https://github.com/fatihmakes/mark-lvii/blob/main/gui/providers_panel.py"
click node_pipeline "https://github.com/fatihmakes/mark-lvii/blob/main/providers/engine_pipeline.py"
click node_registry "https://github.com/fatihmakes/mark-lvii/blob/main/providers/registry.py"
click node_llm "https://github.com/fatihmakes/mark-lvii/blob/main/providers/llm_openai.py"
click node_speech "https://github.com/fatihmakes/mark-lvii/tree/main/providers"
click node_window "https://github.com/fatihmakes/mark-lvii/blob/main/gui/window.py"
click node_hud "https://github.com/fatihmakes/mark-lvii/blob/main/gui/hud.py"
click node_overlays "https://github.com/fatihmakes/mark-lvii/blob/main/gui/overlays.py"
click node_dashboard "https://github.com/fatihmakes/mark-lvii/blob/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_main,node_live,node_user toneBlue
class node_taskentry,node_taskdesktop,node_taskengine,node_taskbrain,node_research,node_taskstore,node_routineui,node_routineengine,node_rulerules toneAmber
class node_loader,node_actions,node_websearch,node_outcome,node_memory toneMint
class node_pipeline,node_registry,node_llm,node_speech toneRose
class node_config,node_providerpanel,node_window,node_hud,node_overlays,node_dashboard toneIndigo
```

## Components

### Conversation Runtime

- [Assistant Runtime](https://github.com/fatihmakes/mark-lvii/blob/main/main.py): `main.py`
- [Gemini Live](https://github.com/fatihmakes/mark-lvii/blob/main/core/gemini.py): `core/gemini.py`

### Tasks and Routines

- [Task Commands](https://github.com/fatihmakes/mark-lvii/blob/main/actions/background_tasks.py): `actions/background_tasks.py`
- [Task Host](https://github.com/fatihmakes/mark-lvii/blob/main/core/tasks/desktop.py): `core/tasks/desktop.py`
- [Task Scheduler](https://github.com/fatihmakes/mark-lvii/blob/main/core/tasks/engine.py): `core/tasks/engine.py`
- [Task Planning](https://github.com/fatihmakes/mark-lvii/blob/main/core/tasks/brain.py): `core/tasks/brain.py`
- [Deep Research](https://github.com/fatihmakes/mark-lvii/blob/main/core/tasks/research.py): `core/tasks/research.py`
- [Task Checkpoints](https://github.com/fatihmakes/mark-lvii/blob/main/core/tasks/store.py): `core/tasks/store.py`
- [Routine Commands](https://github.com/fatihmakes/mark-lvii/blob/main/core/routines/desktop.py): `core/routines/desktop.py`
- [Routine Scheduler](https://github.com/fatihmakes/mark-lvii/blob/main/core/routines/engine.py): `core/routines/engine.py`
- [Routine Rules](https://github.com/fatihmakes/mark-lvii/blob/main/core/routines/rules.py): `core/routines/rules.py`

### Actions and Memory

- [Action Discovery](https://github.com/fatihmakes/mark-lvii/blob/main/core/action_loader.py): `core/action_loader.py`
- [Bundled Actions](https://github.com/fatihmakes/mark-lvii/tree/main/actions): `actions`
- [Web Search](https://github.com/fatihmakes/mark-lvii/blob/main/actions/web_search.py): `actions/web_search.py`
- [Verified Outcomes](https://github.com/fatihmakes/mark-lvii/blob/main/core/outcome.py): `core/outcome.py`
- [Recallable Memory](https://github.com/fatihmakes/mark-lvii/blob/main/memory/memory_manager.py): `memory/memory_manager.py`

### Speech Engines

- [Speech Pipeline](https://github.com/fatihmakes/mark-lvii/blob/main/providers/engine_pipeline.py): `providers/engine_pipeline.py`
- [Provider Registry](https://github.com/fatihmakes/mark-lvii/blob/main/providers/registry.py): `providers/registry.py`
- [Compatible LLM](https://github.com/fatihmakes/mark-lvii/blob/main/providers/llm_openai.py): `providers/llm_openai.py`
- [Speech Providers](https://github.com/fatihmakes/mark-lvii/tree/main/providers): `providers`

### HUD and Settings

- [Assistant Settings](https://github.com/fatihmakes/mark-lvii/blob/main/memory/config_manager.py): `memory/config_manager.py`
- [Engine Settings](https://github.com/fatihmakes/mark-lvii/blob/main/gui/providers_panel.py): `gui/providers_panel.py`
- [Assistant Window](https://github.com/fatihmakes/mark-lvii/blob/main/gui/window.py): `gui/window.py`
- [Command-Center HUD](https://github.com/fatihmakes/mark-lvii/blob/main/gui/hud.py): `gui/hud.py`
- [HUD Panels](https://github.com/fatihmakes/mark-lvii/blob/main/gui/overlays.py): `gui/overlays.py`
- [Remote Dashboard](https://github.com/fatihmakes/mark-lvii/blob/main/dashboard/server.py): `dashboard/server.py`

### Other components

- **User**

## Connections

- User → Assistant Runtime: speaks to
- Assistant Runtime → Gemini Live: runs conversation (evidence: `main.py`)
- Assistant Runtime → Action Discovery: loads actions (evidence: `main.py`)
- Action Discovery → Bundled Actions: discovers skills
- Assistant Runtime → Task Commands: dispatches commands (evidence: `main.py`)
- Task Commands → Task Host: requests task (evidence: `actions/background_tasks.py`)
- Task Host → Task Scheduler: schedules work (evidence: `core/tasks/desktop.py`)
- Task Scheduler → Task Planning: plans rounds (evidence: `core/tasks/engine.py`)
- Task Scheduler → Deep Research: runs research (evidence: `core/tasks/engine.py`)
- Task Scheduler → Task Checkpoints: checkpoints state (evidence: `core/tasks/engine.py`)
- Deep Research → Task Planning: requests planning (evidence: `core/tasks/research.py`)
- Deep Research → Task Checkpoints: persists progress (evidence: `core/tasks/research.py`)
- Task Planning → Action Discovery: gets tool definitions (evidence: `core/tasks/brain.py`)
- Task Planning → Gemini Live: uses model calls (evidence: `core/tasks/brain.py`)
- Task Commands → Verified Outcomes: formats status (evidence: `actions/background_tasks.py`)
- Assistant Runtime → Routine Commands: sets up routines (evidence: `main.py`)
- Routine Commands → Routine Scheduler: manages schedules (evidence: `core/routines/desktop.py`)
- Routine Scheduler → Routine Rules: evaluates triggers (evidence: `core/routines/engine.py`)
- Routine Scheduler → Task Checkpoints: starts tasks (evidence: `core/routines/engine.py`)
- Assistant Runtime → Recallable Memory: uses memory (evidence: `main.py`)
- Web Search → Gemini Live: uses search fallback (evidence: `actions/web_search.py`)
- Assistant Runtime → Assistant Settings: reads settings (evidence: `main.py`)
- Assistant Window → Assistant Runtime: starts assistant (evidence: `gui/window.py`)
- Assistant Window → Command-Center HUD: presents HUD (evidence: `gui/window.py`)
- Assistant Window → HUD Panels: opens panels (evidence: `gui/window.py`)
- Assistant Window → Engine Settings: opens engine settings (evidence: `gui/window.py`)
- Assistant Window → Routine Commands: configures routines (evidence: `gui/window.py`)
- Assistant Window → Task Host: shows task controls (evidence: `gui/window.py`)
- HUD Panels → Recallable Memory: shows stored facts (evidence: `gui/overlays.py`)
- HUD Panels → Remote Dashboard: connects remote panel (evidence: `gui/overlays.py`)
- Engine Settings → Provider Registry: lists providers (evidence: `gui/providers_panel.py`)
- Assistant Runtime → Speech Pipeline: selects alternate engine (evidence: `main.py`)
- Speech Pipeline → Provider Registry: creates providers (evidence: `providers/engine_pipeline.py`)
- Provider Registry → Compatible LLM: loads compatible model (evidence: `providers/registry.py`)
- Speech Pipeline → Speech Providers: uses speech components (evidence: `providers/engine_pipeline.py`)
- Engine Settings → Assistant Settings: saves engine choices (evidence: `gui/providers_panel.py`)