# andrealaforgia/relay-agentic-framework architecture

> Architecture diagram of the GitHub repository andrealaforgia/relay-agentic-framework, 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/andrealaforgia/relay-agentic-framework
- Repository: https://github.com/andrealaforgia/relay-agentic-framework
- Video tour (about a minute): https://gitdiagram.com/andrealaforgia/relay-agentic-framework/video

## Overview

Relay turns an owner’s problem into acceptance-tested, review-gated delivery increments. The CLI connects the owner to persistent chat, while a deterministic coordinator replays the event ledger, dispatches workers, and applies gates; AI runners perform role-specific analysis and implementation. Evidence execution, review, and ledger auditing are distinct safeguards before checkpoints or PRs. The README documents additional learn, planning, monitoring, usage, and Codex-review capabilities. Sampled source confirms coordinator, bus, runner, review, audit, and Git operations; unsampled subsystem links are limited to documented behavior.

Main entry points: [`src/relay/bus/publisher.py`](https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/bus/publisher.py) (Redis stream bus), [`src/relay/coordinator/main.py`](https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/coordinator/main.py) (Coordinator), [`src/relay/cli/main.py`](https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/cli/main.py) (Relay CLI), [`src/relay/ledger/reader.py`](https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/ledger/reader.py) (Event ledger)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Owner interaction"]
  node_cli["Relay CLI<br/>[main.py]"]
  node_chat["Interpreter chat<br/>[main.py]"]
  node_curator["Curated knowledge"]
  node_watch["Live watch<br/>[watch.py]"]
end

subgraph group_coordination["Deterministic coordination"]
  node_coordinator["Coordinator<br/>[main.py]"]
  node_dispatcher["Dispatcher and gates<br/>[dispatcher.py]"]
  node_projection["State projection<br/>[projection.py]"]
  node_policy["Gate policy<br/>[policy.py]"]
end

subgraph group_delivery["Worker delivery"]
  node_workers["Role workers<br/>[chain.py]"]
  node_preparation["Expectation preparation<br/>[preparation.py]"]
  node_runner["AI runners<br/>[base.py]"]
end

subgraph group_evidence["Evidence and assurance"]
  node_toolgate["Toolgate execution<br/>[toolgate.py]"]
  node_evidence["Evidence replay<br/>[evidence_replay.py]"]
  node_reviews["Review delivery<br/>[reviews.py]"]
end

subgraph group_state["Ledger and integrations"]
  node_contract["Message contract<br/>[validator.py]"]
  node_bus["Redis stream bus<br/>[publisher.py]"]
  node_ledger[("Event ledger<br/>[reader.py]")]
  node_audit["Ledger audit<br/>[audit.py]"]
  node_gitops["Git and PR operations<br/>[pr.py]"]
end

node_owner(("Owner"))
node_assistant(("Claude / Codex"))
node_redis[("Redis")]
node_project["Project repository"]

node_owner -->|"runs commands"| node_cli
node_cli -->|"opens session"| node_chat
node_chat -->|"publishes messages"| node_bus
node_cli -->|"starts learning"| node_curator
node_cli -->|"shows activity"| node_watch
node_coordinator -->|"replays events"| node_ledger
node_ledger -->|"supplies events"| node_projection
node_coordinator -->|"applies events"| node_projection
node_coordinator -->|"reacts to state"| node_dispatcher
node_dispatcher -->|"checks gates"| node_policy
node_dispatcher -->|"dispatches work"| node_bus
node_workers -->|"consumes requests"| node_bus
node_workers -->|"runs role turn"| node_runner
node_runner -.->|"invokes model"| node_assistant
node_preparation -.->|"prepares expectations"| node_assistant
node_workers -->|"handles preparation"| node_preparation
node_coordinator -->|"dispatches gates"| node_toolgate
node_toolgate -->|"runs pinned checks"| node_project
node_toolgate -->|"records execution"| node_evidence
node_workers -->|"validates reviews"| node_reviews
node_reviews -->|"reads review context"| node_ledger
node_reviews -->|"publishes review"| node_bus
node_bus -->|"validates messages"| node_contract
node_bus -->|"reads and writes"| node_redis
node_ledger -->|"reads stream"| node_redis
node_cli -->|"audits ledger"| node_audit
node_audit -->|"scans entries"| node_ledger
node_coordinator -->|"manages branches and PRs"| node_gitops
node_gitops -->|"updates repository"| node_project

