> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runr5e.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture Overview

> Three planes, three contracts. Everything else is a projection.

## The Three Planes

r5e separates system state into three planes (per [ADR-0001](/architecture/constraints)):

### Durable Control Plane

Resources and graphs represent semantic truth the system can inspect, reconcile, query, and recover from.

**Kinds:** Graph, Node, Task, Agent, Harness, Tool, AgentSession, Workflow, Artifact, Capability, Guideline, Policy, GANRun, WebhookSubscription, CustomResourceDefinition

All resources follow the **spec/status pattern** — you declare what you want (spec), the system reconciles toward it and reports what it observes (status).

### Live Execution Plane

OTP and Jido processes host in-flight work. Running model sessions, orchestration loops, harness subprocesses, retry timers.

This plane is **operational, not authoritative**. It must be able to fail and be rebuilt from durable state plus external inputs.

### Historical Audit Plane

Events, artifacts, and attestations record what happened. The event log is append-only and hash-chained. Artifacts are content-addressed and immutable.

This plane provides **provenance, diagnostics, and trust** — but it is not a replacement for current semantic truth.

## The Three Contracts

Each plane has a contract that any backend can implement:

| Contract          | Interface                                              | v1alpha Backend              |
| ----------------- | ------------------------------------------------------ | ---------------------------- |
| **Graph Storage** | create, get, update, list, traverse, query\_by\_labels | Postgres + JSONB + GIN       |
| **Event Log**     | append, query, verify\_chain, stream                   | Postgres (append-only table) |
| **CAS**           | store, resolve, exists?, delete, list\_digests         | Local filesystem             |

The contracts are backend-agnostic. Postgres handles everything for v1alpha. Enterprise deployments can swap backends per contract without changing the API.

## The Work Chain

```
Graph (container)
  └── Node (what needs to happen)
       └── Task (specific work on a workflow step)
            └── AgentSession (an agent doing the work)
                 └── Artifacts (immutable outputs with lineage)
```

## Governance Model

* **Policy** evaluates at admission — before work starts, not after
* **Authority** narrows monotonically from parent to child
* **Review** is mandatory and independent — the producer cannot certify its own output
* **Reflect** is mandatory — every session assesses what went well and what didn't
* **Events** are hash-chained — tamper-evident, externally verifiable