Architecture

These pages are for people working on Open Conduit itself, or anyone who wants to know exactly what it guarantees. To install and run it, start at What Open Conduit does.

How to read these pages

Each page separates three kinds of material:

• Current behaviour and guarantees. The opening and the body of every page describe the code as it is now: what the part does, what it promises and its current limits. A limit stated here is a real limit today.
• Design decisions. Nine pages record a decision, numbered B01 to B09, with its rules and the reasons for them. Code and other pages cite these numbers. The decisions still hold unless the page says otherwise.
• History. Where a page has a History section at the end, it records how that part was built: which delivery ticket (numbered like 02-04) added what, what each stage left out at the time, and the evidence runs made then. Those notes describe the code at the time, not current limitations.

Performance gathers the evidence on throughput, latency, contention and resource use, and names what has not been measured yet.

Core

• Core principles: what belongs in the core and what belongs in an extension
• The core in one page
• Package boundaries and dependency rules (decision B01)
• Primitive and transactional storage contracts (decision B02)
• Ingress, executor, toolbelt and observability contracts (decision B03)
• Routing, waits and recovery semantics (decision B04)
• Configuration, secrets and local management (decision B05), with the configuration schema and its fixtures
• Contracts, supported build targets and development checks (decision B06)

Runtime

• SQLite and local artifact guarantees
• Verified backup bundles
• Durable event acceptance and reconciliation
• Durable routing, Work lifecycle and causal limits
• Execution scheduling, recovery and control
• Durable timers, waits and dependency aliases
• Toolbelt authority, configuration and local management
• Shell executor and CLI toolbelt
• Lifecycle telemetry, unified run history and doctor
• Daemon composition and the kill and restart drills
• Performance

Workloads and integrations

• GitHub ingress, routing policy and projections
• Optional workspaces and the Git provider (decision B07)
• Process sandboxes and the srt provider (decision B09)
• Claude Code executor and private continuity
• Codex executor
• Engineering tools, waits and playbooks
• Slack ingress, conversations and marked replies
• Scheduled jobs
• Observed sources
• Introspection: reporting, sweep, triage and fixes
• Operator setup, doctor and engineering controls
• Installed integrations: Linear, Jira, Bitbucket, PostHog and operator tools
• Backup, restore and state recovery

Extensions (provisional)

• Extension subprocess protocol (decision B08)
• Extension packaging, SDK and certification

Proposals

Pages here describe intended behaviour, not the code as it is. Each is rewritten to describe what was built when it lands, and the pages it changes are amended in the same change.

• Setup sessions and config change sets

Keeping these pages current

If a change alters behaviour a page describes, update the page in the same change: the opening and body must stay true of the code. Record when and why something changed in the page’s History section rather than in the body. The pages live in site/src/content/docs/architecture/, and make docs-check checks their example configs and commands like the rest of the site.