# davidondrej/cloudroom-core architecture

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

- Interactive diagram: https://gitdiagram.com/davidondrej/cloudroom-core
- Repository: https://github.com/davidondrej/cloudroom-core

## Overview

Cloudroom Core is a self-hostable service for running coding agents on a Linux VM and retaining their session histories. The main workflow is an authenticated client request through the HTTP API into session management, which starts or controls a harness runtime and records session events. The README also describes account management, workspaces, previews, Mac access, and diagnostics. Paths identify the relevant modules; some subsystem wiring is inferred only from documented capabilities because those sources were not sampled.

Main entry points: [`src/api/mod.rs`](https://github.com/davidondrej/cloudroom-core/blob/main/src/api/mod.rs) (HTTP API), [`src/session/mod.rs`](https://github.com/davidondrej/cloudroom-core/blob/main/src/session/mod.rs) (Session manager), [`src/runtime/mod.rs`](https://github.com/davidondrej/cloudroom-core/blob/main/src/runtime/mod.rs) (Harness runtime), [`src/workspace/mod.rs`](https://github.com/davidondrej/cloudroom-core/blob/main/src/workspace/mod.rs) (Workspace management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_service["Service and sessions"]
  node_api["HTTP API<br/>[mod.rs]"]
  node_session["Session manager<br/>[mod.rs]"]
  node_accounts["Account management<br/>[accounts.rs]"]
  node_workspace["Workspace management<br/>[mod.rs]"]
  node_config["Service config<br/>[config.rs]"]
end

subgraph group_agents["Agent execution"]
  node_runtime["Harness runtime<br/>[mod.rs]"]
  node_harnesses["Harness adapters<br/>[claude.rs]"]
  node_process["Process control<br/>[process.rs]"]
end

subgraph group_state["State and diagnostics"]
  node_history["Session journal<br/>[outbox.rs]"]
  node_workspace_storage["Workspace storage policy<br/>[storage.rs]"]
  node_observability["Observability<br/>[mod.rs]"]
  node_metrics["Metric history<br/>[metrics.rs]"]
end

subgraph group_integrations["Client integrations"]
  node_preview["Preview access<br/>[mod.rs]"]
  node_preview_client["Preview client<br/>[client.py]"]
  node_mac["Mac access<br/>[mod.rs]"]
  node_sync["Settings and auth sync<br/>[client.py]"]
  node_bb_client["TypeScript client<br/>[client.ts]"]
end

node_user(("User or GUI"))
node_agent["Coding agent"]
node_postgres[("PostgreSQL history store")]
node_model_providers(("Model providers"))

node_user -->|"sends requests"| node_api
node_api -->|"dispatches session commands"| node_session
node_api -->|"handles account routes"| node_accounts
node_api -->|"handles workspace routes"| node_workspace
node_api -->|"records API signals"| node_observability
node_session -->|"starts and controls"| node_runtime
node_runtime -->|"selects adapter"| node_harnesses
node_runtime -->|"drives processes"| node_process
node_process -->|"launches"| node_agent
node_agent -->|"makes model calls"| node_model_providers
node_session -->|"appends session events"| node_history
node_history -->|"uploads history"| node_postgres
node_workspace -->|"checks storage policy"| node_workspace_storage
node_observability -->|"records and reads metrics"| node_metrics
node_api -->|"serves preview routes"| node_preview
node_preview_client -->|"requests preview access"| node_api
node_api -->|"serves Mac routes"| node_mac
node_sync -->|"syncs settings and auth"| node_api
node_bb_client -->|"calls session API"| node_api
node_session -->|"uses harness configuration"| node_config

click node_api "https://github.com/davidondrej/cloudroom-core/blob/main/src/api/mod.rs"
click node_session "https://github.com/davidondrej/cloudroom-core/blob/main/src/session/mod.rs"
click node_accounts "https://github.com/davidondrej/cloudroom-core/blob/main/src/session/accounts.rs"
click node_workspace "https://github.com/davidondrej/cloudroom-core/blob/main/src/workspace/mod.rs"
click node_config "https://github.com/davidondrej/cloudroom-core/blob/main/src/config.rs"
click node_runtime "https://github.com/davidondrej/cloudroom-core/blob/main/src/runtime/mod.rs"
click node_harnesses "https://github.com/davidondrej/cloudroom-core/blob/main/src/runtime/claude.rs"
click node_process "https://github.com/davidondrej/cloudroom-core/blob/main/src/runtime/process.rs"
click node_history "https://github.com/davidondrej/cloudroom-core/blob/main/src/session/outbox.rs"
click node_workspace_storage "https://github.com/davidondrej/cloudroom-core/blob/main/src/workspace/storage.rs"
click node_observability "https://github.com/davidondrej/cloudroom-core/blob/main/src/observability/mod.rs"
click node_metrics "https://github.com/davidondrej/cloudroom-core/blob/main/src/observability/metrics.rs"
click node_preview "https://github.com/davidondrej/cloudroom-core/blob/main/src/preview/mod.rs"
click node_preview_client "https://github.com/davidondrej/cloudroom-core/blob/main/src/preview/client.py"
click node_mac "https://github.com/davidondrej/cloudroom-core/blob/main/src/mac/mod.rs"
click node_sync "https://github.com/davidondrej/cloudroom-core/blob/main/src/sync/client.py"
click node_bb_client "https://github.com/davidondrej/cloudroom-core/blob/main/integrations/bb/client.ts"

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_api,node_session,node_accounts,node_workspace,node_config,node_user toneBlue
class node_runtime,node_harnesses,node_process,node_postgres toneAmber
class node_history,node_workspace_storage,node_observability,node_metrics toneMint
class node_preview,node_preview_client,node_mac,node_sync,node_bb_client toneRose
class node_agent,node_model_providers toneIndigo
```

## Components

### Service and sessions

- [HTTP API](https://github.com/davidondrej/cloudroom-core/blob/main/src/api/mod.rs): `src/api/mod.rs`
- [Session manager](https://github.com/davidondrej/cloudroom-core/blob/main/src/session/mod.rs): `src/session/mod.rs`
- [Account management](https://github.com/davidondrej/cloudroom-core/blob/main/src/session/accounts.rs): `src/session/accounts.rs`
- [Workspace management](https://github.com/davidondrej/cloudroom-core/blob/main/src/workspace/mod.rs): `src/workspace/mod.rs`
- [Service config](https://github.com/davidondrej/cloudroom-core/blob/main/src/config.rs): `src/config.rs`

### Agent execution

- [Harness runtime](https://github.com/davidondrej/cloudroom-core/blob/main/src/runtime/mod.rs): `src/runtime/mod.rs`
- [Harness adapters](https://github.com/davidondrej/cloudroom-core/blob/main/src/runtime/claude.rs): `src/runtime/claude.rs`
- [Process control](https://github.com/davidondrej/cloudroom-core/blob/main/src/runtime/process.rs): `src/runtime/process.rs`

### State and diagnostics

- [Session journal](https://github.com/davidondrej/cloudroom-core/blob/main/src/session/outbox.rs): `src/session/outbox.rs`
- [Workspace storage policy](https://github.com/davidondrej/cloudroom-core/blob/main/src/workspace/storage.rs): `src/workspace/storage.rs`
- [Observability](https://github.com/davidondrej/cloudroom-core/blob/main/src/observability/mod.rs): `src/observability/mod.rs`
- [Metric history](https://github.com/davidondrej/cloudroom-core/blob/main/src/observability/metrics.rs): `src/observability/metrics.rs`

### Client integrations

- [Preview access](https://github.com/davidondrej/cloudroom-core/blob/main/src/preview/mod.rs): `src/preview/mod.rs`
- [Preview client](https://github.com/davidondrej/cloudroom-core/blob/main/src/preview/client.py): `src/preview/client.py`
- [Mac access](https://github.com/davidondrej/cloudroom-core/blob/main/src/mac/mod.rs): `src/mac/mod.rs`
- [Settings and auth sync](https://github.com/davidondrej/cloudroom-core/blob/main/src/sync/client.py): `src/sync/client.py`
- [TypeScript client](https://github.com/davidondrej/cloudroom-core/blob/main/integrations/bb/client.ts): `integrations/bb/client.ts`

### Other components

- **User or GUI**
- **Coding agent**
- **PostgreSQL history store**
- **Model providers**

## Connections

- User or GUI → HTTP API: sends requests
- HTTP API → Session manager: dispatches session commands
- HTTP API → Account management: handles account routes
- HTTP API → Workspace management: handles workspace routes
- HTTP API → Observability: records API signals
- Session manager → Harness runtime: starts and controls
- Harness runtime → Harness adapters: selects adapter
- Harness runtime → Process control: drives processes
- Process control → Coding agent: launches
- Coding agent → Model providers: makes model calls
- Session manager → Session journal: appends session events
- Session journal → PostgreSQL history store: uploads history
- Workspace management → Workspace storage policy: checks storage policy
- Observability → Metric history: records and reads metrics
- HTTP API → Preview access: serves preview routes
- Preview client → HTTP API: requests preview access
- HTTP API → Mac access: serves Mac routes
- Settings and auth sync → HTTP API: syncs settings and auth
- TypeScript client → HTTP API: calls session API
- Session manager → Service config: uses harness configuration