# fatihmakes/mark-xlvi architecture

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

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

## Overview

MARK XLVI is a local, cross-platform assistant with three major surfaces: voice/desktop control, a remote dashboard for phone/browser access, and persistent memory. The runtime is centered on Gemini-backed reasoning, with local OS automation, screen understanding, and speech I/O wrapped around it.

1. **Primary orchestration path**
   - `main.py` is the likely main entrypoint for launching the assistant.
   - `ui.py` appears to provide the local user interface layer.
   - The core loop is: user input → LLM reasoning → tool/action execution → response output.

2. **LLM and prompt layer**
   - `core/llm_client.py` is the API boundary to the model provider, and the README says Gemini is the main integration.
   - `core/prompt.txt` likely contains the system instructions / assistant persona.
   - This layer is the decision-making center that chooses whether to answer directly or invoke a tool.

3. **Speech pipeline**
   - `core/stt.py` handles speech-to-text input from the microphone.
   - `core/tts.py` handles spoken output back to the user.
   - This is the real-time voice interface described in the README and is separate from the action execution layer.

4. **Tool/action subsystem**
   - The `actions/` package is the assistant’s operational boundary: each file is a capability module.
   - Core device control lives in `computer_control.py`, `computer_settings.py`, `desktop.py`, and `open_app.py`.
   - Web/browser automation is split into `browser_control.py` and `web_search.py`.
   - File-centric operations are handled by `file_controller.py` and `file_processor.py`.
   - Visual/contextual input comes from `screen_processor.py`.
   - Specialized task modules include `weather_report.py`, `flight_finder.py`, `youtube_video.py`, `send_message.py`, `reminder.py`, `game_updater.py`, `code_helper.py`, and `dev_agent.py`.

5. **OS and environment control boundary**
   - The assistant is explicitly cross-platform, so OS-specific behavior is likely isolated inside the actions layer rather than the core loop.
   - `actions/computer_control.py` and related modules are the abstraction over Windows/macOS/Linux differences.
   - `core/installer.py` suggests a bootstrap/setup path for platform dependencies and runtime preparation.

6. **Visual awareness path**
   - `actions/screen_processor.py` and `actions/desktop.py` indicate screen capture / desktop state inspection.
   - This provides the “see” capability mentioned in the README and likely feeds contextual information back into the LLM before action selection.
   - In the architecture diagram, this should be shown as a feedback loop from the desktop into the reasoning engine.

7. **Persistent memory subsystem**
   - `memory/memory_manager.py` is the main persistence abstraction.
   - `memory/config_manager.py` likely manages memory-related settings and storage configuration.
   - This subsystem preserves long-term context across sessions, which the README describes as advanced persistent memory.

8. **Remote dashboard / phone control**
   - `dashboard/server.py` is a separate server process or embedded web server for remote access.
   - `dashboard/static/app.html` and `login.html` are the browser-facing UI assets.
   - `config/certs/jarvis.crt` and `jarvis.key` show the dashboard uses TLS, which matters for the secure remote-control story.
   - This is a distinct boundary from the local desktop UI: remote clients talk to the dashboard, not directly to the assistant internals.

9. **Security and transport**
   - The presence of certificates in `config/certs/` indicates HTTPS/TLS is part of the deployment model.
   - This is important because the README emphasizes secure mobile control and file sharing.
   - The security boundary is therefore the dashboard server, not the action modules themselves.

10. **External dependencies and integrations**
   - The README indicates Gemini API usage for reasoning.
   - `playwright install` in the setup instructions implies browser automation depends on Playwright.
   - The assistant also depends on local microphone/speaker hardware and standard OS automation capabilities.

11. **Likely end-to-end data flow**
   - Local voice path: microphone → STT → LLM client → action modules / memory → TTS → user.
   - Remote path: mobile/browser client → dashboard server → assistant core/actions → response back to dashboard.
   - Visual path: screen/desktop capture → screen processor → LLM context → actions.

12. **What to show in a diagram**
   - Put `core/llm_client.py` at the center.
   - Surround it with three major systems: speech I/O, actions/tooling, and memory.
   - Add a separate remote access lane for `dashboard/server.py` and static web assets.
   - Draw the OS as the execution target for the `actions/` package, and Gemini as the external reasoning service.

