# echotrigger/centaeris-workspace architecture

> Architecture diagram of the GitHub repository echotrigger/centaeris-workspace, 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/echotrigger/centaeris-workspace
- Repository: https://github.com/echotrigger/centaeris-workspace

## Overview

Centaeris is a hosted agent workspace: users interact through the web client, the Django control plane manages workspace and AgentRun operations, and the Rust runtime coordinates durable jobs and managed execution. Document/material processing and plugin management are additional product capabilities. The sampled excerpts show frontend stream handling, runtime-client calls, worker job handling, and material storage; other links reflect the README and module boundaries, so uncertain internal wiring is omitted.

Main entry points: [`packages/runtime_server/src/main.rs`](https://github.com/echotrigger/centaeris-workspace/blob/main/packages/runtime_server/src/main.rs) (Agent run runtime), [`packages/web/src/main.tsx`](https://github.com/echotrigger/centaeris-workspace/blob/main/packages/web/src/main.tsx) (Workspace UI), [`packages/api/api/ninja_api.py`](https://github.com/echotrigger/centaeris-workspace/blob/main/packages/api/api/ninja_api.py) (API control plane), [`packages/web/src/api.ts`](https://github.com/echotrigger/centaeris-workspace/blob/main/packages/web/src/api.ts) (Web API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web client"]
  node_webapp["Workspace UI<br/>[main.tsx]"]
  node_chat["Chat stream"]
  node_transcript["Transcript view"]
  node_webapi["Web API client<br/>[api.ts]"]
end

subgraph group_control["Django control plane"]
  node_django["API control plane<br/>[ninja_api.py]"]
  node_agenthttp["Agent endpoints<br/>[agents.py]"]
  node_runtimeclient["Runtime client<br/>[runtime_client.py]"]
  node_api_models[("Workspace records<br/>[models.py]")]
  node_worker["Job worker<br/>[worker.py]"]
end

subgraph group_runtime["Runtime services"]
  node_runtime["Agent run runtime<br/>[main.rs]"]
  node_modelclient["Model adapter client"]
  node_runtime_store[("Runtime job store<br/>[postgres_store.rs]")]
  node_transcript_protocol["Transcript protocol"]
end

subgraph group_execution["Managed execution"]
  node_dockerhost["Docker execution host"]
  node_dockerengine["Docker engine<br/>[docker_engine.rs]"]
  node_execution_agent["Execution agent<br/>[execution_agent.rs]"]
end

subgraph group_materials["Materials and plugins"]
  node_materials_http["Material endpoints<br/>[library.py]"]
  node_material_processor["Material processing"]
  node_material_storage[("Material storage")]
  node_plugin_lifecycle["Plugin lifecycle"]
end

node_user(("Workspace user"))
node_model["Model provider"]
node_object_store[("Configured object storage")]

node_user -->|"uses"| node_webapp
node_webapp -->|"requests"| node_webapi
node_webapi -->|"calls API"| node_django
node_webapp -->|"starts chat"| node_chat
node_chat -->|"loads stream"| node_webapi
node_webapp -->|"opens transcript"| node_transcript
node_transcript -->|"loads transcript"| node_webapi
node_django -->|"routes requests"| node_agenthttp
node_agenthttp -->|"schedules runs"| node_runtimeclient
node_runtimeclient -->|"calls internal API"| node_runtime
node_agenthttp -->|"reads and writes"| node_api_models
node_worker -->|"claims jobs"| node_runtime
node_runtime -->|"persists jobs"| node_runtime_store
node_runtime -->|"requests inference"| node_modelclient
node_modelclient -->|"sends model requests"| node_model
node_runtime -->|"emits transcript events"| node_transcript_protocol
node_runtime -->|"dispatches execution"| node_dockerhost
node_dockerhost -->|"manages containers"| node_dockerengine
node_dockerhost -->|"runs agent"| node_execution_agent
node_django -->|"routes material requests"| node_materials_http
node_materials_http -->|"processes materials"| node_material_processor
node_materials_http -->|"reads and commits"| node_material_storage
node_material_storage -->|"reads and writes"| node_object_store
node_django -->|"manages plugins"| node_plugin_lifecycle

click node_webapp "https://github.com/echotrigger/centaeris-workspace/blob/main/packages/web/src/main.tsx"
click node_chat "https://github.com/echotrigger/centaeris-workspace/blob/main/packages/web/src/chat/workspaceChatController.ts"
click node_transcript "https://github.com/echotrigger/centaeris-workspace/blob/main/packages/web/src/chat/workspaceTranscriptController.ts"
click node_webapi "https://github.com/echotrigger/centaeris-workspace/blob/main/packages/web/src/api.ts"
click node_django "https://github.com/echotrigger/centaeris-workspace/blob/main/packages/api/api/ninja_api.py"
click node_agenthttp "https://github.com/echotrigger/centaeris-workspace/blob/main/packages/api/app_core/http/agents.py"
click node_runtimeclient "https://github.com/echotrigger/centaeris-workspace/blob/main/packages/api/app_core/runtime_client.py"
click node_api_models "https://github.com/echotrigger/centaeris-workspace/blob/main/packages/api/app_core/models.py"
click node_worker "https://github.com/echotrigger/centaeris-workspace/blob/main/packages/worker/worker.py"
click node_runtime "https://github.com/echotrigger/centaeris-workspace/blob/main/packages/runtime_server/src/main.rs"
click node_modelclient "https://github.com/echotrigger/centaeris-workspace/blob/main/packages/runtime_server/src/api_model_client.rs"
click node_runtime_store "https://github.com/echotrigger/centaeris-workspace/blob/main/packages/runtime_server/src/postgres_store.rs"
click node_transcript_protocol "https://github.com/echotrigger/centaeris-workspace/blob/main/packages/runtime_server/src/transcript_protocol.rs"
click node_dockerhost "https://github.com/echotrigger/centaeris-workspace/blob/main/packages/runtime_server/src/docker_execution_host.rs"
click node_dockerengine "https://github.com/echotrigger/centaeris-workspace/blob/main/packages/runtime_server/src/docker_engine.rs"
click node_execution_agent "https://github.com/echotrigger/centaeris-workspace/blob/main/packages/hosted_execution/src/bin/execution_agent.rs"
click node_materials_http "https://github.com/echotrigger/centaeris-workspace/blob/main/packages/api/app_core/http/library.py"
click node_material_processor "https://github.com/echotrigger/centaeris-workspace/blob/main/packages/api/app_core/material_processor.py"
click node_material_storage "https://github.com/echotrigger/centaeris-workspace/blob/main/packages/api/app_core/material_storage.py"
click node_plugin_lifecycle "https://github.com/echotrigger/centaeris-workspace/blob/main/packages/api/app_core/plugin_lifecycle.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_webapp,node_chat,node_transcript,node_webapi,node_user toneBlue
class node_django,node_agenthttp,node_runtimeclient,node_api_models,node_worker,node_object_store toneAmber
class node_runtime,node_modelclient,node_runtime_store,node_transcript_protocol toneMint
class node_dockerhost,node_dockerengine,node_execution_agent toneRose
class node_materials_http,node_material_processor,node_material_storage,node_plugin_lifecycle,node_model toneIndigo
```

## Components

### Web client

- [Workspace UI](https://github.com/echotrigger/centaeris-workspace/blob/main/packages/web/src/main.tsx): `packages/web/src/main.tsx`
- [Chat stream](https://github.com/echotrigger/centaeris-workspace/blob/main/packages/web/src/chat/workspaceChatController.ts): `packages/web/src/chat/workspaceChatController.ts`
- [Transcript view](https://github.com/echotrigger/centaeris-workspace/blob/main/packages/web/src/chat/workspaceTranscriptController.ts): `packages/web/src/chat/workspaceTranscriptController.ts`
- [Web API client](https://github.com/echotrigger/centaeris-workspace/blob/main/packages/web/src/api.ts): `packages/web/src/api.ts`

### Django control plane

- [API control plane](https://github.com/echotrigger/centaeris-workspace/blob/main/packages/api/api/ninja_api.py): `packages/api/api/ninja_api.py`
- [Agent endpoints](https://github.com/echotrigger/centaeris-workspace/blob/main/packages/api/app_core/http/agents.py): `packages/api/app_core/http/agents.py`
- [Runtime client](https://github.com/echotrigger/centaeris-workspace/blob/main/packages/api/app_core/runtime_client.py): `packages/api/app_core/runtime_client.py`
- [Workspace records](https://github.com/echotrigger/centaeris-workspace/blob/main/packages/api/app_core/models.py): `packages/api/app_core/models.py`
- [Job worker](https://github.com/echotrigger/centaeris-workspace/blob/main/packages/worker/worker.py): `packages/worker/worker.py`

### Runtime services

- [Agent run runtime](https://github.com/echotrigger/centaeris-workspace/blob/main/packages/runtime_server/src/main.rs): `packages/runtime_server/src/main.rs`
- [Model adapter client](https://github.com/echotrigger/centaeris-workspace/blob/main/packages/runtime_server/src/api_model_client.rs): `packages/runtime_server/src/api_model_client.rs`
- [Runtime job store](https://github.com/echotrigger/centaeris-workspace/blob/main/packages/runtime_server/src/postgres_store.rs): `packages/runtime_server/src/postgres_store.rs`
- [Transcript protocol](https://github.com/echotrigger/centaeris-workspace/blob/main/packages/runtime_server/src/transcript_protocol.rs): `packages/runtime_server/src/transcript_protocol.rs`

### Managed execution

- [Docker execution host](https://github.com/echotrigger/centaeris-workspace/blob/main/packages/runtime_server/src/docker_execution_host.rs): `packages/runtime_server/src/docker_execution_host.rs`
- [Docker engine](https://github.com/echotrigger/centaeris-workspace/blob/main/packages/runtime_server/src/docker_engine.rs): `packages/runtime_server/src/docker_engine.rs`
- [Execution agent](https://github.com/echotrigger/centaeris-workspace/blob/main/packages/hosted_execution/src/bin/execution_agent.rs): `packages/hosted_execution/src/bin/execution_agent.rs`

### Materials and plugins

- [Material endpoints](https://github.com/echotrigger/centaeris-workspace/blob/main/packages/api/app_core/http/library.py): `packages/api/app_core/http/library.py`
- [Material processing](https://github.com/echotrigger/centaeris-workspace/blob/main/packages/api/app_core/material_processor.py): `packages/api/app_core/material_processor.py`
- [Material storage](https://github.com/echotrigger/centaeris-workspace/blob/main/packages/api/app_core/material_storage.py): `packages/api/app_core/material_storage.py`
- [Plugin lifecycle](https://github.com/echotrigger/centaeris-workspace/blob/main/packages/api/app_core/plugin_lifecycle.py): `packages/api/app_core/plugin_lifecycle.py`

### Other components

- **Workspace user**
- **Model provider**
- **Configured object storage**

## Connections

- Workspace user → Workspace UI: uses
- Workspace UI → Web API client: requests
- Web API client → API control plane: calls API
- Workspace UI → Chat stream: starts chat
- Chat stream → Web API client: loads stream
- Workspace UI → Transcript view: opens transcript
- Transcript view → Web API client: loads transcript
- API control plane → Agent endpoints: routes requests
- Agent endpoints → Runtime client: schedules runs
- Runtime client → Agent run runtime: calls internal API
- Agent endpoints → Workspace records: reads and writes
- Job worker → Agent run runtime: claims jobs
- Agent run runtime → Runtime job store: persists jobs
- Agent run runtime → Model adapter client: requests inference
- Model adapter client → Model provider: sends model requests
- Agent run runtime → Transcript protocol: emits transcript events
- Agent run runtime → Docker execution host: dispatches execution
- Docker execution host → Docker engine: manages containers
- Docker execution host → Execution agent: runs agent
- API control plane → Material endpoints: routes material requests
- Material endpoints → Material processing: processes materials
- Material endpoints → Material storage: reads and commits
- Material storage → Configured object storage: reads and writes
- API control plane → Plugin lifecycle: manages plugins