# d-buckner/bloud architecture

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

- Interactive diagram: https://gitdiagram.com/d-buckner/bloud
- Repository: https://github.com/d-buckner/bloud

## Overview

Bloud is a self-hosted home-server manager: a user installs apps through its dashboard, while a reconciliation engine resolves dependencies, starts containers, configures integrations and proxy routes, and verifies apps through their APIs. Its major product branches include catalog-driven app setup, unified login, media-stack wiring, dashboard settings and widgets, and sharing. The README documents the control-loop workflow; sampled Go excerpts show server construction and API-client behavior. Several subsystem paths are directory-level because their implementation files were not sampled.

Main entry points: [`services/host-agent/internal/engine/orchestrator`](https://github.com/d-buckner/bloud/tree/main/services/host-agent/internal/engine/orchestrator) (Reconciliation engine), [`services/host-agent/internal/api`](https://github.com/d-buckner/bloud/tree/main/services/host-agent/internal/api) (HTTP API), [`apps`](https://github.com/d-buckner/bloud/tree/main/apps) (App configurators), [`services/host-agent/pkg/appclient`](https://github.com/d-buckner/bloud/tree/main/services/host-agent/pkg/appclient) (App API clients)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Dashboard"]
  node_dashboard_ui["Dashboard UI"]
  node_web_clients["Web API clients"]
end

subgraph group_control["Control plane"]
  node_http_api["HTTP API"]
  node_catalog["App catalog"]
  node_orchestrator["Reconciliation engine"]
  node_dependency_graph["Dependency graph"]
  node_host_agent["Host-agent startup<br/>[main.go]"]
end

subgraph group_runtime["App runtime"]
  node_app_config["App configurators"]
  node_container_runtime["Container runtime"]
  node_podman["Podman client"]
  node_app_api_clients["App API clients"]
  node_affine_setup["AFFiNE setup<br/>[api.go]"]
  node_configtest["Configurator checks<br/>[configtest.go]"]
end

subgraph group_integrations["Integrations"]
  node_authentik["Authentik integration<br/>[client.go]"]
  node_proxy_config["Proxy configuration"]
  node_sharing["Sharing and tailnet"]
  node_media_wiring["Media-stack wiring<br/>[jellyfin.go]"]
  node_authentik_setup["Authentik setup"]
  node_servarr_client["Download-client support<br/>[downloadclient.go]"]
end

subgraph group_state["State and operations"]
  node_database[("Persistent state")]
  node_event_bus["Event streams"]
end

node_user(("Home-server user"))

node_user -->|"manages apps"| node_dashboard_ui
node_dashboard_ui -.->|"uses clients"| node_web_clients
node_web_clients -.->|"sends requests"| node_http_api
node_http_api -->|"submits intents"| node_orchestrator
node_orchestrator -->|"resolves apps"| node_catalog
node_orchestrator -->|"orders dependencies"| node_dependency_graph
node_orchestrator -->|"reconciles containers"| node_container_runtime
node_container_runtime -.->|"controls containers"| node_podman
node_orchestrator -->|"runs configurators"| node_app_config
node_app_config -->|"verifies apps"| node_app_api_clients
node_orchestrator -->|"writes routes"| node_proxy_config
node_orchestrator -->|"configures identity"| node_authentik
node_app_config -.->|"sets up identity"| node_authentik
node_orchestrator -->|"converges sharing"| node_sharing
node_orchestrator -.->|"wires app stack"| node_media_wiring
node_media_wiring -.->|"configures download clients"| node_servarr_client
node_http_api -.->|"reads and writes"| node_database
node_orchestrator -->|"records state"| node_database
node_http_api -->|"serves events"| node_event_bus
node_host_agent -->|"starts server"| node_http_api
node_host_agent -->|"starts loop"| node_orchestrator
node_authentik_setup -->|"configures provider"| node_authentik
node_affine_setup -->|"calls app APIs"| node_app_api_clients
node_configtest -.->|"uses shared client"| node_app_api_clients

click node_dashboard_ui "https://github.com/d-buckner/bloud/tree/main/services/host-agent/web/src"
click node_web_clients "https://github.com/d-buckner/bloud/tree/main/services/host-agent/web/src/lib/clients"
click node_http_api "https://github.com/d-buckner/bloud/tree/main/services/host-agent/internal/api"
click node_catalog "https://github.com/d-buckner/bloud/tree/main/services/host-agent/internal/catalog"
click node_orchestrator "https://github.com/d-buckner/bloud/tree/main/services/host-agent/internal/engine/orchestrator"
click node_dependency_graph "https://github.com/d-buckner/bloud/tree/main/services/host-agent/internal/engine/graph"
click node_app_config "https://github.com/d-buckner/bloud/tree/main/apps"
click node_container_runtime "https://github.com/d-buckner/bloud/tree/main/services/host-agent/internal/container"
click node_podman "https://github.com/d-buckner/bloud/tree/main/services/host-agent/internal/podman"
click node_app_api_clients "https://github.com/d-buckner/bloud/tree/main/services/host-agent/pkg/appclient"
click node_authentik "https://github.com/d-buckner/bloud/blob/main/services/host-agent/pkg/authentik/client.go"
click node_proxy_config "https://github.com/d-buckner/bloud/tree/main/services/host-agent/internal/traefikgen"
click node_sharing "https://github.com/d-buckner/bloud/tree/main/services/host-agent/internal/sharing"
click node_media_wiring "https://github.com/d-buckner/bloud/blob/main/apps/seerr/jellyfin.go"
click node_database "https://github.com/d-buckner/bloud/tree/main/services/host-agent/internal/store"
click node_event_bus "https://github.com/d-buckner/bloud/tree/main/services/host-agent/internal/eventbus"
click node_host_agent "https://github.com/d-buckner/bloud/blob/main/services/host-agent/cmd/host-agent/main.go"
click node_affine_setup "https://github.com/d-buckner/bloud/blob/main/apps/affine/api.go"
click node_authentik_setup "https://github.com/d-buckner/bloud/blob/main/apps/authentik/server_configurator.go"
click node_configtest "https://github.com/d-buckner/bloud/blob/main/apps/configtest/configtest.go"
click node_servarr_client "https://github.com/d-buckner/bloud/blob/main/services/host-agent/pkg/servarr/downloadclient.go"

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_dashboard_ui,node_web_clients,node_user toneBlue
class node_http_api,node_catalog,node_orchestrator,node_dependency_graph,node_host_agent toneAmber
class node_app_config,node_container_runtime,node_podman,node_app_api_clients,node_affine_setup,node_configtest toneMint
class node_authentik,node_proxy_config,node_sharing,node_media_wiring,node_authentik_setup,node_servarr_client toneRose
class node_database,node_event_bus toneIndigo
```

## Components

### Dashboard

- [Dashboard UI](https://github.com/d-buckner/bloud/tree/main/services/host-agent/web/src): `services/host-agent/web/src`
- [Web API clients](https://github.com/d-buckner/bloud/tree/main/services/host-agent/web/src/lib/clients): `services/host-agent/web/src/lib/clients`

### Control plane

- [HTTP API](https://github.com/d-buckner/bloud/tree/main/services/host-agent/internal/api): `services/host-agent/internal/api`
- [App catalog](https://github.com/d-buckner/bloud/tree/main/services/host-agent/internal/catalog): `services/host-agent/internal/catalog`
- [Reconciliation engine](https://github.com/d-buckner/bloud/tree/main/services/host-agent/internal/engine/orchestrator): `services/host-agent/internal/engine/orchestrator`
- [Dependency graph](https://github.com/d-buckner/bloud/tree/main/services/host-agent/internal/engine/graph): `services/host-agent/internal/engine/graph`
- [Host-agent startup](https://github.com/d-buckner/bloud/blob/main/services/host-agent/cmd/host-agent/main.go): `services/host-agent/cmd/host-agent/main.go`

### App runtime

- [App configurators](https://github.com/d-buckner/bloud/tree/main/apps): `apps`
- [Container runtime](https://github.com/d-buckner/bloud/tree/main/services/host-agent/internal/container): `services/host-agent/internal/container`
- [Podman client](https://github.com/d-buckner/bloud/tree/main/services/host-agent/internal/podman): `services/host-agent/internal/podman`
- [App API clients](https://github.com/d-buckner/bloud/tree/main/services/host-agent/pkg/appclient): `services/host-agent/pkg/appclient`
- [AFFiNE setup](https://github.com/d-buckner/bloud/blob/main/apps/affine/api.go): `apps/affine/api.go`
- [Configurator checks](https://github.com/d-buckner/bloud/blob/main/apps/configtest/configtest.go): `apps/configtest/configtest.go`

### Integrations

- [Authentik integration](https://github.com/d-buckner/bloud/blob/main/services/host-agent/pkg/authentik/client.go): `services/host-agent/pkg/authentik/client.go`
- [Proxy configuration](https://github.com/d-buckner/bloud/tree/main/services/host-agent/internal/traefikgen): `services/host-agent/internal/traefikgen`
- [Sharing and tailnet](https://github.com/d-buckner/bloud/tree/main/services/host-agent/internal/sharing): `services/host-agent/internal/sharing`
- [Media-stack wiring](https://github.com/d-buckner/bloud/blob/main/apps/seerr/jellyfin.go): `apps/seerr/jellyfin.go`
- [Authentik setup](https://github.com/d-buckner/bloud/blob/main/apps/authentik/server_configurator.go): `apps/authentik/server_configurator.go`
- [Download-client support](https://github.com/d-buckner/bloud/blob/main/services/host-agent/pkg/servarr/downloadclient.go): `services/host-agent/pkg/servarr/downloadclient.go`

### State and operations

- [Persistent state](https://github.com/d-buckner/bloud/tree/main/services/host-agent/internal/store): `services/host-agent/internal/store`
- [Event streams](https://github.com/d-buckner/bloud/tree/main/services/host-agent/internal/eventbus): `services/host-agent/internal/eventbus`

### Other components

- **Home-server user**

## Connections

- Home-server user → Dashboard UI: manages apps
- Dashboard UI → Web API clients: uses clients
- Web API clients → HTTP API: sends requests
- HTTP API → Reconciliation engine: submits intents (evidence: `services/host-agent/internal/api/server.go`)
- Reconciliation engine → App catalog: resolves apps (evidence: `services/host-agent/internal/engine/orchestrator/pipeline.go`)
- Reconciliation engine → Dependency graph: orders dependencies (evidence: `services/host-agent/internal/engine/orchestrator/pipeline.go`)
- Reconciliation engine → Container runtime: reconciles containers
- Container runtime → Podman client: controls containers
- Reconciliation engine → App configurators: runs configurators
- App configurators → App API clients: verifies apps (evidence: `apps/affine/api.go`)
- Reconciliation engine → Proxy configuration: writes routes
- Reconciliation engine → Authentik integration: configures identity
- App configurators → Authentik integration: sets up identity
- Reconciliation engine → Sharing and tailnet: converges sharing (evidence: `services/host-agent/internal/engine/orchestrator/pipeline.go`)
- Reconciliation engine → Media-stack wiring: wires app stack
- Media-stack wiring → Download-client support: configures download clients
- HTTP API → Persistent state: reads and writes (evidence: `services/host-agent/internal/api/server.go`)
- Reconciliation engine → Persistent state: records state (evidence: `services/host-agent/internal/engine/orchestrator/pipeline.go`)
- HTTP API → Event streams: serves events (evidence: `services/host-agent/cmd/host-agent/main.go`)
- Host-agent startup → HTTP API: starts server (evidence: `services/host-agent/cmd/host-agent/main.go`)
- Host-agent startup → Reconciliation engine: starts loop (evidence: `services/host-agent/cmd/host-agent/main.go`)
- Authentik setup → Authentik integration: configures provider (evidence: `apps/authentik/server_configurator.go`)
- AFFiNE setup → App API clients: calls app APIs (evidence: `apps/affine/api.go`)
- Configurator checks → App API clients: uses shared client
