# fatihmakes/mark-xlvii architecture

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

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

## Overview

1. **Repository purpose**
   - This is a cross-platform local AI assistant, not a single-purpose app. The core runtime combines voice input/output, LLM reasoning, OS control, web access, vision/screen processing, and persistent memory.

2. **Main execution paths**
   - `main.py` is the primary assistant entrypoint.
   - `ui.py` is likely a secondary interface/bootstrap path.
   - `dashboard/server.py` runs a separate local web dashboard, with static assets in `dashboard/static/`.

3. **Core orchestration layer**
   - The `core/` package is the assistant’s runtime spine.
   - `llm_client.py` is the model gateway, and the README makes Gemini the central LLM backend.
   - `stt.py` and `tts.py` handle speech-to-text and text-to-speech, forming the voice loop.
   - `prompt.txt` provides the base system prompt/personality for the agent.
   - `installer.py` suggests environment/bootstrap setup for missing dependencies or platform-specific setup.

4. **Tool / action subsystem**
   - The `actions/` package is the assistant’s toolbelt, where model decisions become real-world operations.
   - It includes computer control, browser control, app launching, file operations, reminders, messaging, weather, web search, YouTube, flight search, and game updating.
   - `dev_agent.py` and `code_helper.py` imply a more specialized coding/autonomous-workflow path.
   - This layer is the main boundary between “reasoning” and “doing.”

5. **Perception and device control**
   - `screen_processor.py` and `browser_control.py` indicate visual/screen-aware workflows and browser automation.
   - `computer_control.py`, `desktop.py`, and `computer_settings.py` cover OS-level interaction and system tuning.
   - `system_monitor.py` provides background telemetry, matching the README’s CPU/RAM/GPU/temperature monitoring and alerting.

6. **Persistent memory**
   - `memory/` holds the assistant’s long-term context.
   - `memory_manager.py` and `config_manager.py` suggest a configurable store for user preferences, identity, and remembered facts like city/language.
   - This memory layer is separate from transient chat state, so the assistant can personalize across boots and sessions.

7. **Local dashboard boundary**
   - `dashboard/` is an independent presentation layer for monitoring or interaction.
   - `app.html` and `login.html` show a minimal web frontend, likely served locally by `server.py`.
   - The presence of `config/certs/jarvis.crt` and `jarvis.key` suggests the dashboard or local services may run over HTTPS with bundled certificates.

8. **Data flow through the system**
   - The typical flow is: microphone or UI input → STT/text parsing → LLM reasoning → tool selection in `actions/` → OS/web/file side effects → response text → TTS and/or dashboard display.
   - For vision-enabled tasks, screen/browser data feeds into the reasoning loop through the processor/control modules before actions are executed.

9. **External dependencies and services that matter architecturally**
   - Gemini is the main external AI service and likely governs both general dialogue and grounded search behavior.
   - Web search and browser automation depend on external sites and browser tooling, with fallback behavior noted in the README.
   - The assistant is designed around OS-native capabilities, so platform-specific APIs and permissions are important architectural constraints.

10. **How to diagram it**
   - The cleanest diagram is a hub-and-spoke model: a central assistant core calling out to voice I/O, memory, dashboard/UI, and action modules.
   - The action modules form the execution boundary to the operating system, browser, files, and external web services.
   - Memory sits alongside the core as a persistent context store, while the dashboard is an optional local control/visibility surface.

