# fatihmakes/mark-lv architecture

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

- Interactive diagram: https://gitdiagram.com/fatihmakes/mark-lv
- Repository: https://github.com/fatihmakes/mark-lv

## Overview

Mark LV is a cross-platform voice-first personal AI assistant that can perceive the screen, speak, control the computer, and expose a phone dashboard. The principal workflow runs from user input through the live assistant in main.py, which coordinates audio, vision, memory, and dynamically loaded skills; results appear in the HUD or are spoken back. The graph preserves the documented capability branches. Several action modules and runtime integrations were not excerpted, so their internal links are omitted where the evidence does not establish them.

Main entry points: [`main.py`](https://github.com/fatihmakes/mark-lv/blob/main/main.py) (Live assistant), [`core/action_loader.py`](https://github.com/fatihmakes/mark-lv/blob/main/core/action_loader.py) (Skill discovery), [`actions`](https://github.com/fatihmakes/mark-lv/tree/main/actions) (Computer and desktop control), [`ui.py`](https://github.com/fatihmakes/mark-lv/blob/main/ui.py) (HUD and controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["HUD and audio"]
  node_ui["HUD and controls<br/>[ui.py]"]
  node_avatar["Holographic avatar<br/>[avatar.py]"]
  node_mesh["Face geometry<br/>[avatar_mesh.py]"]
  node_audio["Audio devices<br/>[audio_devices.py]"]
  node_wake["Wake word<br/>[wake_word.py]"]
  node_hotkey["Push to talk<br/>[hotkey.py]"]
  node_echo["Echo guard<br/>[echo.py]"]
  node_viseme["Lip sync<br/>[viseme.py]"]
  node_dashboard["Remote dashboard<br/>[server.py]"]
end

subgraph group_runtime["Assistant runtime"]
  node_main["Live assistant<br/>[main.py]"]
  node_gemini["Gemini live and ladder<br/>[gemini.py]"]
  node_llm["One-shot model client<br/>[llm_client.py]"]
  node_stt["Speech recognition<br/>[stt.py]"]
  node_tts["Speech synthesis<br/>[tts.py]"]
end

subgraph group_skills["Skills and tasks"]
  node_actions["Skill discovery<br/>[action_loader.py]"]
  node_web["Web search<br/>[web_search.py]"]
  node_computer["Computer and desktop control"]
  node_files["File operations"]
  node_media["Video playback"]
  node_tasks["Proactive tasks"]
  node_plugins["Plugin discovery<br/>[plugin_loader.py]"]
  node_monitor["System monitoring<br/>[system_monitor.py]"]
end

subgraph group_state["Memory and access"]
  node_memory[("Persistent memory<br/>[memory_manager.py]")]
  node_config[("Assistant configuration<br/>[config_manager.py]")]
  node_undo["Undo history<br/>[undo.py]"]
  node_confirm["Action confirmation<br/>[confirm.py]"]
end

node_user(("User"))

node_user -->|"speaks or requests"| node_main
node_main -->|"updates display"| node_ui
node_main -.->|"runs live session"| node_gemini
node_main -->|"configures devices"| node_audio
node_main -->|"loads context"| node_memory
node_main -->|"reads settings"| node_config
node_main -->|"loads skills"| node_actions
node_main -->|"loads plugins"| node_plugins
node_ui -->|"shows face"| node_avatar
node_avatar -->|"uses geometry"| node_mesh
node_main -->|"gates listening"| node_wake
node_main -->|"handles hotkey"| node_hotkey
node_main -->|"filters self-echo"| node_echo
node_main -->|"drives mouth"| node_viseme
node_main -.->|"transcribes audio"| node_stt
node_main -.->|"speaks replies"| node_tts
node_actions -.->|"discovers skill"| node_web
node_actions -.->|"discovers skills"| node_computer
node_actions -.->|"discovers skill"| node_files
node_actions -.->|"discovers skill"| node_media
node_main -->|"runs search"| node_web
node_main -->|"runs monitoring"| node_monitor
node_main -->|"runs proactive tasks"| node_tasks
node_computer -->|"requests confirmation"| node_confirm
node_computer -->|"records reversible changes"| node_undo
node_files -->|"records file changes"| node_undo
node_plugins -->|"reads configuration"| node_config
node_user -->|"pairs phone"| node_dashboard
node_dashboard -.->|"submits commands"| node_main

click node_main "https://github.com/fatihmakes/mark-lv/blob/main/main.py"
click node_ui "https://github.com/fatihmakes/mark-lv/blob/main/ui.py"
click node_avatar "https://github.com/fatihmakes/mark-lv/blob/main/core/avatar.py"
click node_mesh "https://github.com/fatihmakes/mark-lv/blob/main/core/avatar_mesh.py"
click node_audio "https://github.com/fatihmakes/mark-lv/blob/main/core/audio_devices.py"
click node_wake "https://github.com/fatihmakes/mark-lv/blob/main/core/wake_word.py"
click node_hotkey "https://github.com/fatihmakes/mark-lv/blob/main/core/hotkey.py"
click node_echo "https://github.com/fatihmakes/mark-lv/blob/main/core/echo.py"
click node_viseme "https://github.com/fatihmakes/mark-lv/blob/main/core/viseme.py"
click node_gemini "https://github.com/fatihmakes/mark-lv/blob/main/core/gemini.py"
click node_llm "https://github.com/fatihmakes/mark-lv/blob/main/core/llm_client.py"
click node_stt "https://github.com/fatihmakes/mark-lv/blob/main/core/stt.py"
click node_tts "https://github.com/fatihmakes/mark-lv/blob/main/core/tts.py"
click node_actions "https://github.com/fatihmakes/mark-lv/blob/main/core/action_loader.py"
click node_web "https://github.com/fatihmakes/mark-lv/blob/main/actions/web_search.py"
click node_computer "https://github.com/fatihmakes/mark-lv/tree/main/actions"
click node_files "https://github.com/fatihmakes/mark-lv/tree/main/actions"
click node_media "https://github.com/fatihmakes/mark-lv/tree/main/actions"
click node_tasks "https://github.com/fatihmakes/mark-lv/tree/main/actions"
click node_memory "https://github.com/fatihmakes/mark-lv/blob/main/memory/memory_manager.py"
click node_config "https://github.com/fatihmakes/mark-lv/blob/main/memory/config_manager.py"
click node_undo "https://github.com/fatihmakes/mark-lv/blob/main/core/undo.py"
click node_confirm "https://github.com/fatihmakes/mark-lv/blob/main/core/confirm.py"
click node_plugins "https://github.com/fatihmakes/mark-lv/blob/main/core/plugin_loader.py"
click node_dashboard "https://github.com/fatihmakes/mark-lv/blob/main/dashboard/server.py"
click node_monitor "https://github.com/fatihmakes/mark-lv/blob/main/actions/system_monitor.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_ui,node_avatar,node_mesh,node_audio,node_wake,node_hotkey,node_echo,node_viseme,node_dashboard,node_user toneBlue
class node_main,node_gemini,node_llm,node_stt,node_tts toneAmber
class node_actions,node_web,node_computer,node_files,node_media,node_tasks,node_plugins,node_monitor toneMint
class node_memory,node_config,node_undo,node_confirm toneRose
```

## Components

### HUD and audio

- [HUD and controls](https://github.com/fatihmakes/mark-lv/blob/main/ui.py): `ui.py`
- [Holographic avatar](https://github.com/fatihmakes/mark-lv/blob/main/core/avatar.py): `core/avatar.py`
- [Face geometry](https://github.com/fatihmakes/mark-lv/blob/main/core/avatar_mesh.py): `core/avatar_mesh.py`
- [Audio devices](https://github.com/fatihmakes/mark-lv/blob/main/core/audio_devices.py): `core/audio_devices.py`
- [Wake word](https://github.com/fatihmakes/mark-lv/blob/main/core/wake_word.py): `core/wake_word.py`
- [Push to talk](https://github.com/fatihmakes/mark-lv/blob/main/core/hotkey.py): `core/hotkey.py`
- [Echo guard](https://github.com/fatihmakes/mark-lv/blob/main/core/echo.py): `core/echo.py`
- [Lip sync](https://github.com/fatihmakes/mark-lv/blob/main/core/viseme.py): `core/viseme.py`
- [Remote dashboard](https://github.com/fatihmakes/mark-lv/blob/main/dashboard/server.py): `dashboard/server.py`

### Assistant runtime

- [Live assistant](https://github.com/fatihmakes/mark-lv/blob/main/main.py): `main.py`
- [Gemini live and ladder](https://github.com/fatihmakes/mark-lv/blob/main/core/gemini.py): `core/gemini.py`
- [One-shot model client](https://github.com/fatihmakes/mark-lv/blob/main/core/llm_client.py): `core/llm_client.py`
- [Speech recognition](https://github.com/fatihmakes/mark-lv/blob/main/core/stt.py): `core/stt.py`
- [Speech synthesis](https://github.com/fatihmakes/mark-lv/blob/main/core/tts.py): `core/tts.py`

### Skills and tasks

- [Skill discovery](https://github.com/fatihmakes/mark-lv/blob/main/core/action_loader.py): `core/action_loader.py`
- [Web search](https://github.com/fatihmakes/mark-lv/blob/main/actions/web_search.py): `actions/web_search.py`
- [Computer and desktop control](https://github.com/fatihmakes/mark-lv/tree/main/actions): `actions`
- [File operations](https://github.com/fatihmakes/mark-lv/tree/main/actions): `actions`
- [Video playback](https://github.com/fatihmakes/mark-lv/tree/main/actions): `actions`
- [Proactive tasks](https://github.com/fatihmakes/mark-lv/tree/main/actions): `actions`
- [Plugin discovery](https://github.com/fatihmakes/mark-lv/blob/main/core/plugin_loader.py): `core/plugin_loader.py`
- [System monitoring](https://github.com/fatihmakes/mark-lv/blob/main/actions/system_monitor.py): `actions/system_monitor.py`

### Memory and access

- [Persistent memory](https://github.com/fatihmakes/mark-lv/blob/main/memory/memory_manager.py): `memory/memory_manager.py`
- [Assistant configuration](https://github.com/fatihmakes/mark-lv/blob/main/memory/config_manager.py): `memory/config_manager.py`
- [Undo history](https://github.com/fatihmakes/mark-lv/blob/main/core/undo.py): `core/undo.py`
- [Action confirmation](https://github.com/fatihmakes/mark-lv/blob/main/core/confirm.py): `core/confirm.py`

### Other components

- **User**

## Connections

- User → Live assistant: speaks or requests
- Live assistant → HUD and controls: updates display (evidence: `main.py`)
- Live assistant → Gemini live and ladder: runs live session (evidence: `main.py`)
- Live assistant → Audio devices: configures devices (evidence: `main.py`)
- Live assistant → Persistent memory: loads context (evidence: `main.py`)
- Live assistant → Assistant configuration: reads settings (evidence: `main.py`)
- Live assistant → Skill discovery: loads skills (evidence: `main.py`)
- Live assistant → Plugin discovery: loads plugins (evidence: `main.py`)
- HUD and controls → Holographic avatar: shows face (evidence: `ui.py`)
- Holographic avatar → Face geometry: uses geometry (evidence: `core/avatar.py`)
- Live assistant → Wake word: gates listening (evidence: `main.py`)
- Live assistant → Push to talk: handles hotkey (evidence: `main.py`)
- Live assistant → Echo guard: filters self-echo (evidence: `main.py`)
- Live assistant → Lip sync: drives mouth (evidence: `main.py`)
- Live assistant → Speech recognition: transcribes audio
- Live assistant → Speech synthesis: speaks replies
- Skill discovery → Web search: discovers skill
- Skill discovery → Computer and desktop control: discovers skills
- Skill discovery → File operations: discovers skill
- Skill discovery → Video playback: discovers skill
- Live assistant → Web search: runs search (evidence: `main.py`)
- Live assistant → System monitoring: runs monitoring (evidence: `main.py`)
- Live assistant → Proactive tasks: runs proactive tasks (evidence: `main.py`)
- Computer and desktop control → Action confirmation: requests confirmation (evidence: `actions/computer_settings.py`)
- Computer and desktop control → Undo history: records reversible changes (evidence: `actions/computer_settings.py`)
- File operations → Undo history: records file changes (evidence: `actions/file_controller.py`)
- Plugin discovery → Assistant configuration: reads configuration (evidence: `core/plugin_loader.py`)
- User → Remote dashboard: pairs phone
- Remote dashboard → Live assistant: submits commands (evidence: `main.py`)