# Architecture

Open Orchestra is a local-first workflow control plane. The CLI remains the
source of truth, while web, VS Code, and agent runtimes use the same workflow
files and JSON command contracts. The canonical diagram source is Mermaid so it
can be reviewed as text and rendered consistently by GitHub, docs tooling, and
the project site.

```mermaid
flowchart LR
  subgraph entry["Entry surfaces"]
    human["Human operator"]
    runtime["Agent runtimes"]
    ide["IDE control center"]
    web["Local web console"]
  end

  subgraph contract["Runtime and CLI contract"]
    bootstrap["Runtime bootstrap"]
    commands["orchestra CLI"]
    manifest["Command manifest"]
    api["JSON contracts"]
  end

  subgraph workflow["Workflow core"]
    intake["Task registry"]
    phases["PM to release phases"]
    gates["Human review gates"]
    skills["Skills and memory"]
    readiness["Release readiness"]
  end

  subgraph state["Local state and adapters"]
    files[".agent-workflow state"]
    providers["Model providers"]
    trackers["Tracker adapters"]
    evidence["Evidence packs"]
    content["Docs manifest"]
  end

  subgraph delivery["Delivery outputs"]
    site["Public site"]
    package["npm package"]
    reports["Handoffs and reports"]
    release["CI release tags"]
  end

  human --> commands
  runtime --> bootstrap
  ide --> api
  web --> api
  bootstrap --> commands
  commands --> manifest
  api --> manifest
  manifest --> phases
  phases --> intake
  phases --> gates
  phases --> skills
  phases --> readiness
  intake --> files
  gates --> evidence
  skills --> files
  phases --> providers
  phases --> trackers
  readiness --> evidence
  content --> site
  readiness --> site
  readiness --> package
  readiness --> release
  evidence --> reports
```

The site renders the same source from
[`site/public/architecture.mmd`](../site/public/architecture.mmd) through the
React + Vite public site with pan, zoom, reset, and fullscreen controls.
The documentation and served Mermaid source must be updated together. See
[Public Site Content Workflow](site-content-workflow.md) for the generated
content contract and diagram QA expectations.

## How To Read It

- **Entry points** are humans, agent runtimes, the local web console, and IDE
  surfaces. They all route through the public `orchestra` command surface.
- **CLI layer** owns command parsing, command manifest metadata, JSON contracts,
  and stable local behavior.
- **Core workflow services** coordinate task graphs, autonomous workflow runs,
  gates, role-scoped memory, skills, and release readiness.
- **State and integrations** stay explicit: `.agent-workflow/` is local
  durable state; model providers and trackers are integration boundaries; docs,
  site, npm, and release tags are delivery outputs.

## Design Principles

- Local workflow state is durable and reviewable.
- Network calls are explicit, opt-in, or CI-owned.
- Tracker integrations use stable child-process calls locally, or runtime MCP
  skills/adapters when the tracker belongs to the agent runtime.
- Release decisions are evidence-based: acceptance coverage, smoke, rollback,
  locks, reviews, and blockers are visible before publish.

## Related Docs

- [MVP guide](orchestra-mvp.md)
- [Advisory supervisor architecture](advisory-supervisor-architecture.md)
- [Persona workflows](persona-workflows.md)
- [Runtime adapters](runtime-adapters.md)
- [Public site content workflow](site-content-workflow.md)
- [Traceability flow](traceability-flow.md)