Main entry points: [`main.py`](https://github.com/fatihmakes/mark-xlvii/blob/main/main.py) (main.py), [`core/llm_client.py`](https://github.com/fatihmakes/mark-xlvii/blob/main/core/llm_client.py) (LLM client), [`dashboard/server.py`](https://github.com/fatihmakes/mark-xlvii/blob/main/dashboard/server.py) (Dashboard server), [`actions/screen_processor.py`](https://github.com/fatihmakes/mark-xlvii/blob/main/actions/screen_processor.py) (Screen vision)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main_py(("main.py<br/>entrypoint<br/>[main.py]"))
  node_ui_py(("ui.py<br/>entrypoint<br/>[ui.py]"))
  node_llm_client["LLM client<br/>model gateway<br/>[llm_client.py]"]
  node_prompt["Base prompt<br/>persona prompt<br/>[prompt.txt]"]
  node_installer["Installer<br/>bootstrap<br/>[installer.py]"]
end

subgraph group_voice["Voice I/O"]
  node_stt["Speech input<br/>stt<br/>[stt.py]"]
  node_tts["Speech output<br/>tts<br/>[tts.py]"]
end

subgraph group_actions["Actions"]
  node_web_search["Web search<br/>web tool<br/>[web_search.py]"]
  node_browser_control["Browser control<br/>browser automation<br/>[browser_control.py]"]
  node_screen_processor["Screen vision"]
  node_computer_control["Computer control<br/>os control"]
  node_file_ops["File ops<br/>files<br/>[file_controller.py]"]
  node_comm_tools["Comm tools<br/>assistant tools<br/>[send_message.py]"]
  node_dev_tools{{"Dev tools<br/>coding tools<br/>[dev_agent.py]"}}
  node_system_monitor["System monitor<br/>telemetry<br/>[system_monitor.py]"]
end

subgraph group_memory["Memory"]
  node_memory_mgr[("Memory store<br/>memory manager<br/>[memory_manager.py]")]
  node_config_mgr["Prefs config<br/>config manager<br/>[config_manager.py]"]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_server(("Dashboard server<br/>web server<br/>[server.py]"))
  node_dashboard_ui["Dashboard UI<br/>web frontend<br/>[app.html]"]
  node_certs["TLS certs<br/>security assets<br/>[jarvis.crt]"]
end

node_main_py -->|"capture speech"| node_stt
node_main_py -->|"reason"| node_llm_client
node_main_py -->|"speak"| node_tts
node_main_py -->|"remember"| node_memory_mgr
node_main_py -->|"personalize"| node_config_mgr
node_main_py -->|"prime"| node_prompt
node_main_py -->|"act"| node_computer_control
node_main_py -->|"lookup"| node_web_search
node_main_py -->|"browse"| node_browser_control
node_main_py -->|"see"| node_screen_processor
node_main_py -->|"files"| node_file_ops
node_main_py -->|"assist"| node_comm_tools
node_main_py -->|"code"| node_dev_tools
node_main_py -->|"monitor"| node_system_monitor
node_ui_py -->|"bootstrap"| node_llm_client
node_dashboard_server -->|"serve"| node_dashboard_ui
node_dashboard_server -.->|"https"| node_certs
node_llm_client -.->|"context"| node_memory_mgr
node_llm_client -.->|"ground"| node_web_search
node_llm_client -.->|"plan"| node_dev_tools
node_screen_processor -.->|"visual loop"| node_browser_control
node_computer_control -.->|"state"| node_system_monitor

click node_main_py "https://github.com/fatihmakes/mark-xlvii/blob/main/main.py"
click node_ui_py "https://github.com/fatihmakes/mark-xlvii/blob/main/ui.py"
click node_llm_client "https://github.com/fatihmakes/mark-xlvii/blob/main/core/llm_client.py"
click node_prompt "https://github.com/fatihmakes/mark-xlvii/blob/main/core/prompt.txt"
click node_stt "https://github.com/fatihmakes/mark-xlvii/blob/main/core/stt.py"
click node_tts "https://github.com/fatihmakes/mark-xlvii/blob/main/core/tts.py"
click node_installer "https://github.com/fatihmakes/mark-xlvii/blob/main/core/installer.py"
click node_memory_mgr "https://github.com/fatihmakes/mark-xlvii/blob/main/memory/memory_manager.py"
click node_config_mgr "https://github.com/fatihmakes/mark-xlvii/blob/main/memory/config_manager.py"
click node_web_search "https://github.com/fatihmakes/mark-xlvii/blob/main/actions/web_search.py"
click node_browser_control "https://github.com/fatihmakes/mark-xlvii/blob/main/actions/browser_control.py"
click node_screen_processor "https://github.com/fatihmakes/mark-xlvii/blob/main/actions/screen_processor.py"
click node_computer_control "https://github.com/fatihmakes/mark-xlvii/blob/main/actions/computer_control.py"
click node_file_ops "https://github.com/fatihmakes/mark-xlvii/blob/main/actions/file_controller.py"
click node_comm_tools "https://github.com/fatihmakes/mark-xlvii/blob/main/actions/send_message.py"
click node_dev_tools "https://github.com/fatihmakes/mark-xlvii/blob/main/actions/dev_agent.py"
click node_system_monitor "https://github.com/fatihmakes/mark-xlvii/blob/main/actions/system_monitor.py"
click node_dashboard_server "https://github.com/fatihmakes/mark-xlvii/blob/main/dashboard/server.py"
click node_dashboard_ui "https://github.com/fatihmakes/mark-xlvii/blob/main/dashboard/static/app.html"
click node_certs "https://github.com/fatihmakes/mark-xlvii/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,node_llm_client,node_prompt,node_installer toneBlue
class node_stt,node_tts toneAmber
class node_web_search,node_browser_control,node_screen_processor,node_computer_control,node_file_ops,node_comm_tools,node_dev_tools,node_system_monitor toneMint
class node_memory_mgr,node_config_mgr toneRose
class node_dashboard_server,node_dashboard_ui,node_certs toneIndigo
```

## Components

### Runtime

Primary assistant entrypoints and orchestration

- [main.py](https://github.com/fatihmakes/mark-xlvii/blob/main/main.py): entrypoint · Primary assistant process · `main.py`
- [ui.py](https://github.com/fatihmakes/mark-xlvii/blob/main/ui.py): entrypoint · Secondary UI/bootstrap entry · `ui.py`
- [LLM client](https://github.com/fatihmakes/mark-xlvii/blob/main/core/llm_client.py): model gateway · Routes prompts to the main AI backend · `core/llm_client.py`
- [Base prompt](https://github.com/fatihmakes/mark-xlvii/blob/main/core/prompt.txt): persona prompt · System prompt and assistant behavior rules · `core/prompt.txt`
- [Installer](https://github.com/fatihmakes/mark-xlvii/blob/main/core/installer.py): bootstrap · Dependency and platform setup helper · `core/installer.py`

### Voice I/O

Speech input/output loop

- [Speech input](https://github.com/fatihmakes/mark-xlvii/blob/main/core/stt.py): stt · Voice to text transcription · `core/stt.py`
- [Speech output](https://github.com/fatihmakes/mark-xlvii/blob/main/core/tts.py): tts · Text to speech response synthesis · `core/tts.py`

### Actions

Tooling and side-effect execution

- [Web search](https://github.com/fatihmakes/mark-xlvii/blob/main/actions/web_search.py): web tool · Searches external web sources · `actions/web_search.py`
- [Browser control](https://github.com/fatihmakes/mark-xlvii/blob/main/actions/browser_control.py): browser automation · Controls browser-based workflows · `actions/browser_control.py`
- [Screen vision](https://github.com/fatihmakes/mark-xlvii/blob/main/actions/screen_processor.py): vision · Processes screen or browser visual context · `actions/screen_processor.py`
- [Computer control](https://github.com/fatihmakes/mark-xlvii/blob/main/actions/computer_control.py): os control · Performs desktop and OS interactions · `actions/computer_control.py`
- [File ops](https://github.com/fatihmakes/mark-xlvii/blob/main/actions/file_controller.py): files · File processing and controller boundary · `actions/file_controller.py`
- [Comm tools](https://github.com/fatihmakes/mark-xlvii/blob/main/actions/send_message.py): assistant tools · Messaging, reminders, weather, flights, YouTube, apps, game updates · `actions/send_message.py`
- [Dev tools](https://github.com/fatihmakes/mark-xlvii/blob/main/actions/dev_agent.py): coding tools · Coding assistant and autonomous work helpers · `actions/dev_agent.py`
- [System monitor](https://github.com/fatihmakes/mark-xlvii/blob/main/actions/system_monitor.py): telemetry · Tracks CPU, RAM, GPU, temperature, and alerts · `actions/system_monitor.py`

### Memory

Persistent context and preferences

- [Memory store](https://github.com/fatihmakes/mark-xlvii/blob/main/memory/memory_manager.py): memory manager · Persistent long-term assistant memory · `memory/memory_manager.py`
- [Prefs config](https://github.com/fatihmakes/mark-xlvii/blob/main/memory/config_manager.py): config manager · Saved user preferences and identity context · `memory/config_manager.py`

### Dashboard

Local web UI and server

- [Dashboard server](https://github.com/fatihmakes/mark-xlvii/blob/main/dashboard/server.py): web server · Serves the local dashboard application · `dashboard/server.py`
- [Dashboard UI](https://github.com/fatihmakes/mark-xlvii/blob/main/dashboard/static/app.html): web frontend · Local HTML interface for login and status · `dashboard/static/app.html`
- [TLS certs](https://github.com/fatihmakes/mark-xlvii/blob/main/config/certs/jarvis.crt): security assets · Bundled certificate and key for local HTTPS · `config/certs/jarvis.crt`

## Connections

- main.py → Speech input: capture speech · Primary voice input path
- main.py → LLM client: reason · Sends user context and prompts to the model
- main.py → Speech output: speak · Converts assistant responses to audio
- main.py → Memory store: remember · Reads and updates long-term context
- main.py → Prefs config: personalize · Loads user-specific preferences and identity
- main.py → Base prompt: prime · Uses the base assistant prompt
- main.py → Computer control: act · Delegates OS-level actions
- main.py → Web search: lookup · Queries external information
- main.py → Browser control: browse · Runs browser-based tasks
- main.py → Screen vision: see · Feeds visual context into the loop
- main.py → File ops: files · Handles file-oriented actions
- main.py → Comm tools: assist · Uses reminder, messaging, travel, media, and app tools
- main.py → Dev tools: code · Enables coding and autonomous helper flows
- main.py → System monitor: monitor · Reads system telemetry and alerts
- ui.py → LLM client: bootstrap · Alternative UI path into the assistant runtime
- Dashboard server → Dashboard UI: serve · Hosts the local dashboard frontend
- Dashboard server → TLS certs: https · Uses bundled TLS assets for local secure serving
- LLM client → Memory store: context · Can retrieve persistent memory for grounding
- LLM client → Web search: ground · Can delegate external lookup when needed
- LLM client → Dev tools: plan · Can trigger specialized coding workflows
- Screen vision → Browser control: visual loop · Screen-aware automation feeds browser control
- Computer control → System monitor: state · Desktop control and telemetry inform each other