# timmo001/system-bridge architecture

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

- Interactive diagram: https://gitdiagram.com/timmo001/system-bridge
- Repository: https://github.com/timmo001/system-bridge

## Overview

System Bridge is a cross-platform system monitoring and control service, with a web client and API/WebSocket access. Its main workflow is: collect platform data into named modules, expose it to authenticated clients, and route control requests to system actions. The README also identifies MCP, Home Assistant integration, discovery, tray controls, and an optional Omarchy plugin. The graph reflects sampled wiring where available; some backend routes and integrations are represented at their documented subsystem boundary because their implementation was not sampled.

Main entry points: [`data/data.go`](https://github.com/timmo001/system-bridge/blob/dev/data/data.go) (Data registry), [`main.go`](https://github.com/timmo001/system-bridge/blob/dev/main.go) (Application runtime), [`backend/backend.go`](https://github.com/timmo001/system-bridge/blob/dev/backend/backend.go) (Backend server), [`backend/websocket/websocket.go`](https://github.com/timmo001/system-bridge/blob/dev/backend/websocket/websocket.go) (WebSocket service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["Application runtime<br/>[main.go]"]
  node_settings[("Settings and token<br/>[settings.go]")]
  node_tray["System tray<br/>[tray.go]"]
end

subgraph group_collection["System data"]
  node_datastore[("Data registry<br/>[data.go]")]
  node_modules["Platform data modules"]
  node_types["Module data types<br/>[module.go]"]
  node_bus["Update event bus<br/>[bus.go]"]
end

subgraph group_interfaces["Client interfaces"]
  node_backend["Backend server<br/>[backend.go]"]
  node_http["HTTP API<br/>[api.go]"]
  node_websocket["WebSocket service<br/>[websocket.go]"]
  node_mcp["MCP service<br/>[server.go]"]
  node_discovery["Network discovery<br/>[discovery.go]"]
end

subgraph group_controls["Controls"]
  node_router["Event router<br/>[event.go]"]
  node_handlers["Request handlers<br/>[handler.go]"]
  node_systemactions["System actions"]
end

subgraph group_client["Web client"]
  node_webapp["Web application<br/>[app.ts]"]
  node_provider["App state provider<br/>[app-provider.ts]"]
  node_wscontroller["WebSocket controller"]
  node_pages["Client pages"]
end

node_user(("Operator / client"))
node_homeassistant["Home Assistant connector"]
node_omarchy["Omarchy bar plugin"]

node_main -->|"loads configuration"| node_settings
node_main -->|"creates registry"| node_datastore
node_main -->|"starts service"| node_backend
node_main -->|"starts tray"| node_tray
node_datastore -->|"registers and updates"| node_modules
node_datastore -->|"stores module data"| node_types
node_datastore -->|"publishes updates"| node_bus
node_backend -->|"serves API"| node_http
node_backend -->|"serves socket"| node_websocket
node_backend -->|"serves MCP"| node_mcp
node_websocket -->|"receives updates"| node_bus
node_http -->|"routes requests"| node_router
node_websocket -->|"dispatches messages"| node_router
node_mcp -->|"reads module data"| node_datastore
node_mcp -->|"dispatches controls"| node_router
node_router -->|"dispatches events"| node_handlers
node_handlers -->|"requests data"| node_datastore
node_handlers -->|"invokes actions"| node_systemactions
node_main -->|"starts discovery"| node_discovery
node_user -->|"uses"| node_webapp
node_webapp -->|"renders within"| node_provider
node_provider -->|"manages connection"| node_wscontroller
node_wscontroller -->|"sends requests"| node_websocket
node_webapp -->|"routes to"| node_pages
node_homeassistant -.->|"connects through API"| node_http
node_homeassistant -.->|"connects through socket"| node_websocket
node_omarchy -.->|"optional integration"| node_backend

click node_main "https://github.com/timmo001/system-bridge/blob/dev/main.go"
click node_settings "https://github.com/timmo001/system-bridge/blob/dev/settings/settings.go"
click node_tray "https://github.com/timmo001/system-bridge/blob/dev/tray/tray.go"
click node_datastore "https://github.com/timmo001/system-bridge/blob/dev/data/data.go"
click node_modules "https://github.com/timmo001/system-bridge/tree/dev/data/module"
click node_types "https://github.com/timmo001/system-bridge/blob/dev/types/module.go"
click node_bus "https://github.com/timmo001/system-bridge/blob/dev/bus/bus.go"
click node_backend "https://github.com/timmo001/system-bridge/blob/dev/backend/backend.go"
click node_http "https://github.com/timmo001/system-bridge/blob/dev/backend/http/api.go"
click node_websocket "https://github.com/timmo001/system-bridge/blob/dev/backend/websocket/websocket.go"
click node_mcp "https://github.com/timmo001/system-bridge/blob/dev/backend/mcp/server.go"
click node_router "https://github.com/timmo001/system-bridge/blob/dev/event/event.go"
click node_handlers "https://github.com/timmo001/system-bridge/blob/dev/event/handler/handler.go"
click node_systemactions "https://github.com/timmo001/system-bridge/tree/dev/utils/handlers"
click node_discovery "https://github.com/timmo001/system-bridge/blob/dev/discovery/discovery.go"
click node_webapp "https://github.com/timmo001/system-bridge/blob/dev/web-client/src/app.ts"
click node_provider "https://github.com/timmo001/system-bridge/blob/dev/web-client/src/components/app-provider.ts"
click node_wscontroller "https://github.com/timmo001/system-bridge/blob/dev/web-client/src/controllers/websocket-controller.ts"
click node_pages "https://github.com/timmo001/system-bridge/tree/dev/web-client/src/pages"

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,node_settings,node_tray,node_user toneBlue
class node_datastore,node_modules,node_types,node_bus toneAmber
class node_backend,node_http,node_websocket,node_mcp,node_discovery toneMint
class node_router,node_handlers,node_systemactions toneRose
class node_webapp,node_provider,node_wscontroller,node_pages,node_homeassistant,node_omarchy toneIndigo
```

## Components

### Runtime

- [Application runtime](https://github.com/timmo001/system-bridge/blob/dev/main.go): `main.go`
- [Settings and token](https://github.com/timmo001/system-bridge/blob/dev/settings/settings.go): `settings/settings.go`
- [System tray](https://github.com/timmo001/system-bridge/blob/dev/tray/tray.go): `tray/tray.go`

### System data

- [Data registry](https://github.com/timmo001/system-bridge/blob/dev/data/data.go): `data/data.go`
- [Platform data modules](https://github.com/timmo001/system-bridge/tree/dev/data/module): `data/module`
- [Module data types](https://github.com/timmo001/system-bridge/blob/dev/types/module.go): `types/module.go`
- [Update event bus](https://github.com/timmo001/system-bridge/blob/dev/bus/bus.go): `bus/bus.go`

### Client interfaces

- [Backend server](https://github.com/timmo001/system-bridge/blob/dev/backend/backend.go): `backend/backend.go`
- [HTTP API](https://github.com/timmo001/system-bridge/blob/dev/backend/http/api.go): `backend/http/api.go`
- [WebSocket service](https://github.com/timmo001/system-bridge/blob/dev/backend/websocket/websocket.go): `backend/websocket/websocket.go`
- [MCP service](https://github.com/timmo001/system-bridge/blob/dev/backend/mcp/server.go): `backend/mcp/server.go`
- [Network discovery](https://github.com/timmo001/system-bridge/blob/dev/discovery/discovery.go): `discovery/discovery.go`

### Controls

- [Event router](https://github.com/timmo001/system-bridge/blob/dev/event/event.go): `event/event.go`
- [Request handlers](https://github.com/timmo001/system-bridge/blob/dev/event/handler/handler.go): `event/handler/handler.go`
- [System actions](https://github.com/timmo001/system-bridge/tree/dev/utils/handlers): `utils/handlers`

### Web client

- [Web application](https://github.com/timmo001/system-bridge/blob/dev/web-client/src/app.ts): `web-client/src/app.ts`
- [App state provider](https://github.com/timmo001/system-bridge/blob/dev/web-client/src/components/app-provider.ts): `web-client/src/components/app-provider.ts`
- [WebSocket controller](https://github.com/timmo001/system-bridge/blob/dev/web-client/src/controllers/websocket-controller.ts): `web-client/src/controllers/websocket-controller.ts`
- [Client pages](https://github.com/timmo001/system-bridge/tree/dev/web-client/src/pages): `web-client/src/pages`

### Other components

- **Operator / client**
- **Home Assistant connector**
- **Omarchy bar plugin**

## Connections

- Application runtime → Settings and token: loads configuration
- Application runtime → Data registry: creates registry
- Application runtime → Backend server: starts service
- Application runtime → System tray: starts tray
- Data registry → Platform data modules: registers and updates
- Data registry → Module data types: stores module data
- Data registry → Update event bus: publishes updates
- Backend server → HTTP API: serves API
- Backend server → WebSocket service: serves socket
- Backend server → MCP service: serves MCP
- WebSocket service → Update event bus: receives updates
- HTTP API → Event router: routes requests
- WebSocket service → Event router: dispatches messages
- MCP service → Data registry: reads module data
- MCP service → Event router: dispatches controls
- Event router → Request handlers: dispatches events
- Request handlers → Data registry: requests data
- Request handlers → System actions: invokes actions
- Application runtime → Network discovery: starts discovery
- Operator / client → Web application: uses
- Web application → App state provider: renders within
- App state provider → WebSocket controller: manages connection
- WebSocket controller → WebSocket service: sends requests
- Web application → Client pages: routes to
- Home Assistant connector → HTTP API: connects through API
- Home Assistant connector → WebSocket service: connects through socket
- Omarchy bar plugin → Backend server: optional integration