# Architecture

The engine owns workflow validity and execution semantics. Orchestration stores, configures, and hosts runs, and performs I/O. Providers implement model transport. The UI and desktop shell submit actions and display results: the UI owns presentation and interaction, and desktop bridges its commands and events.

## Filesystem

```text
architecture/
├── README.md                    # This index
├── end-to-end-runtime.md        # UI → desktop → orchestration → engine → providers (code-grounded)
├── technical-overview.md        # End-to-end overview with diagrams: context, caching, nodes/flow, harness design
├── contract.md                  # Layer responsibilities and dependency rules (source of truth)
├── orchestration-layout.md      # Orchestration module map and change paths
├── callable-agents.md           # Saved-agent snapshot and subagent model
├── provider-adapters.md         # Provider adapter families (Rig) and Bedrock notes
├── output-repair.md             # Overseer repair for malformed final-output submits
├── threading-concurrency.md     # Tokio runtimes, async tasks, blocking I/O risks
├── run-persistence.md           # Durable run storage, checkpoints, replay vs resume
└── diagrams/
    ├── README.md
    ├── layers-current-vs-target.mmd
    └── layers-legacy-names.mmd
```

## Implementation guides

| Topic | Guide |
| --- | --- |
| Run start, IPC, checkpoints, pauses, and resume | [Run lifecycle](https://philbotar.github.io/OpenFlow/architecture/end-to-end-runtime.html) |
| One agent's turn: context, caching, tools, and completion | [Agent execution and context](https://philbotar.github.io/OpenFlow/architecture/technical-overview.html) |
| Dependencies, ports, and change review | [Architecture contract](https://philbotar.github.io/OpenFlow/architecture/contract.html) |
| Orchestration services, stores, and change locations | [Orchestration layout](https://philbotar.github.io/OpenFlow/architecture/orchestration-layout.html) |
| Saved-agent snapshots and subagent lifecycle | [Callable agents](https://philbotar.github.io/OpenFlow/architecture/callable-agents.html) |
| Rig provider families and Bedrock setup | [Provider adapters](https://philbotar.github.io/OpenFlow/architecture/provider-adapters.html) |
| Planning restrictions, approval, and frozen evidence | [Plan → Execute internals](https://philbotar.github.io/OpenFlow/architecture/plan-execute.html) |
| Repair of malformed final-output calls | [Overseer output repair](https://philbotar.github.io/OpenFlow/architecture/output-repair.html) |
| Current and target layer boundaries | [Layer diagram](https://github.com/philbotar/OpenFlow/blob/main/docs/architecture/diagrams/layers-current-vs-target.mmd) |
| Runtimes, I/O, and parallelism | [Threading and concurrency](https://philbotar.github.io/OpenFlow/architecture/threading-concurrency.html) |
| Checkpoints, replay, and resume after restart | [Run persistence](https://philbotar.github.io/OpenFlow/architecture/run-persistence.html) |

Product-facing behavior: [runs](https://philbotar.github.io/OpenFlow/guides/runs.html), [projects and persistence](https://philbotar.github.io/OpenFlow/guides/projects-and-persistence.html), [configuration](https://philbotar.github.io/OpenFlow/reference/configuration.html).

## Layer stack

```text
UI (crates/ui)
  → Desktop adapter (crates/desktop)
    → Orchestration (crates/orchestration)
      → Engine (crates/engine)
      → Provider adapters (crates/providers) via AiPort
```

Orchestration owns runtime execution state and `ToolPortImpl`. Engine owns the workflow state machine and ports. Provider adapters own wire transport.

[Coding patterns](https://philbotar.github.io/OpenFlow/contributing/coding-patterns.html) names owning files and runtime rules, [AGENTS.md](https://github.com/philbotar/OpenFlow/blob/main/AGENTS.md) maps common changes to those owners, and the [architecture check config](https://github.com/philbotar/OpenFlow/blob/main/crates/workspace-checks/arch-check-rules.toml) defines the enforced boundaries.

## System boundaries

The desktop UI, command bridge, runtime host, engine, and providers are separate layers. [`../../scripts/check-architecture.sh`](https://github.com/philbotar/OpenFlow/blob/main/scripts/check-architecture.sh) enforces their dependency boundaries from [`../../crates/workspace-checks/arch-check-rules.toml`](https://github.com/philbotar/OpenFlow/blob/main/crates/workspace-checks/arch-check-rules.toml).

```mermaid
flowchart TD
    subgraph UI["crates/ui — SolidJS + TypeScript"]
        Canvas["Canvas (nodes & edges)"]
        Chat["Per-node chat panels"]
        Port["api.ts<br/>(typed desktop command and event wrappers)"]
    end

    subgraph Desktop["crates/desktop — Tauri adapter"]
        Cmds["Command handlers<br/>(IPC + DTO mapping only)"]
    end

    subgraph Orch["crates/orchestration — application layer / composition root"]
        Backend["AppBackend façade"]
        Coord["RunCoordinator<br/>(session, action channel)"]
        Drive["run/execution/<br/>(engine construction and hosting)"]
        ToolPortImpl["ToolPortImpl + ToolRunner<br/>(tool execution, cache, artifacts)"]
        Stores["adapters/storage/*<br/>(atomic JSON persistence)"]
    end

    subgraph Engine["crates/engine — I/O-free hexagon"]
        IE["InteractiveEngine<br/>(state machine)"]
        Graph["Workflow / Node / Edge<br/>+ DAG validation"]
        Ports["Ports: AiPort, ToolPort"]
        Policy["Tool approval policy<br/>(tiers, modes)"]
    end

    subgraph Providers["crates/providers — outbound adapter"]
        Factory["create_provider() → Box&lt;dyn AiPort&gt;"]
        OpenAI["OpenAI-compatible<br/>(Responses + Chat Completions)"]
        Anthropic["Anthropic Messages API"]
    end

    UI -->|"invoke Tauri commands"| Desktop
    Desktop -->|"calls AppBackend only"| Orch
    Orch -->|"drives InteractiveEngine::run()"| Engine
    Orch -->|"dyn AiPort, never concrete types"| Providers
    Providers -->|"implements engine::AiPort"| Engine
```

CI checks these constraints:

| Rule | Enforcement |
|---|---|
| Engine has zero I/O: no filesystem, no HTTP, no `unwrap`/`expect`/`panic` | Clippy denies + forbidden-dep table (`reqwest`, `tauri` banned in engine) |
| Only `orchestration/run/execution/` may construct `InteractiveEngine` | Tier-3 arch check |
| Desktop imports `orchestration::Workflow`, never `engine::Workflow` | Re-export boundary; ban tables |
| Orchestration may only import `create_provider` + config types from providers | Allowlist; `AiClient` banned |
| Engine public API is snapshot-tested | `crates/engine/tests/snapshots/public_api.txt` |