# musabduman/ghost-operator-v2 architecture

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

- Interactive diagram: https://gitdiagram.com/musabduman/ghost-operator-v2
- Repository: https://github.com/musabduman/ghost-operator-v2

## Overview

Ghost is a local-first personal AI assistant. Its documented workflow accepts voice or chat, routes work through a LangGraph supervisor/worker and critic, dispatches tools, and returns a response; memory captures activity and distills durable facts. The graph also preserves project memory, voice, UI, and integrations. Some subsystems are documented but their implementation was not sampled, so those links cite the README; the separate prime-agent tree and flight simulator are not part of Ghost’s described product.

Main entry points: [`handler/command_handler.py`](https://github.com/musabduman/ghost-operator-v2/blob/main/handler/command_handler.py) (Command handler), [`legacy/ui_v1/main.py`](https://github.com/musabduman/ghost-operator-v2/blob/main/legacy/ui_v1/main.py) (Desktop UI), [`ai/llm.py`](https://github.com/musabduman/ghost-operator-v2/blob/main/ai/llm.py) (Supervisor and workers), [`server.py`](https://github.com/musabduman/ghost-operator-v2/blob/main/server.py) (Core server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_desktop["Desktop UI<br/>[main.py]"]
  node_webui["Web UI<br/>[App.jsx]"]
  node_voice["Voice handler<br/>[voice_handler.py]"]
  node_server["Core server<br/>[server.py]"]
  node_sessions[("Session store<br/>[session_manager.py]")]
end

subgraph group_agent["Agent and tools"]
  node_llm["Supervisor and workers<br/>[llm.py]"]
  node_registry["Tool registry<br/>[tool_registry.py]"]
  node_commands["Command handler<br/>[command_handler.py]"]
end

subgraph group_memory["Memory"]
  node_episodic[("Episodic log<br/>[episodic_db.py]")]
  node_librarian["Librarian agent<br/>[librarian_agent.py]"]
  node_rag[("RAG memory<br/>[rag_hafıza.py]")]
  node_projectmemory[("Project memory<br/>[project_memory.py]")]
  node_symbolmap[("Project symbol map<br/>[symbol_graph.py]")]
end

subgraph group_integrations["Machine integrations"]
  node_fs["File operations<br/>[fs.py]"]
  node_whatsapp["WhatsApp<br/>[whatsapp_tool.py]"]
  node_vision["Screen vision<br/>[vison.py]"]
  node_spotify["Spotify<br/>[spotify.py]"]
  node_browser["Browser tool<br/>[browser_tool.py]"]
end

node_user(("User"))

node_user -->|"sends input"| node_desktop
node_desktop -->|"submits commands"| node_commands
node_desktop -->|"uses voice"| node_voice
node_desktop -->|"loads sessions"| node_sessions
node_user -->|"sends chat"| node_webui
node_webui -.->|"WebSocket chat"| node_server
node_server -->|"dispatches"| node_commands
node_server -->|"uses sessions"| node_sessions
node_commands -->|"runs agent"| node_llm
node_llm -->|"uses schemas"| node_registry
node_llm -->|"dispatches tools"| node_commands
node_commands -->|"calls file tools"| node_fs
node_commands -->|"calls WhatsApp"| node_whatsapp
node_commands -->|"calls vision"| node_vision
node_commands -->|"calls browser"| node_browser
node_commands -.->|"uses integration"| node_spotify
node_llm -.->|"logs activity"| node_episodic
node_librarian -->|"reads unanalyzed logs"| node_episodic
node_librarian -->|"stores extracted facts"| node_rag
node_commands -.->|"injects project rules"| node_projectmemory
node_commands -.->|"uses project symbols"| node_symbolmap

click node_desktop "https://github.com/musabduman/ghost-operator-v2/blob/main/legacy/ui_v1/main.py"
click node_webui "https://github.com/musabduman/ghost-operator-v2/blob/main/frontend/src/App.jsx"
click node_voice "https://github.com/musabduman/ghost-operator-v2/blob/main/handler/voice_handler.py"
click node_server "https://github.com/musabduman/ghost-operator-v2/blob/main/server.py"
click node_sessions "https://github.com/musabduman/ghost-operator-v2/blob/main/sessions/session_manager.py"
click node_llm "https://github.com/musabduman/ghost-operator-v2/blob/main/ai/llm.py"
click node_registry "https://github.com/musabduman/ghost-operator-v2/blob/main/core/tool_registry.py"
click node_commands "https://github.com/musabduman/ghost-operator-v2/blob/main/handler/command_handler.py"
click node_episodic "https://github.com/musabduman/ghost-operator-v2/blob/main/haf%C4%B1za/episodic_db.py"
click node_librarian "https://github.com/musabduman/ghost-operator-v2/blob/main/ai/librarian_agent.py"
click node_rag "https://github.com/musabduman/ghost-operator-v2/blob/main/haf%C4%B1za/rag_haf%C4%B1za.py"
click node_projectmemory "https://github.com/musabduman/ghost-operator-v2/blob/main/haf%C4%B1za/project_memory.py"
click node_symbolmap "https://github.com/musabduman/ghost-operator-v2/blob/main/haf%C4%B1za/symbol_graph.py"
click node_fs "https://github.com/musabduman/ghost-operator-v2/blob/main/core/fs.py"
click node_whatsapp "https://github.com/musabduman/ghost-operator-v2/blob/main/tools/whatsapp_tool.py"
click node_vision "https://github.com/musabduman/ghost-operator-v2/blob/main/vison/vison.py"
click node_spotify "https://github.com/musabduman/ghost-operator-v2/blob/main/kontrol/spotify.py"
click node_browser "https://github.com/musabduman/ghost-operator-v2/blob/main/tools/browser_tool.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_desktop,node_webui,node_voice,node_server,node_sessions,node_user toneBlue
class node_llm,node_registry,node_commands toneAmber
class node_episodic,node_librarian,node_rag,node_projectmemory,node_symbolmap toneMint
class node_fs,node_whatsapp,node_vision,node_spotify,node_browser toneRose
```

## Components

### User interaction

- [Desktop UI](https://github.com/musabduman/ghost-operator-v2/blob/main/legacy/ui_v1/main.py): `legacy/ui_v1/main.py`
- [Web UI](https://github.com/musabduman/ghost-operator-v2/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Voice handler](https://github.com/musabduman/ghost-operator-v2/blob/main/handler/voice_handler.py): `handler/voice_handler.py`
- [Core server](https://github.com/musabduman/ghost-operator-v2/blob/main/server.py): `server.py`
- [Session store](https://github.com/musabduman/ghost-operator-v2/blob/main/sessions/session_manager.py): `sessions/session_manager.py`

### Agent and tools

- [Supervisor and workers](https://github.com/musabduman/ghost-operator-v2/blob/main/ai/llm.py): `ai/llm.py`
- [Tool registry](https://github.com/musabduman/ghost-operator-v2/blob/main/core/tool_registry.py): `core/tool_registry.py`
- [Command handler](https://github.com/musabduman/ghost-operator-v2/blob/main/handler/command_handler.py): `handler/command_handler.py`

### Memory

- [Episodic log](https://github.com/musabduman/ghost-operator-v2/blob/main/haf%C4%B1za/episodic_db.py): `hafıza/episodic_db.py`
- [Librarian agent](https://github.com/musabduman/ghost-operator-v2/blob/main/ai/librarian_agent.py): `ai/librarian_agent.py`
- [RAG memory](https://github.com/musabduman/ghost-operator-v2/blob/main/haf%C4%B1za/rag_haf%C4%B1za.py): `hafıza/rag_hafıza.py`
- [Project memory](https://github.com/musabduman/ghost-operator-v2/blob/main/haf%C4%B1za/project_memory.py): `hafıza/project_memory.py`
- [Project symbol map](https://github.com/musabduman/ghost-operator-v2/blob/main/haf%C4%B1za/symbol_graph.py): `hafıza/symbol_graph.py`

### Machine integrations

- [File operations](https://github.com/musabduman/ghost-operator-v2/blob/main/core/fs.py): `core/fs.py`
- [WhatsApp](https://github.com/musabduman/ghost-operator-v2/blob/main/tools/whatsapp_tool.py): `tools/whatsapp_tool.py`
- [Screen vision](https://github.com/musabduman/ghost-operator-v2/blob/main/vison/vison.py): `vison/vison.py`
- [Spotify](https://github.com/musabduman/ghost-operator-v2/blob/main/kontrol/spotify.py): `kontrol/spotify.py`
- [Browser tool](https://github.com/musabduman/ghost-operator-v2/blob/main/tools/browser_tool.py): `tools/browser_tool.py`

### Other components

- **User**

## Connections

- User → Desktop UI: sends input
- Desktop UI → Command handler: submits commands (evidence: `legacy/ui_v1/main.py`)
- Desktop UI → Voice handler: uses voice (evidence: `legacy/ui_v1/main.py`)
- Desktop UI → Session store: loads sessions (evidence: `legacy/ui_v1/main.py`)
- User → Web UI: sends chat (evidence: `frontend/src/App.jsx`)
- Web UI → Core server: WebSocket chat (evidence: `frontend/src/App.jsx`)
- Core server → Command handler: dispatches (evidence: `server.py`)
- Core server → Session store: uses sessions (evidence: `server.py`)
- Command handler → Supervisor and workers: runs agent (evidence: `handler/command_handler.py`)
- Supervisor and workers → Tool registry: uses schemas (evidence: `ai/llm.py`)
- Supervisor and workers → Command handler: dispatches tools (evidence: `handler/command_handler.py`)
- Command handler → File operations: calls file tools (evidence: `handler/command_handler.py`)
- Command handler → WhatsApp: calls WhatsApp (evidence: `handler/command_handler.py`)
- Command handler → Screen vision: calls vision (evidence: `handler/command_handler.py`)
- Command handler → Browser tool: calls browser (evidence: `handler/command_handler.py`)
- Command handler → Spotify: uses integration (evidence: `handler/command_handler.py`)
- Supervisor and workers → Episodic log: logs activity
- Librarian agent → Episodic log: reads unanalyzed logs
- Librarian agent → RAG memory: stores extracted facts
- Command handler → Project memory: injects project rules
- Command handler → Project symbol map: uses project symbols
