# light-heart-labs/dreamserver architecture

> Architecture diagram of the GitHub repository light-heart-labs/dreamserver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/light-heart-labs/dreamserver
- Repository: https://github.com/light-heart-labs/dreamserver

## Overview

ODS is a cross-platform installer and local AI-server platform. The main user journey is: install and configure the stack, manage hardware/models and services in Portal, then use the web interfaces and agent workflows against local inference; optional remote providers and cloud APIs extend that runtime. The graph includes documented product capabilities whose implementation was not sampled, using supported enclosing paths. Source excerpts are partial, so uncertain internal wiring is omitted.

Main entry points: [`ods/extensions/services/model-router/app/main.py`](https://github.com/light-heart-labs/dreamserver/blob/main/ods/extensions/services/model-router/app/main.py) (Model router), [`ods/extensions/services/dashboard-api/main.py`](https://github.com/light-heart-labs/dreamserver/blob/main/ods/extensions/services/dashboard-api/main.py) (Dashboard API), [`ods/extensions/services/dashboard/src/App.jsx`](https://github.com/light-heart-labs/dreamserver/blob/main/ods/extensions/services/dashboard/src/App.jsx) (Portal dashboard), [`ods/extensions/services/pixel-agent`](https://github.com/light-heart-labs/dreamserver/tree/main/ods/extensions/services/pixel-agent) (Pixel agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Installation"]
  node_installer["Setup wizard<br/>[App.tsx]"]
  node_native_setup["Platform setup<br/>[installer.rs]"]
end

subgraph group_portal["Portal and API"]
  node_dashboard["Portal dashboard<br/>[App.jsx]"]
  node_api["Dashboard API<br/>[main.py]"]
  node_model_routes["Route evidence<br/>[model_routes.py]"]
  node_pixel_api["Pixel API<br/>[pixel.py]"]
  node_extension_catalog["Extension catalog<br/>[extensions.py]"]
end

subgraph group_inference["Models and Inference"]
  node_model_ui["Model router<br/>[main.py]"]
  node_host_agent["Host agent<br/>[ods-host-agent.py]"]
  node_switchboard["Model switchboard"]
end

subgraph group_pixel["Pixel and Agents"]
  node_pixel_ui["Pixel interface"]
  node_pixel_agent["Pixel agent"]
  node_policy_engine["Agent policy<br/>[main.py]"]
  node_extension_manager["Extension lifecycle"]
end

subgraph group_services["Stack Capabilities"]
  node_service_library["AI and homelab services"]
  node_token_proxy["Token Spy<br/>[main.py]"]
  node_sharing["Inference sharing<br/>[main.py]"]
  node_remote_provider["Remote providers"]
end

node_operator(("Operator"))
node_browser(("Browser user"))
node_inference_backend["Inference backend"]

node_operator -->|"starts setup"| node_installer
node_installer -->|"runs install"| node_native_setup
node_browser -->|"opens Portal"| node_dashboard
node_dashboard -->|"requests management"| node_api
node_api -->|"checks host"| node_host_agent
node_api -->|"serves route evidence"| node_model_routes
node_model_routes -->|"fetches evidence"| node_model_ui
node_dashboard -->|"opens Pixel"| node_pixel_ui
node_pixel_ui -->|"requests Pixel services"| node_pixel_api
node_pixel_api -->|"exposes agent features"| node_pixel_agent
node_pixel_agent -->|"checks tool policy"| node_policy_engine
node_pixel_agent -->|"manages extensions"| node_extension_manager
node_api -->|"serves extension management"| node_extension_catalog
node_model_ui -->|"reads model state"| node_host_agent
node_model_ui -->|"forwards inference"| node_inference_backend
node_host_agent -->|"coordinates model state"| node_switchboard
node_browser -->|"uses installed services"| node_service_library
node_token_proxy -.->|"proxies API requests"| node_inference_backend
node_sharing -.->|"forwards inference"| node_model_ui
node_remote_provider -.->|"enables remote routes"| node_model_ui

click node_installer "https://github.com/light-heart-labs/dreamserver/blob/main/installer/src/App.tsx"
click node_native_setup "https://github.com/light-heart-labs/dreamserver/blob/main/installer/src-tauri/src/installer.rs"
click node_dashboard "https://github.com/light-heart-labs/dreamserver/blob/main/ods/extensions/services/dashboard/src/App.jsx"
click node_api "https://github.com/light-heart-labs/dreamserver/blob/main/ods/extensions/services/dashboard-api/main.py"
click node_model_routes "https://github.com/light-heart-labs/dreamserver/blob/main/ods/extensions/services/dashboard-api/routers/model_routes.py"
click node_model_ui "https://github.com/light-heart-labs/dreamserver/blob/main/ods/extensions/services/model-router/app/main.py"
click node_host_agent "https://github.com/light-heart-labs/dreamserver/blob/main/ods/bin/ods-host-agent.py"
click node_switchboard "https://github.com/light-heart-labs/dreamserver/tree/main/ods/bin/model_switchboard"
click node_pixel_ui "https://github.com/light-heart-labs/dreamserver/tree/main/ods/extensions/services/dashboard/src/components"
click node_pixel_api "https://github.com/light-heart-labs/dreamserver/blob/main/ods/extensions/services/dashboard-api/routers/pixel.py"
click node_pixel_agent "https://github.com/light-heart-labs/dreamserver/tree/main/ods/extensions/services/pixel-agent"
click node_policy_engine "https://github.com/light-heart-labs/dreamserver/blob/main/ods/extensions/services/ape/main.py"
click node_extension_manager "https://github.com/light-heart-labs/dreamserver/blob/main/ods/extensions/services/pixel-agent/host/extension_manager.py"
click node_extension_catalog "https://github.com/light-heart-labs/dreamserver/blob/main/ods/extensions/services/dashboard-api/routers/extensions.py"
click node_service_library "https://github.com/light-heart-labs/dreamserver/tree/main/ods/extensions"
click node_token_proxy "https://github.com/light-heart-labs/dreamserver/blob/main/ods/extensions/services/token-spy/main.py"
click node_sharing "https://github.com/light-heart-labs/dreamserver/blob/main/ods/extensions/services/pixel-inference/app/main.py"
click node_remote_provider "https://github.com/light-heart-labs/dreamserver/tree/main/ods/bin/remote_provider"

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_installer,node_native_setup,node_browser toneBlue
class node_dashboard,node_api,node_model_routes,node_pixel_api,node_extension_catalog toneAmber
class node_model_ui,node_host_agent,node_switchboard toneMint
class node_pixel_ui,node_pixel_agent,node_policy_engine,node_extension_manager toneRose
class node_service_library,node_token_proxy,node_sharing,node_remote_provider,node_operator,node_inference_backend toneIndigo
```

## Components

### Installation

- [Setup wizard](https://github.com/light-heart-labs/dreamserver/blob/main/installer/src/App.tsx): `installer/src/App.tsx`
- [Platform setup](https://github.com/light-heart-labs/dreamserver/blob/main/installer/src-tauri/src/installer.rs): `installer/src-tauri/src/installer.rs`

### Portal and API

- [Portal dashboard](https://github.com/light-heart-labs/dreamserver/blob/main/ods/extensions/services/dashboard/src/App.jsx): `ods/extensions/services/dashboard/src/App.jsx`
- [Dashboard API](https://github.com/light-heart-labs/dreamserver/blob/main/ods/extensions/services/dashboard-api/main.py): `ods/extensions/services/dashboard-api/main.py`
- [Route evidence](https://github.com/light-heart-labs/dreamserver/blob/main/ods/extensions/services/dashboard-api/routers/model_routes.py): `ods/extensions/services/dashboard-api/routers/model_routes.py`
- [Pixel API](https://github.com/light-heart-labs/dreamserver/blob/main/ods/extensions/services/dashboard-api/routers/pixel.py): `ods/extensions/services/dashboard-api/routers/pixel.py`
- [Extension catalog](https://github.com/light-heart-labs/dreamserver/blob/main/ods/extensions/services/dashboard-api/routers/extensions.py): `ods/extensions/services/dashboard-api/routers/extensions.py`

### Models and Inference

- [Model router](https://github.com/light-heart-labs/dreamserver/blob/main/ods/extensions/services/model-router/app/main.py): `ods/extensions/services/model-router/app/main.py`
- [Host agent](https://github.com/light-heart-labs/dreamserver/blob/main/ods/bin/ods-host-agent.py): `ods/bin/ods-host-agent.py`
- [Model switchboard](https://github.com/light-heart-labs/dreamserver/tree/main/ods/bin/model_switchboard): `ods/bin/model_switchboard`

### Pixel and Agents

- [Pixel interface](https://github.com/light-heart-labs/dreamserver/tree/main/ods/extensions/services/dashboard/src/components): `ods/extensions/services/dashboard/src/components`
- [Pixel agent](https://github.com/light-heart-labs/dreamserver/tree/main/ods/extensions/services/pixel-agent): `ods/extensions/services/pixel-agent`
- [Agent policy](https://github.com/light-heart-labs/dreamserver/blob/main/ods/extensions/services/ape/main.py): `ods/extensions/services/ape/main.py`
- [Extension lifecycle](https://github.com/light-heart-labs/dreamserver/blob/main/ods/extensions/services/pixel-agent/host/extension_manager.py): `ods/extensions/services/pixel-agent/host/extension_manager.py`

### Stack Capabilities

- [AI and homelab services](https://github.com/light-heart-labs/dreamserver/tree/main/ods/extensions): `ods/extensions`
- [Token Spy](https://github.com/light-heart-labs/dreamserver/blob/main/ods/extensions/services/token-spy/main.py): `ods/extensions/services/token-spy/main.py`
- [Inference sharing](https://github.com/light-heart-labs/dreamserver/blob/main/ods/extensions/services/pixel-inference/app/main.py): `ods/extensions/services/pixel-inference/app/main.py`
- [Remote providers](https://github.com/light-heart-labs/dreamserver/tree/main/ods/bin/remote_provider): `ods/bin/remote_provider`

### Other components

- **Operator**
- **Browser user**
- **Inference backend**

## Connections

- Operator → Setup wizard: starts setup
- Setup wizard → Platform setup: runs install
- Browser user → Portal dashboard: opens Portal
- Portal dashboard → Dashboard API: requests management
- Dashboard API → Host agent: checks host
- Dashboard API → Route evidence: serves route evidence
- Route evidence → Model router: fetches evidence
- Portal dashboard → Pixel interface: opens Pixel
- Pixel interface → Pixel API: requests Pixel services
- Pixel API → Pixel agent: exposes agent features
- Pixel agent → Agent policy: checks tool policy
- Pixel agent → Extension lifecycle: manages extensions
- Dashboard API → Extension catalog: serves extension management
- Model router → Host agent: reads model state
- Model router → Inference backend: forwards inference
- Host agent → Model switchboard: coordinates model state
- Browser user → AI and homelab services: uses installed services
- Token Spy → Inference backend: proxies API requests
- Inference sharing → Model router: forwards inference
- Remote providers → Model router: enables remote routes