# echotrigger/centaeris architecture

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

- Interactive diagram: https://gitdiagram.com/echotrigger/centaeris
- Repository: https://github.com/echotrigger/centaeris

## Overview

Centaeris is a Rust agent-runtime framework with desktop and terminal hosts. A user starts or selects a session in a host; the host sends protocol requests to the shared runtime, which coordinates model turns, tool execution, events, and durable session state, then returns results for display. Major capabilities also include workspace operations, schedules, extension/skill loading, and MCP integration. The README establishes the shared contracts and adapters; sampled code shows selected UI-to-bridge and runtime internals, so uncertain implementation wiring is omitted.

Main entry points: [`packages/runtime/src/handlers.rs`](https://github.com/echotrigger/centaeris/blob/main/packages/runtime/src/handlers.rs) (Request Handlers), [`packages/runtime/src/agent_runtime.rs`](https://github.com/echotrigger/centaeris/blob/main/packages/runtime/src/agent_runtime.rs) (Agent Runtime), [`packages/core/src/runtime/turn_pipeline.rs`](https://github.com/echotrigger/centaeris/blob/main/packages/core/src/runtime/turn_pipeline.rs) (Turn Pipeline), [`packages/core/src/model.rs`](https://github.com/echotrigger/centaeris/blob/main/packages/core/src/model.rs) (Model Contracts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hosts["User Hosts"]
  node_desktop["Desktop Host<br/>[main.mjs]"]
  node_ui["Shared UI<br/>[App.tsx]"]
  node_tui["Terminal Host<br/>[app.rs]"]
end

subgraph group_runtime["Runtime Orchestration"]
  node_protocol["Host Protocol<br/>[host_protocol.rs]"]
  node_server["Runtime Server<br/>[runtime_server.rs]"]
  node_handlers["Request Handlers<br/>[handlers.rs]"]
  node_agent["Agent Runtime<br/>[agent_runtime.rs]"]
end

subgraph group_semantics["Agent Semantics"]
  node_core_runtime["Turn Runtime<br/>[runtime.rs]"]
  node_turn_pipeline["Turn Pipeline<br/>[turn_pipeline.rs]"]
  node_tooling["Tool Contracts<br/>[tool.rs]"]
  node_model["Model Contracts<br/>[model.rs]"]
  node_sessions["Session Contracts<br/>[session.rs]"]
end

subgraph group_integrations["Adapters and Extensions"]
  node_model_catalog["Model Catalog<br/>[lib.rs]"]
  node_mcp["MCP Adapter<br/>[lib.rs]"]
  node_extensions["Extensions and Skills<br/>[extension.rs]"]
end

subgraph group_state["Persistence and Workspaces"]
  node_sqlite["SQLite Adapter<br/>[lib.rs]"]
  node_workspace["Workspace Services<br/>[workspaces.rs]"]
  node_schedules["Schedules<br/>[schedules.rs]"]
end

node_user(("User"))
node_provider["Model Provider"]
node_mcp_server["MCP Server"]
node_store[("SQLite Store")]

node_user -->|"uses"| node_ui
node_user -->|"uses"| node_tui
node_ui -->|"host bridge"| node_desktop
node_desktop -->|"sends requests"| node_protocol
node_tui -->|"sends requests"| node_protocol
node_protocol -->|"transports"| node_server
node_server -->|"dispatches"| node_handlers
node_handlers -->|"routes agent requests"| node_agent
node_agent -->|"coordinates turns"| node_core_runtime
node_core_runtime -->|"runs turns"| node_turn_pipeline
node_turn_pipeline -->|"requests generation"| node_model
node_turn_pipeline -->|"executes tool calls"| node_tooling
node_model -->|"sends model requests"| node_provider
node_handlers -->|"handles session operations"| node_sessions
node_agent -->|"continues sessions"| node_sessions
node_agent -->|"persists runtime state"| node_sqlite
node_sqlite -->|"reads and writes"| node_store
node_handlers -->|"routes workspace requests"| node_workspace
node_handlers -->|"routes schedule requests"| node_schedules
node_handlers -.->|"routes MCP operations"| node_mcp
node_mcp -.->|"communicates"| node_mcp_server
node_agent -.->|"loads extensions"| node_extensions
node_model -.->|"uses catalog"| node_model_catalog

click node_desktop "https://github.com/echotrigger/centaeris/blob/main/packages/desktop/src/main.mjs"
click node_ui "https://github.com/echotrigger/centaeris/blob/main/packages/ui/src/App.tsx"
click node_tui "https://github.com/echotrigger/centaeris/blob/main/packages/tui/src/app.rs"
click node_protocol "https://github.com/echotrigger/centaeris/blob/main/packages/runtime/src/host_protocol.rs"
click node_server "https://github.com/echotrigger/centaeris/blob/main/packages/runtime/src/runtime_server.rs"
click node_handlers "https://github.com/echotrigger/centaeris/blob/main/packages/runtime/src/handlers.rs"
click node_agent "https://github.com/echotrigger/centaeris/blob/main/packages/runtime/src/agent_runtime.rs"
click node_core_runtime "https://github.com/echotrigger/centaeris/blob/main/packages/core/src/runtime.rs"
click node_turn_pipeline "https://github.com/echotrigger/centaeris/blob/main/packages/core/src/runtime/turn_pipeline.rs"
click node_tooling "https://github.com/echotrigger/centaeris/blob/main/packages/core/src/tool.rs"
click node_model "https://github.com/echotrigger/centaeris/blob/main/packages/core/src/model.rs"
click node_sessions "https://github.com/echotrigger/centaeris/blob/main/packages/core/src/session.rs"
click node_model_catalog "https://github.com/echotrigger/centaeris/blob/main/packages/model-catalog/src/lib.rs"
click node_mcp "https://github.com/echotrigger/centaeris/blob/main/packages/mcp/src/lib.rs"
click node_extensions "https://github.com/echotrigger/centaeris/blob/main/packages/core/src/extension.rs"
click node_sqlite "https://github.com/echotrigger/centaeris/blob/main/packages/runtime_sqlite/src/lib.rs"
click node_workspace "https://github.com/echotrigger/centaeris/blob/main/packages/runtime/src/workspaces.rs"
click node_schedules "https://github.com/echotrigger/centaeris/blob/main/packages/runtime/src/schedules.rs"

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_desktop,node_ui,node_tui,node_user toneBlue
class node_protocol,node_server,node_handlers,node_agent,node_store toneAmber
class node_core_runtime,node_turn_pipeline,node_tooling,node_model,node_sessions,node_mcp_server toneMint
class node_model_catalog,node_mcp,node_extensions toneRose
class node_sqlite,node_workspace,node_schedules,node_provider toneIndigo
```

## Components

### User Hosts

- [Desktop Host](https://github.com/echotrigger/centaeris/blob/main/packages/desktop/src/main.mjs): `packages/desktop/src/main.mjs`
- [Shared UI](https://github.com/echotrigger/centaeris/blob/main/packages/ui/src/App.tsx): `packages/ui/src/App.tsx`
- [Terminal Host](https://github.com/echotrigger/centaeris/blob/main/packages/tui/src/app.rs): `packages/tui/src/app.rs`

### Runtime Orchestration

- [Host Protocol](https://github.com/echotrigger/centaeris/blob/main/packages/runtime/src/host_protocol.rs): `packages/runtime/src/host_protocol.rs`
- [Runtime Server](https://github.com/echotrigger/centaeris/blob/main/packages/runtime/src/runtime_server.rs): `packages/runtime/src/runtime_server.rs`
- [Request Handlers](https://github.com/echotrigger/centaeris/blob/main/packages/runtime/src/handlers.rs): `packages/runtime/src/handlers.rs`
- [Agent Runtime](https://github.com/echotrigger/centaeris/blob/main/packages/runtime/src/agent_runtime.rs): `packages/runtime/src/agent_runtime.rs`

### Agent Semantics

- [Turn Runtime](https://github.com/echotrigger/centaeris/blob/main/packages/core/src/runtime.rs): `packages/core/src/runtime.rs`
- [Turn Pipeline](https://github.com/echotrigger/centaeris/blob/main/packages/core/src/runtime/turn_pipeline.rs): `packages/core/src/runtime/turn_pipeline.rs`
- [Tool Contracts](https://github.com/echotrigger/centaeris/blob/main/packages/core/src/tool.rs): `packages/core/src/tool.rs`
- [Model Contracts](https://github.com/echotrigger/centaeris/blob/main/packages/core/src/model.rs): `packages/core/src/model.rs`
- [Session Contracts](https://github.com/echotrigger/centaeris/blob/main/packages/core/src/session.rs): `packages/core/src/session.rs`

### Adapters and Extensions

- [Model Catalog](https://github.com/echotrigger/centaeris/blob/main/packages/model-catalog/src/lib.rs): `packages/model-catalog/src/lib.rs`
- [MCP Adapter](https://github.com/echotrigger/centaeris/blob/main/packages/mcp/src/lib.rs): `packages/mcp/src/lib.rs`
- [Extensions and Skills](https://github.com/echotrigger/centaeris/blob/main/packages/core/src/extension.rs): `packages/core/src/extension.rs`

### Persistence and Workspaces

- [SQLite Adapter](https://github.com/echotrigger/centaeris/blob/main/packages/runtime_sqlite/src/lib.rs): `packages/runtime_sqlite/src/lib.rs`
- [Workspace Services](https://github.com/echotrigger/centaeris/blob/main/packages/runtime/src/workspaces.rs): `packages/runtime/src/workspaces.rs`
- [Schedules](https://github.com/echotrigger/centaeris/blob/main/packages/runtime/src/schedules.rs): `packages/runtime/src/schedules.rs`

### Other components

- **User**
- **Model Provider**
- **MCP Server**
- **SQLite Store**

## Connections

- User → Shared UI: uses
- User → Terminal Host: uses
- Shared UI → Desktop Host: host bridge
- Desktop Host → Host Protocol: sends requests
- Terminal Host → Host Protocol: sends requests
- Host Protocol → Runtime Server: transports
- Runtime Server → Request Handlers: dispatches
- Request Handlers → Agent Runtime: routes agent requests
- Agent Runtime → Turn Runtime: coordinates turns
- Turn Runtime → Turn Pipeline: runs turns
- Turn Pipeline → Model Contracts: requests generation
- Turn Pipeline → Tool Contracts: executes tool calls
- Model Contracts → Model Provider: sends model requests
- Request Handlers → Session Contracts: handles session operations
- Agent Runtime → Session Contracts: continues sessions
- Agent Runtime → SQLite Adapter: persists runtime state
- SQLite Adapter → SQLite Store: reads and writes
- Request Handlers → Workspace Services: routes workspace requests
- Request Handlers → Schedules: routes schedule requests
- Request Handlers → MCP Adapter: routes MCP operations
- MCP Adapter → MCP Server: communicates
- Agent Runtime → Extensions and Skills: loads extensions
- Model Contracts → Model Catalog: uses catalog