# rwilliamspbg-ops/ghostlink architecture

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

- Interactive diagram: https://gitdiagram.com/rwilliamspbg-ops/ghostlink
- Repository: https://github.com/rwilliamspbg-ops/ghostlink

## Overview

Ghostlink is a self-hosted distributed inference fabric for heterogeneous LAN hardware, with an OpenAI-compatible API and a Studio UI. The main workflow is a user submitting a chat request through the UI or API; the backend runs inference locally or uses LAN peers, then returns the result. Separate product branches cover cluster visibility and management, MCP tools, and developer SDKs. The README documents the product flow and capabilities; sampled source and the SOURCE INDEX clarify selected UI, gateway, inference, and core relationships, but many backend routes remain unsampled.

Main entry points: [`crates/ghost-link/src/main.rs`](https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/ghost-link/src/main.rs) (Inference API), [`ghostlink_gui_modern/src/App.tsx`](https://github.com/rwilliamspbg-ops/ghostlink/blob/main/ghostlink_gui_modern/src/App.tsx) (Studio application), [`crates/ghost-link/src/mcp/registry.rs`](https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/ghost-link/src/mcp/registry.rs) (MCP tool registry), [`ghostlink_gui_modern/src/api.ts`](https://github.com/rwilliamspbg-ops/ghostlink/blob/main/ghostlink_gui_modern/src/api.ts) (UI API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_studio["Studio application<br/>[App.tsx]"]
  node_chat["Chat workspace<br/>[ChatTab.tsx]"]
  node_models["Model controls<br/>[ModelsTab.tsx]"]
  node_workers["Cluster dashboard<br/>[WorkersTab.tsx]"]
  node_uiapi["UI API client<br/>[api.ts]"]
end

subgraph group_serving["Inference serving"]
  node_gateway["Control-plane gateway<br/>[main.go]"]
  node_backend["Inference API<br/>[main.rs]"]
  node_native["Native engine adapter<br/>[native_engine.rs]"]
  node_ollama["Ollama engine<br/>[ollama.rs]"]
  node_vllm["vLLM engine<br/>[vllm.rs]"]
end

subgraph group_fabric["Cluster fabric"]
  node_discovery["Peer discovery<br/>[discovery.rs]"]
  node_planning["Placement planning<br/>[planning.rs]"]
  node_cluster["Cluster coordination<br/>[cluster.rs]"]
  node_rpc["RPC model sharding<br/>[rpc_cluster.rs]"]
  node_protocol["Cluster protocol<br/>[protocol.rs]"]
end

subgraph group_extensions["Tools and integrations"]
  node_mcp["MCP tool registry<br/>[registry.rs]"]
  node_memory["Durable memory tool<br/>[main.rs]"]
  node_rag["RAG tool server<br/>[main.rs]"]
  node_vision["Vision tool server<br/>[main.rs]"]
end

subgraph group_clients["Client access"]
  node_jsclient["JavaScript SDK<br/>[client.ts]"]
  node_pyclient["Python SDK<br/>[client.py]"]
end

node_user(("User"))
node_llama["llama.cpp server"]
node_apiuser(("API consumer"))

node_user -->|"uses"| node_studio
node_studio -->|"renders"| node_chat
node_studio -->|"renders"| node_models
node_studio -->|"renders"| node_workers
node_chat -->|"requests"| node_uiapi
node_models -.->|"requests"| node_uiapi
node_workers -->|"requests"| node_uiapi
node_uiapi -->|"HTTP requests"| node_gateway
node_gateway -->|"proxies requests"| node_backend
node_apiuser -->|"submits requests"| node_backend
node_backend -.->|"dispatches inference"| node_native
node_native -->|"sends generation requests"| node_llama
node_native -->|"uses cluster adapter"| node_rpc
node_backend -.->|"supports engine"| node_ollama
node_backend -.->|"supports engine"| node_vllm
node_discovery -->|"forms LAN cluster"| node_cluster
node_planning -->|"plans placement"| node_cluster
node_cluster -->|"uses messages"| node_protocol
node_planning -->|"uses protocol types"| node_protocol
node_rpc -->|"distributes inference"| node_cluster
node_studio -.->|"configures tools"| node_mcp
node_mcp -.->|"connects tool server"| node_memory
node_mcp -.->|"connects tool server"| node_rag
node_mcp -.->|"connects tool server"| node_vision
node_apiuser -->|"uses SDK"| node_jsclient
node_apiuser -.->|"uses SDK"| node_pyclient
node_jsclient -->|"calls API"| node_backend
node_pyclient -.->|"calls API"| node_backend

click node_studio "https://github.com/rwilliamspbg-ops/ghostlink/blob/main/ghostlink_gui_modern/src/App.tsx"
click node_chat "https://github.com/rwilliamspbg-ops/ghostlink/blob/main/ghostlink_gui_modern/src/components/ChatTab.tsx"
click node_models "https://github.com/rwilliamspbg-ops/ghostlink/blob/main/ghostlink_gui_modern/src/components/ModelsTab.tsx"
click node_workers "https://github.com/rwilliamspbg-ops/ghostlink/blob/main/ghostlink_gui_modern/src/components/WorkersTab.tsx"
click node_uiapi "https://github.com/rwilliamspbg-ops/ghostlink/blob/main/ghostlink_gui_modern/src/api.ts"
click node_gateway "https://github.com/rwilliamspbg-ops/ghostlink/blob/main/control-plane/main.go"
click node_backend "https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/ghost-link/src/main.rs"
click node_native "https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/ghost-link/src/native_engine.rs"
click node_ollama "https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/ghost-link/src/ollama.rs"
click node_vllm "https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/ghost-link/src/vllm.rs"
click node_discovery "https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/ghostlink-core/src/discovery.rs"
click node_planning "https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/ghostlink-core/src/planning.rs"
click node_cluster "https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/ghostlink-core/src/cluster.rs"
click node_rpc "https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/ghost-link/src/rpc_cluster.rs"
click node_protocol "https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/ghostlink-core/src/protocol.rs"
click node_mcp "https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/ghost-link/src/mcp/registry.rs"
click node_memory "https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/mcp-memory/src/main.rs"
click node_rag "https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/mcp-rag/src/main.rs"
click node_vision "https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/mcp-vision/src/main.rs"
click node_jsclient "https://github.com/rwilliamspbg-ops/ghostlink/blob/main/sdks/js/src/client.ts"
click node_pyclient "https://github.com/rwilliamspbg-ops/ghostlink/blob/main/sdks/python/ghostlink_client/client.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_studio,node_chat,node_models,node_workers,node_uiapi,node_user toneBlue
class node_gateway,node_backend,node_native,node_ollama,node_vllm toneAmber
class node_discovery,node_planning,node_cluster,node_rpc,node_protocol,node_llama,node_apiuser toneMint
class node_mcp,node_memory,node_rag,node_vision toneRose
class node_jsclient,node_pyclient toneIndigo
```

## Components

### User interfaces

- [Studio application](https://github.com/rwilliamspbg-ops/ghostlink/blob/main/ghostlink_gui_modern/src/App.tsx): `ghostlink_gui_modern/src/App.tsx`
- [Chat workspace](https://github.com/rwilliamspbg-ops/ghostlink/blob/main/ghostlink_gui_modern/src/components/ChatTab.tsx): `ghostlink_gui_modern/src/components/ChatTab.tsx`
- [Model controls](https://github.com/rwilliamspbg-ops/ghostlink/blob/main/ghostlink_gui_modern/src/components/ModelsTab.tsx): `ghostlink_gui_modern/src/components/ModelsTab.tsx`
- [Cluster dashboard](https://github.com/rwilliamspbg-ops/ghostlink/blob/main/ghostlink_gui_modern/src/components/WorkersTab.tsx): `ghostlink_gui_modern/src/components/WorkersTab.tsx`
- [UI API client](https://github.com/rwilliamspbg-ops/ghostlink/blob/main/ghostlink_gui_modern/src/api.ts): `ghostlink_gui_modern/src/api.ts`

### Inference serving

- [Control-plane gateway](https://github.com/rwilliamspbg-ops/ghostlink/blob/main/control-plane/main.go): `control-plane/main.go`
- [Inference API](https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/ghost-link/src/main.rs): `crates/ghost-link/src/main.rs`
- [Native engine adapter](https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/ghost-link/src/native_engine.rs): `crates/ghost-link/src/native_engine.rs`
- [Ollama engine](https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/ghost-link/src/ollama.rs): `crates/ghost-link/src/ollama.rs`
- [vLLM engine](https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/ghost-link/src/vllm.rs): `crates/ghost-link/src/vllm.rs`

### Cluster fabric

- [Peer discovery](https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/ghostlink-core/src/discovery.rs): `crates/ghostlink-core/src/discovery.rs`
- [Placement planning](https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/ghostlink-core/src/planning.rs): `crates/ghostlink-core/src/planning.rs`
- [Cluster coordination](https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/ghostlink-core/src/cluster.rs): `crates/ghostlink-core/src/cluster.rs`
- [RPC model sharding](https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/ghost-link/src/rpc_cluster.rs): `crates/ghost-link/src/rpc_cluster.rs`
- [Cluster protocol](https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/ghostlink-core/src/protocol.rs): `crates/ghostlink-core/src/protocol.rs`

### Tools and integrations

- [MCP tool registry](https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/ghost-link/src/mcp/registry.rs): `crates/ghost-link/src/mcp/registry.rs`
- [Durable memory tool](https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/mcp-memory/src/main.rs): `crates/mcp-memory/src/main.rs`
- [RAG tool server](https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/mcp-rag/src/main.rs): `crates/mcp-rag/src/main.rs`
- [Vision tool server](https://github.com/rwilliamspbg-ops/ghostlink/blob/main/crates/mcp-vision/src/main.rs): `crates/mcp-vision/src/main.rs`

### Client access

- [JavaScript SDK](https://github.com/rwilliamspbg-ops/ghostlink/blob/main/sdks/js/src/client.ts): `sdks/js/src/client.ts`
- [Python SDK](https://github.com/rwilliamspbg-ops/ghostlink/blob/main/sdks/python/ghostlink_client/client.py): `sdks/python/ghostlink_client/client.py`

### Other components

- **User**
- **llama.cpp server**
- **API consumer**

## Connections

- User → Studio application: uses (evidence: `README.md`)
- Studio application → Chat workspace: renders (evidence: `ghostlink_gui_modern/src/App.tsx`)
- Studio application → Model controls: renders (evidence: `ghostlink_gui_modern/src/App.tsx`)
- Studio application → Cluster dashboard: renders (evidence: `ghostlink_gui_modern/src/App.tsx`)
- Chat workspace → UI API client: requests (evidence: `ghostlink_gui_modern/src/components/ChatTab.tsx`)
- Model controls → UI API client: requests
- Cluster dashboard → UI API client: requests (evidence: `ghostlink_gui_modern/src/components/WorkersTab.tsx`)
- UI API client → Control-plane gateway: HTTP requests (evidence: `README.md`)
- Control-plane gateway → Inference API: proxies requests (evidence: `control-plane/main.go`)
- API consumer → Inference API: submits requests (evidence: `README.md`)
- Inference API → Native engine adapter: dispatches inference
- Native engine adapter → llama.cpp server: sends generation requests (evidence: `crates/ghost-link/src/native_engine.rs`)
- Native engine adapter → RPC model sharding: uses cluster adapter (evidence: `crates/ghost-link/src/native_engine.rs`)
- Inference API → Ollama engine: supports engine
- Inference API → vLLM engine: supports engine
- Peer discovery → Cluster coordination: forms LAN cluster (evidence: `README.md`)
- Placement planning → Cluster coordination: plans placement (evidence: `crates/ghostlink-core/src/planning.rs`)
- Cluster coordination → Cluster protocol: uses messages (evidence: `crates/ghostlink-core/src/cluster.rs`)
- Placement planning → Cluster protocol: uses protocol types (evidence: `crates/ghostlink-core/src/planning.rs`)
- RPC model sharding → Cluster coordination: distributes inference (evidence: `README.md`)
- Studio application → MCP tool registry: configures tools
- MCP tool registry → Durable memory tool: connects tool server
- MCP tool registry → RAG tool server: connects tool server
- MCP tool registry → Vision tool server: connects tool server
- API consumer → JavaScript SDK: uses SDK (evidence: `sdks/js/src/client.ts`)
- API consumer → Python SDK: uses SDK
- JavaScript SDK → Inference API: calls API (evidence: `sdks/js/src/client.ts`)
- Python SDK → Inference API: calls API
