Architecture

OpRelay sits between your agents and your database. No LLM in the data path — deterministic SQL only.

┌─────────────┐     ┌─────────────────────────┐     ┌──────────┐
│ Claude Code │────▶│       OpRelay           │────▶│          │
│ Codex       │ MCP │  MCP server (stdio/HTTP) │ SQL │  SQLite  │
│ Any agent   │◀────│  Dashboard (React)       │◀────│          │
└─────────────┘     └─────────────────────────┘     └──────────┘

Three pillars

Pillar	What It Does
Observability	Makes agent work legible through runs, failures, usage, facts, and dashboard views
Coordination	Gives agents deterministic task lifecycle, locks, routing, and review handoff
Reconciliation	Syncs state back to external systems and closes the loop on accepted work

Two lanes

Both lanes read from the same data model — the difference is optimization target.

Lane	Consumer	Optimized For
Agent	Live agents, dispatch logic	Throughput, context minimization, compact baton-pass
Human	Operators, reviewers	Legibility, trust, operational oversight (dashboard)

What's included

• 17 MCP tools for shared state, coordination, and audit
• Dashboard with run timelines, fact browsers, task boards, and usage metrics
• Cookie-based auth with admin/operator/viewer roles
• Advisory-lock task claiming for multi-agent coordination
• SQLite (zero-config) or bring your own database

More capabilities coming soon.

Data model

Facts

Structured operational state, scoped by project.

• Key format: {category}.{key} (e.g., infra.database, stack.server.version)
• Confidence (epistemic): how certain — assumed, observed, inferred, confirmed
• Validity (lifecycle): current state — active, stale, superseded, invalid

Decisions

Engineering decisions with rationale and alternatives.

• Status lifecycle: draft → accepted → superseded / rejected

Tasks

Coordinated work items with dependencies.

• Append-only status transitions via task_status_history
• Advisory locking for contention-safe claiming
• Current state derived via views (not mutable columns)

Runs

Immutable audit trail of agent executions.

• Every session records what happened, what changed, and the outcome
• Structured meta_json for files touched, git state, token usage

Design rules

1. No LLM in the read/write path — deterministic SQL only
2. Bounded retrieval — every query enforces limits
3. Project isolation — project_key scoping, no cross-project leakage
4. Append-only for audit — all state changes are immutable events, current state via views
5. Dashboard is read-only — no write operations from the human lane