click node_cli "https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/cli/main.py"
click node_chat "https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/cli/main.py"
click node_curator "https://github.com/andrealaforgia/relay-agentic-framework/tree/main/src/relay/cli"
click node_watch "https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/cli/watch.py"
click node_coordinator "https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/coordinator/main.py"
click node_dispatcher "https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/coordinator/dispatcher.py"
click node_projection "https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/coordinator/projection.py"
click node_policy "https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/coordinator/policy.py"
click node_workers "https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/workers/chain.py"
click node_preparation "https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/workers/preparation.py"
click node_runner "https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/runners/base.py"
click node_toolgate "https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/workers/toolgate.py"
click node_evidence "https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/workers/evidence_replay.py"
click node_reviews "https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/workers/reviews.py"
click node_contract "https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/contract/validator.py"
click node_bus "https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/bus/publisher.py"
click node_ledger "https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/ledger/reader.py"
click node_audit "https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/ledger/audit.py"
click node_gitops "https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/gitops/pr.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_cli,node_chat,node_curator,node_watch toneBlue
class node_coordinator,node_dispatcher,node_projection,node_policy,node_redis toneAmber
class node_workers,node_preparation,node_runner toneMint
class node_toolgate,node_evidence,node_reviews toneRose
class node_contract,node_bus,node_ledger,node_audit,node_gitops,node_owner,node_assistant,node_project toneIndigo
```

## Components

### Owner interaction

- [Relay CLI](https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/cli/main.py): `src/relay/cli/main.py`
- [Interpreter chat](https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/cli/main.py): `src/relay/cli/main.py`
- [Curated knowledge](https://github.com/andrealaforgia/relay-agentic-framework/tree/main/src/relay/cli): `src/relay/cli`
- [Live watch](https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/cli/watch.py): `src/relay/cli/watch.py`

### Deterministic coordination

- [Coordinator](https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/coordinator/main.py): `src/relay/coordinator/main.py`
- [Dispatcher and gates](https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/coordinator/dispatcher.py): `src/relay/coordinator/dispatcher.py`
- [State projection](https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/coordinator/projection.py): `src/relay/coordinator/projection.py`
- [Gate policy](https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/coordinator/policy.py): `src/relay/coordinator/policy.py`

### Worker delivery

- [Role workers](https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/workers/chain.py): `src/relay/workers/chain.py`
- [Expectation preparation](https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/workers/preparation.py): `src/relay/workers/preparation.py`
- [AI runners](https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/runners/base.py): `src/relay/runners/base.py`

### Evidence and assurance

- [Toolgate execution](https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/workers/toolgate.py): `src/relay/workers/toolgate.py`
- [Evidence replay](https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/workers/evidence_replay.py): `src/relay/workers/evidence_replay.py`
- [Review delivery](https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/workers/reviews.py): `src/relay/workers/reviews.py`

### Ledger and integrations

- [Message contract](https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/contract/validator.py): `src/relay/contract/validator.py`
- [Redis stream bus](https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/bus/publisher.py): `src/relay/bus/publisher.py`
- [Event ledger](https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/ledger/reader.py): `src/relay/ledger/reader.py`
- [Ledger audit](https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/ledger/audit.py): `src/relay/ledger/audit.py`
- [Git and PR operations](https://github.com/andrealaforgia/relay-agentic-framework/blob/main/src/relay/gitops/pr.py): `src/relay/gitops/pr.py`

### Other components

- **Owner**
- **Claude / Codex**
- **Redis**
- **Project repository**

## Connections

- Owner → Relay CLI: runs commands
- Relay CLI → Interpreter chat: opens session
- Interpreter chat → Redis stream bus: publishes messages
- Relay CLI → Curated knowledge: starts learning
- Relay CLI → Live watch: shows activity
- Coordinator → Event ledger: replays events
- Event ledger → State projection: supplies events
- Coordinator → State projection: applies events
- Coordinator → Dispatcher and gates: reacts to state
- Dispatcher and gates → Gate policy: checks gates
- Dispatcher and gates → Redis stream bus: dispatches work
- Role workers → Redis stream bus: consumes requests
- Role workers → AI runners: runs role turn
- AI runners → Claude / Codex: invokes model
- Expectation preparation → Claude / Codex: prepares expectations
- Role workers → Expectation preparation: handles preparation
- Coordinator → Toolgate execution: dispatches gates
- Toolgate execution → Project repository: runs pinned checks
- Toolgate execution → Evidence replay: records execution
- Role workers → Review delivery: validates reviews
- Review delivery → Event ledger: reads review context
- Review delivery → Redis stream bus: publishes review
- Redis stream bus → Message contract: validates messages
- Redis stream bus → Redis: reads and writes
- Event ledger → Redis: reads stream
- Relay CLI → Ledger audit: audits ledger
- Ledger audit → Event ledger: scans entries
- Coordinator → Git and PR operations: manages branches and PRs
- Git and PR operations → Project repository: updates repository