Main entry points: [`core/llm_client.py`](https://github.com/fatihmakes/mark-xlvi/blob/main/core/llm_client.py) (LLM Client), [`dashboard/server.py`](https://github.com/fatihmakes/mark-xlvi/blob/main/dashboard/server.py) (Dashboard API), [`actions/computer_control.py`](https://github.com/fatihmakes/mark-xlvi/blob/main/actions/computer_control.py) (Computer), [`actions/screen_processor.py`](https://github.com/fatihmakes/mark-xlvi/blob/main/actions/screen_processor.py) (Screen AI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main_py["Main<br/>entrypoint<br/>[main.py]"]
  node_ui_py["Desktop UI<br/>local-ui<br/>[ui.py]"]
end

subgraph group_core["Core"]
  node_llm_client["LLM Client<br/>model-gateway<br/>[llm_client.py]"]
  node_prompt_txt["Prompt<br/>[prompt.txt]"]
  node_stt_py["Speech In<br/>stt<br/>[stt.py]"]
  node_tts_py["Speech Out<br/>tts<br/>[tts.py]"]
  node_installer_py["Installer<br/>bootstrap<br/>[installer.py]"]
end

subgraph group_actions["Actions"]
  node_computer_control["Computer<br/>os-control"]
  node_computer_settings["Settings"]
  node_desktop["Desktop<br/>screen-state<br/>[desktop.py]"]
  node_screen_processor["Screen AI<br/>vision"]
  node_browser_control["Browser<br/>web-automation<br/>[browser_control.py]"]
  node_web_search["Search<br/>[web_search.py]"]
  node_file_controller["Files<br/>file-control<br/>[file_controller.py]"]
  node_special_actions["Special Tasks<br/>task-modules<br/>[weather_report.py]"]
  node_dev_tools["Dev Assist<br/>code-tools<br/>[code_helper.py]"]
end

subgraph group_memory["Memory"]
  node_memory_manager[("Memory<br/>persistence<br/>[memory_manager.py]")]
  node_config_manager["Memory Config<br/>settings<br/>[config_manager.py]"]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_server["Dashboard API<br/>remote-server<br/>[server.py]"]
  node_dashboard_ui["Dashboard UI<br/>web-ui<br/>[app.html]"]
  node_dashboard_login["Login<br/>web-ui<br/>[login.html]"]
end

subgraph group_config["Security"]
  node_certs["TLS Certs<br/>tls-assets<br/>[jarvis.crt]"]
end

node_main_py -->|"starts"| node_ui_py
node_main_py -->|"orchestrates"| node_llm_client
node_ui_py -->|"captures"| node_stt_py
node_stt_py -->|"transcribes to"| node_llm_client
node_llm_client -->|"loads"| node_prompt_txt
node_llm_client -->|"reads/writes"| node_memory_manager
node_memory_manager -->|"configured by"| node_config_manager
node_llm_client -->|"selects tools"| node_computer_control
node_llm_client -->|"selects tools"| node_browser_control
node_llm_client -->|"selects tools"| node_file_controller
node_llm_client -->|"requests vision"| node_screen_processor
node_desktop -->|"feeds"| node_screen_processor
node_screen_processor -->|"context for"| node_llm_client
node_llm_client -->|"selects tools"| node_special_actions
node_llm_client -->|"selects tools"| node_dev_tools
node_llm_client -->|"speaks"| node_tts_py
node_computer_control -.->|"manages"| node_computer_settings
node_dashboard_ui -->|"calls"| node_dashboard_server
node_dashboard_login -->|"authenticates"| node_dashboard_server
node_dashboard_server -->|"routes to"| node_llm_client
node_dashboard_server -->|"syncs"| node_memory_manager
node_dashboard_server -->|"controls"| node_computer_control
node_certs -->|"secures"| node_dashboard_server
node_installer_py -.->|"prepares"| node_dashboard_server
node_installer_py -.->|"installs"| node_browser_control

click node_main_py "https://github.com/fatihmakes/mark-xlvi/blob/main/main.py"
click node_ui_py "https://github.com/fatihmakes/mark-xlvi/blob/main/ui.py"
click node_llm_client "https://github.com/fatihmakes/mark-xlvi/blob/main/core/llm_client.py"
click node_prompt_txt "https://github.com/fatihmakes/mark-xlvi/blob/main/core/prompt.txt"
click node_stt_py "https://github.com/fatihmakes/mark-xlvi/blob/main/core/stt.py"
click node_tts_py "https://github.com/fatihmakes/mark-xlvi/blob/main/core/tts.py"
click node_installer_py "https://github.com/fatihmakes/mark-xlvi/blob/main/core/installer.py"
click node_memory_manager "https://github.com/fatihmakes/mark-xlvi/blob/main/memory/memory_manager.py"
click node_config_manager "https://github.com/fatihmakes/mark-xlvi/blob/main/memory/config_manager.py"
click node_computer_control "https://github.com/fatihmakes/mark-xlvi/blob/main/actions/computer_control.py"
click node_computer_settings "https://github.com/fatihmakes/mark-xlvi/blob/main/actions/computer_settings.py"
click node_desktop "https://github.com/fatihmakes/mark-xlvi/blob/main/actions/desktop.py"
click node_screen_processor "https://github.com/fatihmakes/mark-xlvi/blob/main/actions/screen_processor.py"
click node_browser_control "https://github.com/fatihmakes/mark-xlvi/blob/main/actions/browser_control.py"
click node_web_search "https://github.com/fatihmakes/mark-xlvi/blob/main/actions/web_search.py"
click node_file_controller "https://github.com/fatihmakes/mark-xlvi/blob/main/actions/file_controller.py"
click node_special_actions "https://github.com/fatihmakes/mark-xlvi/blob/main/actions/weather_report.py"
click node_dev_tools "https://github.com/fatihmakes/mark-xlvi/blob/main/actions/code_helper.py"
click node_dashboard_server "https://github.com/fatihmakes/mark-xlvi/blob/main/dashboard/server.py"
click node_dashboard_ui "https://github.com/fatihmakes/mark-xlvi/blob/main/dashboard/static/app.html"
click node_dashboard_login "https://github.com/fatihmakes/mark-xlvi/blob/main/dashboard/static/login.html"
click node_certs "https://github.com/fatihmakes/mark-xlvi/blob/main/config/certs/jarvis.crt"

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_py,node_ui_py toneBlue
class node_llm_client,node_prompt_txt,node_stt_py,node_tts_py,node_installer_py toneAmber
class node_computer_control,node_computer_settings,node_desktop,node_screen_processor,node_browser_control,node_web_search,node_file_controller,node_special_actions,node_dev_tools toneMint
class node_memory_manager,node_config_manager toneRose
class node_dashboard_server,node_dashboard_ui,node_dashboard_login toneIndigo
class node_certs toneTeal
```

## Components

### Runtime

Local assistant entrypoints and orchestration

- [Main](https://github.com/fatihmakes/mark-xlvi/blob/main/main.py): entrypoint · Launches the assistant runtime · `main.py`
- [Desktop UI](https://github.com/fatihmakes/mark-xlvi/blob/main/ui.py): local-ui · Local control surface · `ui.py`

### Core

Reasoning, speech, and bootstrap

- [LLM Client](https://github.com/fatihmakes/mark-xlvi/blob/main/core/llm_client.py): model-gateway · Gemini-facing reasoning boundary · `core/llm_client.py`
- [Prompt](https://github.com/fatihmakes/mark-xlvi/blob/main/core/prompt.txt): system-prompt · Assistant instructions and persona · `core/prompt.txt`
- [Speech In](https://github.com/fatihmakes/mark-xlvi/blob/main/core/stt.py): stt · Microphone to text pipeline · `core/stt.py`
- [Speech Out](https://github.com/fatihmakes/mark-xlvi/blob/main/core/tts.py): tts · Text to spoken response pipeline · `core/tts.py`
- [Installer](https://github.com/fatihmakes/mark-xlvi/blob/main/core/installer.py): bootstrap · Environment and dependency setup · `core/installer.py`

### Actions

Tooling and OS automation

- [Computer](https://github.com/fatihmakes/mark-xlvi/blob/main/actions/computer_control.py): os-control · Keyboard, mouse, and system automation · `actions/computer_control.py`
- [Settings](https://github.com/fatihmakes/mark-xlvi/blob/main/actions/computer_settings.py): os-settings · System configuration actions · `actions/computer_settings.py`
- [Desktop](https://github.com/fatihmakes/mark-xlvi/blob/main/actions/desktop.py): screen-state · Desktop context and capture boundary · `actions/desktop.py`
- [Screen AI](https://github.com/fatihmakes/mark-xlvi/blob/main/actions/screen_processor.py): vision · Screen understanding and visual context · `actions/screen_processor.py`
- [Browser](https://github.com/fatihmakes/mark-xlvi/blob/main/actions/browser_control.py): web-automation · Automated browser interaction · `actions/browser_control.py`
- [Search](https://github.com/fatihmakes/mark-xlvi/blob/main/actions/web_search.py): web-search · Web lookup and retrieval · `actions/web_search.py`
- [Files](https://github.com/fatihmakes/mark-xlvi/blob/main/actions/file_controller.py): file-control · File operations and management · `actions/file_controller.py`
- [Special Tasks](https://github.com/fatihmakes/mark-xlvi/blob/main/actions/weather_report.py): task-modules · Domain tools like weather, flight, media, reminders · `actions/weather_report.py`
- [Dev Assist](https://github.com/fatihmakes/mark-xlvi/blob/main/actions/code_helper.py): code-tools · Code help and agentic development tasks · `actions/code_helper.py`

### Memory

Persistent context and settings

- [Memory](https://github.com/fatihmakes/mark-xlvi/blob/main/memory/memory_manager.py): persistence · Long-term memory store and retrieval · `memory/memory_manager.py`
- [Memory Config](https://github.com/fatihmakes/mark-xlvi/blob/main/memory/config_manager.py): settings · Memory storage and policy config · `memory/config_manager.py`

### Dashboard

Remote access server and web UI

- [Dashboard API](https://github.com/fatihmakes/mark-xlvi/blob/main/dashboard/server.py): remote-server · Remote access and control server · `dashboard/server.py`
- [Dashboard UI](https://github.com/fatihmakes/mark-xlvi/blob/main/dashboard/static/app.html): web-ui · Browser-facing dashboard shell · `dashboard/static/app.html`
- [Login](https://github.com/fatihmakes/mark-xlvi/blob/main/dashboard/static/login.html): web-ui · Dashboard authentication screen · `dashboard/static/login.html`

### Security

Deployment certificates

- [TLS Certs](https://github.com/fatihmakes/mark-xlvi/blob/main/config/certs/jarvis.crt): tls-assets · HTTPS certificates and keys · `config/certs/jarvis.crt`

## Connections

- Main → Desktop UI: starts · Main launches the local UI and runtime
- Main → LLM Client: orchestrates · Main routes user requests into the reasoning core
- Desktop UI → Speech In: captures · Local UI can feed voice input into speech recognition
- Speech In → LLM Client: transcribes to · Speech input becomes model context
- LLM Client → Prompt: loads · Reasoning uses the system prompt
- LLM Client → Memory: reads/writes · Model decisions are informed by persistent memory
- Memory → Memory Config: configured by · Memory storage and policy settings shape persistence
- LLM Client → Computer: selects tools · Reasoning can trigger OS actions
- LLM Client → Browser: selects tools · Reasoning can trigger browser automation
- LLM Client → Files: selects tools · Reasoning can trigger file operations
- LLM Client → Screen AI: requests vision · Model can pull screen context before acting
- Desktop → Screen AI: feeds · Desktop state and capture flow into visual understanding
- Screen AI → LLM Client: context for · Visual analysis returns to the reasoning loop
- LLM Client → Special Tasks: selects tools · Domain-specific tasks are invoked from the core loop
- LLM Client → Dev Assist: selects tools · Developer-oriented assistance is exposed as a capability
- LLM Client → Speech Out: speaks · Final responses are rendered to audio
- Computer → Settings: manages · System control can extend into settings and preferences
- Dashboard UI → Dashboard API: calls · Remote browser clients talk to the dashboard server
- Login → Dashboard API: authenticates · Login flow terminates at the dashboard server
- Dashboard API → LLM Client: routes to · Remote requests enter the same assistant reasoning core
- Dashboard API → Memory: syncs · Remote sessions can access persistent memory
- Dashboard API → Computer: controls · Dashboard can drive local actions through the assistant core
- TLS Certs → Dashboard API: secures · TLS materials secure the remote dashboard
- Installer → Dashboard API: prepares · Bootstrap configures runtime dependencies and services
- Installer → Browser: installs · Setup prepares browser automation dependencies