Architecture Diagrams

1. Control Plane and Entrypoints

External clients stay on a short path while Nexus picks the execution shape internally.

flowchart LR Client["Client (Codex, Cursor, Claude, Windsurf, Antigravity)"] Bootstrap["nexus_session_bootstrap"] Orchestrate["nexus_orchestrate"] Plan["nexus_plan_execution (optional)"] Runtime["SubAgent Runtime"] Dashboard["Dashboard + API"] Client --> Bootstrap Bootstrap --> Plan Bootstrap --> Orchestrate Plan --> Orchestrate Orchestrate --> Runtime Runtime --> Dashboard Runtime --> Client

The public contract stays small even when the internal runtime is richer.

2. Orchestration Contract

Every non-trivial run passes through the same decision path before mutation.

flowchart TD Start["Bootstrap session"] Recall["Recall memory + stats"] Decompose["Task graph + worker plan"] Budget["Source-aware token budget"] Score["Artifact scoring"] Audit["Artifact selection audit"] Execute["Runtime execution"] Verify["Verification + governance"] Learn["Learning + continuation decision"] Start --> Recall --> Decompose --> Budget --> Score --> Audit --> Execute --> Verify --> Learn

The planner, artifact audit, and token budget are part of the normal runtime contract, not optional operator rituals.

3. Worktree Execution Lifecycle

Runtime workers and verifiers run in isolated worktrees, with preflight repair and bounded failure handling.

sequenceDiagram participant O as Orchestrator participant D as Worktree Doctor participant G as Git Worktree participant C as Coder Worker participant V as Verifier participant R as Runtime Snapshot O->>D: inspect + prune stale metadata D-->>O: health snapshot O->>G: git worktree add --detach G-->>C: isolated worktree C->>V: handoff candidate patch V->>R: record verification result + worktree health V->>G: cleanup worktree G-->>R: cleanup status

If worktree creation degrades, Nexus records that explicitly and returns a short remediation path instead of a raw git wall.

4. Memory Fabric and Reconciliation

Nexus stores distilled facts, decisions, and failure modes rather than treating raw transcripts as first-class long-term memory.

flowchart LR Input["Run output / worker output / operator note"] Extract["Fact extractor"] Reconcile["Memory reconciler"] Decision{"Action"} Graph["Graph projector"] Vault["Vault projector"] Scopes["Session / Shared / Project / User / Promoted"] Input --> Extract --> Reconcile --> Decision Decision -->|ADD / UPDATE / MERGE| Graph Decision -->|QUARANTINE / DELETE / NONE| Scopes Graph --> Vault Vault --> Scopes

Relevance, importance, trust, freshness, scope, and state stay attached to every memory item.

5. RAG Ingestion and Retrieval Gate

RAG remains session-first and orchestrator-owned. Collections are never dumped wholesale into the runtime prompt.

flowchart TD Source["File / URL / Raw text"] Ingest["Chunk + embed + tag"] Attach["Attach collection to runtime"] Gate["RAG gate"] Select["Top matching chunks"] Drop["Dropped by budget"] Packet["Planner / packet / runtime context"] Memory["Distilled facts only"] Source --> Ingest --> Attach --> Gate Gate --> Select --> Packet Gate --> Drop Packet --> Memory

Only distilled facts can promote into longer-lived memory, and even that goes through reconciliation and provenance checks.

6. Source-Aware Token Budget

Budgeting spans repo, memory, RAG, patterns, and runtime traces across planning and execution phases.

flowchart TD Sources["Repo + Memory + RAG + Patterns + Runtime traces"] Rank["Rank by relevance, trust, and cost"] Allocate["Allocate by phase"] Keep["Selected context"] Skip["Dropped context"] Trace["Persisted by-source telemetry"] Sources --> Rank --> Allocate Allocate --> Keep Allocate --> Skip Keep --> Trace Skip --> Trace

The dashboard can answer where tokens came from, what was compressed away, and what the latest orchestrated run actually spent them on.

7. Dashboard and Runtime Truth Data Flow

The UI does not invent state from whichever process hosts it. It renders persisted runtime snapshots.

flowchart LR Runtime["Runtime snapshot"] Registry["Runtime registry"] API["Dashboard API"] UI["Dashboard views"] Inspector["Inspector + event stream"] Runtime --> Registry --> API --> UI Registry --> Inspector API --> Inspector

Lifetime token telemetry, worktree health, artifact audit, worker plan, client bootstrap truth, and memory health all flow from persisted runtime data.

8. CI and Release Pipeline

Release readiness is treated as an explicit pipeline instead of a loose checklist.

flowchart LR PR["Pull request"] Quality["Build + lint + tests + pack dry-run"] Audit["Dependency audit + workflow lint"] Smoke["Bootstrap + setup + dashboard + MCP smoke"] Merge["Merge to main"] Pages["Docs deploy"] Release["GitHub release + npm publish"] PR --> Quality --> Audit --> Smoke --> Merge --> Pages --> Release

The same quality path should back local QA, PR checks, docs deploy confidence, and publish readiness.

Architecture that matches the product you can run today.