# iii-hq/iii architecture

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

- Interactive diagram: https://gitdiagram.com/iii-hq/iii
- Repository: https://github.com/iii-hq/iii

## Overview

iii is a composable runtime for registering workers, routing triggers to functions, and observing the resulting activity. The principal workflow is to define or add workers through Compose, have them join the live engine catalog, invoke their functions through triggers, and inspect traces, logs, queues, and state in the Console. The graph preserves documented queue, cron, HTTP, state, stream, SDK, and sandbox capabilities. Several subsystem links are based on README descriptions because their implementation files were not sampled.

Main entry points: [`engine/src/trigger.rs`](https://github.com/iii-hq/iii/blob/main/engine/src/trigger.rs) (Trigger routing), [`console/packages/console-frontend/src/routes/traces.tsx`](https://github.com/iii-hq/iii/blob/main/console/packages/console-frontend/src/routes/traces.tsx) (Developer console), [`crates/iii-compose/src/cli.rs`](https://github.com/iii-hq/iii/blob/main/crates/iii-compose/src/cli.rs) (Compose CLI), [`sdk/packages`](https://github.com/iii-hq/iii/tree/main/sdk/packages) (Worker processes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_composition["Worker composition"]
  node_compose["Compose CLI<br/>[cli.rs]"]
  node_compose_config["Compose configuration<br/>[config.rs]"]
  node_compose_lifecycle["Managed engine lifecycle<br/>[managed_engine.rs]"]
end

subgraph group_runtime["Engine runtime"]
  node_worker["Worker processes"]
  node_sdk["Language SDKs"]
  node_engine["Engine runtime<br/>[mod.rs]"]
  node_catalog[("Worker and function catalog<br/>[registry.rs]")]
  node_trigger_routing["Trigger routing<br/>[trigger.rs]"]
  node_function_invocation["Function invocation<br/>[http_invoker.rs]"]
end

subgraph group_capabilities["Runtime capabilities"]
  node_http_cron["HTTP and cron triggers<br/>[mod.rs]"]
  node_queues["Queue subscriptions<br/>[queue.rs]"]
  node_state_streams["State and streams<br/>[stream.rs]"]
  node_observability["Logs traces metrics<br/>[mod.rs]"]
  node_sandbox["Sandbox workers<br/>[mod.rs]"]
end

subgraph group_operations["Operations and console"]
  node_console["Developer console<br/>[traces.tsx]"]
  node_console_server["Console server and proxy<br/>[server.rs]"]
end

node_developer(("Developer or agent"))
node_external_engine(("External engine services"))

node_developer -->|"defines workers"| node_compose
node_developer -->|"registers functions"| node_sdk
node_compose -->|"loads configuration"| node_compose_config
node_compose -->|"starts engine"| node_compose_lifecycle
node_compose_lifecycle -.->|"launches runtime"| node_engine
node_worker -->|"registers with"| node_engine
node_sdk -->|"connects worker"| node_worker
node_engine -->|"maintains catalog"| node_catalog
node_trigger_routing -->|"dispatches call"| node_function_invocation
node_worker -->|"declares triggers"| node_trigger_routing
node_http_cron -->|"routes events"| node_trigger_routing
node_queues -->|"delivers messages"| node_trigger_routing
node_state_streams -->|"emits changes"| node_trigger_routing
node_function_invocation -->|"records activity"| node_observability
node_external_engine -->|"serves engine API"| node_console_server
node_console -.->|"requests console API"| node_console_server
node_console_server -->|"proxies requests"| node_external_engine
node_console -->|"inspects traces logs"| node_observability
node_console -->|"inspects queues"| node_queues
node_console -->|"inspects live state"| node_state_streams
node_developer -.->|"adds sandbox worker"| node_sandbox

click node_compose "https://github.com/iii-hq/iii/blob/main/crates/iii-compose/src/cli.rs"
click node_compose_config "https://github.com/iii-hq/iii/blob/main/crates/iii-compose/src/config.rs"
click node_compose_lifecycle "https://github.com/iii-hq/iii/blob/main/crates/iii-compose/src/managed_engine.rs"
click node_worker "https://github.com/iii-hq/iii/tree/main/sdk/packages"
click node_sdk "https://github.com/iii-hq/iii/tree/main/sdk/packages"
click node_engine "https://github.com/iii-hq/iii/blob/main/engine/src/engine/mod.rs"
click node_catalog "https://github.com/iii-hq/iii/blob/main/engine/src/workers/registry.rs"
click node_trigger_routing "https://github.com/iii-hq/iii/blob/main/engine/src/trigger.rs"
click node_function_invocation "https://github.com/iii-hq/iii/blob/main/engine/src/invocation/http_invoker.rs"
click node_http_cron "https://github.com/iii-hq/iii/blob/main/engine/src/workers/http_functions/mod.rs"
click node_queues "https://github.com/iii-hq/iii/blob/main/engine/src/workers/queue/queue.rs"
click node_state_streams "https://github.com/iii-hq/iii/blob/main/engine/src/workers/stream/stream.rs"
click node_observability "https://github.com/iii-hq/iii/blob/main/engine/src/workers/observability/mod.rs"
click node_sandbox "https://github.com/iii-hq/iii/blob/main/crates/iii-worker/src/sandbox_daemon/mod.rs"
click node_console "https://github.com/iii-hq/iii/blob/main/console/packages/console-frontend/src/routes/traces.tsx"
click node_console_server "https://github.com/iii-hq/iii/blob/main/console/packages/console-rust/src/server.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_compose,node_compose_config,node_compose_lifecycle toneBlue
class node_worker,node_sdk,node_engine,node_catalog,node_trigger_routing,node_function_invocation toneAmber
class node_http_cron,node_queues,node_state_streams,node_observability,node_sandbox toneMint
class node_console,node_console_server toneRose
class node_developer,node_external_engine toneIndigo
```

## Components

### Worker composition

- [Compose CLI](https://github.com/iii-hq/iii/blob/main/crates/iii-compose/src/cli.rs): `crates/iii-compose/src/cli.rs`
- [Compose configuration](https://github.com/iii-hq/iii/blob/main/crates/iii-compose/src/config.rs): `crates/iii-compose/src/config.rs`
- [Managed engine lifecycle](https://github.com/iii-hq/iii/blob/main/crates/iii-compose/src/managed_engine.rs): `crates/iii-compose/src/managed_engine.rs`

### Engine runtime

- [Worker processes](https://github.com/iii-hq/iii/tree/main/sdk/packages): `sdk/packages`
- [Language SDKs](https://github.com/iii-hq/iii/tree/main/sdk/packages): `sdk/packages`
- [Engine runtime](https://github.com/iii-hq/iii/blob/main/engine/src/engine/mod.rs): `engine/src/engine/mod.rs`
- [Worker and function catalog](https://github.com/iii-hq/iii/blob/main/engine/src/workers/registry.rs): `engine/src/workers/registry.rs`
- [Trigger routing](https://github.com/iii-hq/iii/blob/main/engine/src/trigger.rs): `engine/src/trigger.rs`
- [Function invocation](https://github.com/iii-hq/iii/blob/main/engine/src/invocation/http_invoker.rs): `engine/src/invocation/http_invoker.rs`

### Runtime capabilities

- [HTTP and cron triggers](https://github.com/iii-hq/iii/blob/main/engine/src/workers/http_functions/mod.rs): `engine/src/workers/http_functions/mod.rs`
- [Queue subscriptions](https://github.com/iii-hq/iii/blob/main/engine/src/workers/queue/queue.rs): `engine/src/workers/queue/queue.rs`
- [State and streams](https://github.com/iii-hq/iii/blob/main/engine/src/workers/stream/stream.rs): `engine/src/workers/stream/stream.rs`
- [Logs traces metrics](https://github.com/iii-hq/iii/blob/main/engine/src/workers/observability/mod.rs): `engine/src/workers/observability/mod.rs`
- [Sandbox workers](https://github.com/iii-hq/iii/blob/main/crates/iii-worker/src/sandbox_daemon/mod.rs): `crates/iii-worker/src/sandbox_daemon/mod.rs`

### Operations and console

- [Developer console](https://github.com/iii-hq/iii/blob/main/console/packages/console-frontend/src/routes/traces.tsx): `console/packages/console-frontend/src/routes/traces.tsx`
- [Console server and proxy](https://github.com/iii-hq/iii/blob/main/console/packages/console-rust/src/server.rs): `console/packages/console-rust/src/server.rs`

### Other components

- **Developer or agent**
- **External engine services**

## Connections

- Developer or agent → Compose CLI: defines workers (evidence: `README.md`)
- Developer or agent → Language SDKs: registers functions (evidence: `README.md`)
- Compose CLI → Compose configuration: loads configuration (evidence: `crates/iii-compose/src/config.rs`)
- Compose CLI → Managed engine lifecycle: starts engine (evidence: `crates/iii-compose/src/managed_engine.rs`)
- Managed engine lifecycle → Engine runtime: launches runtime
- Worker processes → Engine runtime: registers with (evidence: `README.md`)
- Language SDKs → Worker processes: connects worker (evidence: `README.md`)
- Engine runtime → Worker and function catalog: maintains catalog (evidence: `README.md`)
- Trigger routing → Function invocation: dispatches call (evidence: `README.md`)
- Worker processes → Trigger routing: declares triggers (evidence: `README.md`)
- HTTP and cron triggers → Trigger routing: routes events (evidence: `README.md`)
- Queue subscriptions → Trigger routing: delivers messages (evidence: `README.md`)
- State and streams → Trigger routing: emits changes (evidence: `README.md`)
- Function invocation → Logs traces metrics: records activity (evidence: `README.md`)
- External engine services → Console server and proxy: serves engine API (evidence: `console/packages/console-rust/src/server.rs`)
- Developer console → Console server and proxy: requests console API
- Console server and proxy → External engine services: proxies requests (evidence: `console/packages/console-rust/src/server.rs`)
- Developer console → Logs traces metrics: inspects traces logs (evidence: `README.md`)
- Developer console → Queue subscriptions: inspects queues (evidence: `README.md`)
- Developer console → State and streams: inspects live state (evidence: `README.md`)
- Developer or agent → Sandbox workers: adds sandbox worker
