# darknorthaco/phantom architecture

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

- Interactive diagram: https://gitdiagram.com/darknorthaco/phantom
- Repository: https://github.com/darknorthaco/phantom

## Overview

Phantom is a privacy-first distributed compute platform, with the Tauri desktop app documented as its canonical install and deployment path. The principal user workflow is consent and controller placement, followed by deployment checks and the deployment ceremony, then operational monitoring and management. The deployed fabric routes work across heterogeneous workers, with GPU-specific execution and configurable LLM task scheduling. The graph preserves the documented swappable UI and legacy installer branches. Some backend and deployment wiring is unsampled, so those links are omitted or marked unverified.

Main entry points: [`phantom_core/phantom_core/controller_api.py`](https://github.com/darknorthaco/phantom/blob/master/phantom_core/phantom_core/controller_api.py) (Controller API), [`phantom_app/src/App.tsx`](https://github.com/darknorthaco/phantom/blob/master/phantom_app/src/App.tsx) (Desktop app), [`phantom_app/src/utils/tauri.ts`](https://github.com/darknorthaco/phantom/blob/master/phantom_app/src/utils/tauri.ts) (Tauri command bridge), [`phantom_core/phantom_core/socket_integration.py`](https://github.com/darknorthaco/phantom/blob/master/phantom_core/phantom_core/socket_integration.py) (Socket integration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop deployment"]
  node_app["Desktop app<br/>[App.tsx]"]
  node_placement["Controller placement"]
  node_deploy_ui["Deployment ceremony"]
  node_app_state["Ceremony state<br/>[deploymentState.ts]"]
  node_tauri_bridge["Tauri command bridge<br/>[tauri.ts]"]
  node_ceremony_backend["Ceremony orchestration<br/>[orchestrator.rs]"]
  node_deployer["Deployment operations"]
  node_legacy_installer["Legacy installers"]
end

subgraph group_engine["Distributed engine"]
  node_controller_api["Controller API<br/>[controller_api.py]"]
  node_orchestrator["Task orchestrator<br/>[orchestrator.py]"]
  node_taskmaster["LLM task pipeline<br/>[pipeline.py]"]
  node_socket["Socket integration"]
  node_protocol["Protocol transports"]
end

subgraph group_workers["Worker execution"]
  node_linux_worker["Linux worker<br/>[worker.py]"]
  node_windows_worker["Windows worker<br/>[worker.py]"]
  node_gpu_plugins["GPU plugin manager<br/>[plugin_manager.py]"]
end

subgraph group_security["Security and trust"]
  node_security["Integrated security"]
end

subgraph group_interfaces["Interfaces"]
  node_ui_framework["Swappable UI framework<br/>[ui_manager.py]"]
  node_matrix_ui["Matrix interface<br/>[App.js]"]
end

node_user(("Operator"))

node_user -->|"uses"| node_app
node_app -->|"renders"| node_placement
node_app -->|"renders"| node_deploy_ui
node_placement -->|"confirms placement"| node_tauri_bridge
node_app -->|"checks health"| node_tauri_bridge
node_deploy_ui -.->|"uses ceremony data"| node_app_state
node_tauri_bridge -.->|"invokes commands"| node_ceremony_backend
node_ceremony_backend -.->|"coordinates deployment"| node_deployer
node_controller_api -->|"initializes"| node_orchestrator
node_linux_worker -->|"initializes plugins"| node_gpu_plugins
node_linux_worker -->|"uses socket layer"| node_socket
node_windows_worker -->|"uses socket layer"| node_socket
node_controller_api -->|"initializes security"| node_security
node_controller_api -->|"uses socket layer"| node_socket
node_orchestrator -.->|"routes work"| node_taskmaster
node_controller_api -.->|"communicates through"| node_protocol
node_user -->|"uses"| node_matrix_ui
node_matrix_ui -.->|"uses framework"| node_ui_framework
node_user -->|"opts into"| node_legacy_installer

click node_app "https://github.com/darknorthaco/phantom/blob/master/phantom_app/src/App.tsx"
click node_placement "https://github.com/darknorthaco/phantom/blob/master/phantom_app/src/components/ControllerSelectionScreen.tsx"
click node_deploy_ui "https://github.com/darknorthaco/phantom/blob/master/phantom_app/src/components/DeploymentCeremony.tsx"
click node_app_state "https://github.com/darknorthaco/phantom/blob/master/phantom_app/src/state/deploymentState.ts"
click node_tauri_bridge "https://github.com/darknorthaco/phantom/blob/master/phantom_app/src/utils/tauri.ts"
click node_ceremony_backend "https://github.com/darknorthaco/phantom/blob/master/phantom_app/src-tauri/src/backend/ceremony/orchestrator.rs"
click node_deployer "https://github.com/darknorthaco/phantom/blob/master/phantom_app/src-tauri/src/backend/phantom_deployer.rs"
click node_controller_api "https://github.com/darknorthaco/phantom/blob/master/phantom_core/phantom_core/controller_api.py"
click node_orchestrator "https://github.com/darknorthaco/phantom/blob/master/phantom_core/phantom_core/orchestrator.py"
click node_taskmaster "https://github.com/darknorthaco/phantom/blob/master/phantom_core/llm_taskmaster/pipeline.py"
click node_socket "https://github.com/darknorthaco/phantom/blob/master/phantom_core/phantom_core/socket_integration.py"
click node_linux_worker "https://github.com/darknorthaco/phantom/blob/master/phantom_core/linux-worker/linux_worker/worker.py"
click node_windows_worker "https://github.com/darknorthaco/phantom/blob/master/phantom_core/windows-worker/windows_worker/worker.py"
click node_gpu_plugins "https://github.com/darknorthaco/phantom/blob/master/phantom_core/linux-worker/plugins/plugin_manager.py"
click node_security "https://github.com/darknorthaco/phantom/blob/master/phantom_core/security_framework/integrated_security.py"
click node_protocol "https://github.com/darknorthaco/phantom/tree/master/phantom_core/phantom_protocol"
click node_ui_framework "https://github.com/darknorthaco/phantom/blob/master/ui/ui_framework/ui_manager.py"
click node_matrix_ui "https://github.com/darknorthaco/phantom/blob/master/ui/redblue_matrix/phantom-matrix-android/App.js"
click node_legacy_installer "https://github.com/darknorthaco/phantom/tree/master/installer"

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_app,node_placement,node_deploy_ui,node_app_state,node_tauri_bridge,node_ceremony_backend,node_deployer,node_legacy_installer toneBlue
class node_controller_api,node_orchestrator,node_taskmaster,node_socket,node_protocol toneAmber
class node_linux_worker,node_windows_worker,node_gpu_plugins toneMint
class node_security toneRose
class node_ui_framework,node_matrix_ui,node_user toneIndigo
```

## Components

### Desktop deployment

- [Desktop app](https://github.com/darknorthaco/phantom/blob/master/phantom_app/src/App.tsx): `phantom_app/src/App.tsx`
- [Controller placement](https://github.com/darknorthaco/phantom/blob/master/phantom_app/src/components/ControllerSelectionScreen.tsx): `phantom_app/src/components/ControllerSelectionScreen.tsx`
- [Deployment ceremony](https://github.com/darknorthaco/phantom/blob/master/phantom_app/src/components/DeploymentCeremony.tsx): `phantom_app/src/components/DeploymentCeremony.tsx`
- [Ceremony state](https://github.com/darknorthaco/phantom/blob/master/phantom_app/src/state/deploymentState.ts): `phantom_app/src/state/deploymentState.ts`
- [Tauri command bridge](https://github.com/darknorthaco/phantom/blob/master/phantom_app/src/utils/tauri.ts): `phantom_app/src/utils/tauri.ts`
- [Ceremony orchestration](https://github.com/darknorthaco/phantom/blob/master/phantom_app/src-tauri/src/backend/ceremony/orchestrator.rs): `phantom_app/src-tauri/src/backend/ceremony/orchestrator.rs`
- [Deployment operations](https://github.com/darknorthaco/phantom/blob/master/phantom_app/src-tauri/src/backend/phantom_deployer.rs): `phantom_app/src-tauri/src/backend/phantom_deployer.rs`
- [Legacy installers](https://github.com/darknorthaco/phantom/tree/master/installer): `installer`

### Distributed engine

- [Controller API](https://github.com/darknorthaco/phantom/blob/master/phantom_core/phantom_core/controller_api.py): `phantom_core/phantom_core/controller_api.py`
- [Task orchestrator](https://github.com/darknorthaco/phantom/blob/master/phantom_core/phantom_core/orchestrator.py): `phantom_core/phantom_core/orchestrator.py`
- [LLM task pipeline](https://github.com/darknorthaco/phantom/blob/master/phantom_core/llm_taskmaster/pipeline.py): `phantom_core/llm_taskmaster/pipeline.py`
- [Socket integration](https://github.com/darknorthaco/phantom/blob/master/phantom_core/phantom_core/socket_integration.py): `phantom_core/phantom_core/socket_integration.py`
- [Protocol transports](https://github.com/darknorthaco/phantom/tree/master/phantom_core/phantom_protocol): `phantom_core/phantom_protocol`

### Worker execution

- [Linux worker](https://github.com/darknorthaco/phantom/blob/master/phantom_core/linux-worker/linux_worker/worker.py): `phantom_core/linux-worker/linux_worker/worker.py`
- [Windows worker](https://github.com/darknorthaco/phantom/blob/master/phantom_core/windows-worker/windows_worker/worker.py): `phantom_core/windows-worker/windows_worker/worker.py`
- [GPU plugin manager](https://github.com/darknorthaco/phantom/blob/master/phantom_core/linux-worker/plugins/plugin_manager.py): `phantom_core/linux-worker/plugins/plugin_manager.py`

### Security and trust

- [Integrated security](https://github.com/darknorthaco/phantom/blob/master/phantom_core/security_framework/integrated_security.py): `phantom_core/security_framework/integrated_security.py`

### Interfaces

- [Swappable UI framework](https://github.com/darknorthaco/phantom/blob/master/ui/ui_framework/ui_manager.py): `ui/ui_framework/ui_manager.py`
- [Matrix interface](https://github.com/darknorthaco/phantom/blob/master/ui/redblue_matrix/phantom-matrix-android/App.js): `ui/redblue_matrix/phantom-matrix-android/App.js`

### Other components

- **Operator**

## Connections

- Operator → Desktop app: uses (evidence: `README.md`)
- Desktop app → Controller placement: renders (evidence: `phantom_app/src/App.tsx`)
- Desktop app → Deployment ceremony: renders (evidence: `phantom_app/src/App.tsx`)
- Controller placement → Tauri command bridge: confirms placement (evidence: `phantom_app/src/components/ControllerSelectionScreen.tsx`)
- Desktop app → Tauri command bridge: checks health (evidence: `phantom_app/src/App.tsx`)
- Deployment ceremony → Ceremony state: uses ceremony data
- Tauri command bridge → Ceremony orchestration: invokes commands
- Ceremony orchestration → Deployment operations: coordinates deployment
- Controller API → Task orchestrator: initializes (evidence: `phantom_core/phantom_core/controller_api.py`)
- Linux worker → GPU plugin manager: initializes plugins (evidence: `phantom_core/linux-worker/linux_worker/worker.py`)
- Linux worker → Socket integration: uses socket layer (evidence: `phantom_core/linux-worker/linux_worker/worker.py`)
- Windows worker → Socket integration: uses socket layer (evidence: `phantom_core/windows-worker/windows_worker/worker.py`)
- Controller API → Integrated security: initializes security (evidence: `phantom_core/phantom_core/controller_api.py`)
- Controller API → Socket integration: uses socket layer (evidence: `phantom_core/phantom_core/controller_api.py`)
- Task orchestrator → LLM task pipeline: routes work
- Controller API → Protocol transports: communicates through
- Operator → Matrix interface: uses (evidence: `README.md`)
- Matrix interface → Swappable UI framework: uses framework
- Operator → Legacy installers: opts into (evidence: `README.md`)
