CortexBuild — System Architecture (v0.1)¶
┌─────────────────────────────────────────────────────────────────────┐
│ CortexBuild CONTROL PLANE │
│ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ Web UI (Next.js 15 + Tailwind + shadcn/ui) │ │
│ │ • Project list │ │
│ │ • Task board (Linear-style; PM-persona language) │ │
│ │ • Agent timeline (real-time; tech-lead-persona detail) │ │
│ │ • Approval queue (PR merge, deploy, spend, secrets) │ │
│ │ • Settings: provider keys, autonomy matrix, rule packs │ │
│ │ • Audit log viewer (filterable, exportable) │ │
│ │ • Cost dashboard ($ per task, per agent, per provider) │ │
│ └────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
│ WebSocket (progress, approvals)
│ REST (commands, queries)
▼
┌─────────────────────────────────────────────────────────────────────┐
│ ORCHESTRATOR SERVICE (Python 3.12 + FastAPI) │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │
│ │ Phase Sequencer │ │ Rule SSoT │ │ Recurrence Ledger │ │
│ │ (wave model) │ │ Engine │ │ Persister │ │
│ │ │ │ │ │ │ │
│ │ Plan→Critic→ │ │ Renders rules │ │ Post-mortem capture │ │
│ │ Build→[T∥S∥O] │ │ to all enabled │ │ → ledger entry │ │
│ │ →PR Reviewer │ │ provider tools │ │ → new rule draft │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │
│ │ Provider Router │ │ Approval Gate │ │ Audit Log Writer │ │
│ │ │ │ State Machine │ │ │ │
│ │ Claude/Copilot/ │ │ Auto/Notify/ │ │ Every shell op, │ │
│ │ Codex/Bedrock/ │ │ Approve per │ │ file edit, API call │ │
│ │ Vertex/Ollama │ │ action class │ │ → Postgres + S3 │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐│
│ │ Multi-tenant data layer (Postgres + Redis) ││
│ │ • projects, users, sessions, approvals, tasks, agents, runs ││
│ │ • audit_log, recurrence_ledger, rule_packs, llm_provider_keys ││
│ └─────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────┘
│ │
│ spawns workspace │ invokes LLM
▼ ▼
┌──────────────────────────────────────┐ ┌──────────────────────────┐
│ EXECUTION RUNTIME │ │ LLM PROVIDER APIs │
│ (Daytona devcontainer) │ │ │
│ │ │ • Anthropic (Claude) │
│ Per-project sandbox VM: │ │ • OpenAI (GPT/Codex) │
│ • Repo clone (read-write) │ │ • GitHub Copilot CLI │
│ • Toolchain auto-install │ │ • Bedrock │
│ (node, python, go, rust, java) │ │ • Vertex │
│ • Provider CLIs │ │ • Ollama (local) │
│ (gh, claude, codex, etc.) │ │ │
│ • Network egress firewall │ │ Keys: BYO, encrypted │
│ • Resource limits (cgroups) │ │ at rest (KMS), never │
│ • Audit-logged shell │ │ leave control plane │
└──────────────────────────────────────┘ └──────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────┐
│ USER'S GIT PROVIDER (external) │
│ │
│ GitHub / GitLab / Bitbucket / Azure DevOps │
│ Branches, PRs, issues, comments — CortexBuild writes here │
│ User reviews in their normal git UI; CortexBuild never blocks merge │
└──────────────────────────────────────────────────────────────────────┘
Diagram legend (adjacent qualifiers). In the boxes above: Bedrock / Vertex are reachable via an OpenAI-compatible gateway only — no native adapter (roadmap); native providers = Claude, Gemini, OpenAI-compatible. The Execution Runtime (Daytona devcontainer) box is Phase 1 — planned 🔜, not yet shipped.
Status — roadmap vs shipped. This diagram shows the full target architecture. Shipped today (P0): rule SSoT + 4-surface
render, the recurrenceledger, brownfield analysis, and offline conformance/eval. Planned (not yet shipped): the Execution Runtime (Daytona devcontainer / per-project sandbox) is Phase 1 — planned 🔜; the fully autonomous orchestrator control loop and the 20-action-class approval matrix are later phases. Provider note: native providers today are Anthropic (Claude), Gemini, and any OpenAI-compatible endpoint — Bedrock / Vertex / Azure OpenAI are reachable only via an OpenAI-compatible gateway (no native adapter).
Component responsibilities¶
Web UI (Next.js)¶
- Authenticated dashboard
- Real-time updates via WebSocket
- Approval dialogs (blocking when needed)
- Persona toggle (PM ↔ tech-lead)
- BYO key management (write-only forms)
Orchestrator Service (FastAPI)¶
- Stateless API + stateful workers
- Multi-tenant: project = tenant boundary
- Long-running task supervision
- Provider adapter abstraction
- Rule rendering (port of
render-agents.ps1) - Recurrence ledger CRUD
- Audit log emission
Execution Runtime (Daytona) — Phase 1, planned 🔜¶
- One devcontainer per project, persistent
- Toolchain installers triggered by detected stack
- Provider CLIs preinstalled (or installed on-demand)
- Shell wrapped to log every command
- Network egress firewall (allow git provider + LLM APIs only by default)
- Filesystem snapshots before risky operations
LLM Provider APIs¶
- Calls happen from the orchestrator (not the VM) for cost tracking + key isolation
- VM only ever talks to its repo + the orchestrator
- Orchestrator caches plan outputs
Boundaries (what runs where)¶
| Concern | Control Plane | VM | Git Provider | LLM API |
|---|---|---|---|---|
| Repo clone | — | ✅ | (source) | — |
| Code edit | — | ✅ | — | — |
| LLM call | ✅ (router) | — | — | (target) |
| Rule rendering | ✅ | — | — | — |
| PR open | (orchestrates) | ✅ (gh pr create) |
(target) | — |
| Approval dialog | ✅ | — | — | — |
| Audit log write | ✅ | (emits events) | — | — |
| Recurrence ledger | ✅ | — | — | — |
| Secrets storage | ✅ (KMS) | (env vars at runtime) | — | — |
Data model (top-level tables)¶
-- Tenancy
projects (id, slug, owner_user_id, repo_url, git_provider, status, created_at)
users (id, email, oauth_provider, oauth_id, persona_default, created_at)
project_members (project_id, user_id, role) -- owner | admin | member | viewer
-- Configuration
provider_keys (id, project_id, provider, key_ciphertext, kms_key_id, created_at)
autonomy_matrix (project_id, action_class, level, updated_by, updated_at)
rule_packs_enabled (project_id, pack_name, pack_version, enabled_at)
-- Work
tasks (id, project_id, source, source_id, title, body, complexity, confidence, status, ...)
runs (id, task_id, branch_name, status, started_at, ended_at, cost_usd, ...)
agent_invocations (id, run_id, agent_id, provider, model, prompt_tokens, completion_tokens, latency_ms, ...)
-- Approvals
approvals (id, project_id, run_id, action_class, payload_json, requested_at, decided_at, decision, decided_by)
-- Governance
audit_log (id, project_id, run_id, actor_type, actor_id, action, target, payload_json, ts)
recurrence_ledger (id, project_id, class, severity, agent, symptom, root_cause, fix, guard_id, status, automation_target, ts)
-- Rule SSoT
rule_packs (id, slug, version, source_url, signed_by, content_hash)
rendered_targets (project_id, target_tool, target_path, content_hash, rendered_at)
Provider Adapter interface¶
class ProviderAdapter(Protocol):
name: str # "claude_code" | "copilot_cli" | "codex" | "bedrock" | ... (bedrock/vertex = gateway-only, no native adapter)
async def invoke(
self,
prompt: str,
*,
system: str | None = None,
tools: list[ToolDef] | None = None,
model_hint: ModelTier, # "reasoning_heavy" | "balanced" | "fast_cheap"
max_tokens: int = 4096,
timeout_seconds: int = 300,
) -> InvocationResult: ...
async def stream(self, ...) -> AsyncIterator[StreamChunk]: ...
def estimate_cost(self, prompt: str, model_hint: ModelTier) -> Decimal: ...
def capabilities(self) -> set[Capability]:
# {CODE_EXECUTION, WEB_BROWSE, FILE_IO, VISION, LONG_CONTEXT}
...
async def rate_limit_status(self) -> RateLimitStatus: ...
async def health_check(self) -> HealthStatus:
# Daily smoke test from CI hits this
...
Phase Sequencer (wave model)¶
Ported from CortexVigil rule-phase-sequence:
Wave 1a: Planner (sequential)
Wave 1b: Critic (conditional — skip for trivial low-risk plans)
Wave 2: Builder (sequential — only writer)
Wave 3: Tester ∥ Security ∥ Optimizer (parallel — all read-only)
Wave 4: PR Reviewer (sequential)
State machine guarantees: agents never run out of order; waves block on previous wave's completion; wave 3 parallelism is opt-in per runtime capability.
Approval Gate State Machine¶
Action requested by agent
│
▼
┌──────────────────┐
│ Lookup autonomy │
│ level for class │
└──────────────────┘
│
▼
┌───────┐ AUTO ┌──────────────┐
│ Level │──────────►│ Execute now │──► Audit log
└───┬───┘ └──────────────┘
│ NOTIFY ┌──────────────┐ ┌──────────────┐
├──────────────►│ Execute now │─►│ Notify UI │──► 5-min rollback window
│ └──────────────┘ └──────────────┘
│
│ APPROVE ┌──────────────┐ ┌──────────────┐ ┌─────────────┐
└──────────────►│ Pause agent │─►│ UI prompts │─►│ User decides│
└──────────────┘ └──────────────┘ └──────┬──────┘
│
Yes ┌──────┴──────┐ No
▼ ▼
┌────────────┐ ┌────────────┐
│ Execute │ │ Abort task │
│ + audit │ │ + audit │
└────────────┘ └────────────┘
Sequence: Onboarding a brownfield repo¶
User UI Orchestrator VM (Daytona) LLM Provider
│ │ │ │ │
│ Connect repo URL │ │ │ │
│────────────────────►│ │ │ │
│ │ POST /projects │ │ │
│ │───────────────────►│ │ │
│ │ │ Create workspace│ │
│ │ │─────────────────►│ │
│ │ │ │ Clone repo │
│ │ │ │ Detect toolchain │
│ │ │ │ Install tools │
│ │ │ │ Run graphify │
│ │ │◄─────────────────│ Structural report │
│ │ │ │ │
│ │ │ Invoke Analyser │ │
│ │ │─────────────────────────────────────►│
│ │ │◄─────────────────────────────────────│ Inferred rules
│ │ │ │ │ + heatmap
│ │ Show heatmap + Q1 │ │ │
│ │◄───────────────────│ │ │
│ Answer Q1..Qn │ │ │ │
│◄────────────────────│ │ │ │
│ │ POST answers │ │ │
│ │───────────────────►│ │ │
│ │ │ Render rule pack│ │
│ │ │ → .CortexBuild/ │ │
│ │ │ Push to repo │ │
│ │ │─────────────────►│ │
│ │ │ │ git push origin │
│ │ │ │ "CortexBuild init" │
│ │ │ │ │
│ │ Show first roadmap│ │ │
│ │◄───────────────────│ │ │
│ Approve roadmap │ │ │ │
│────────────────────►│ │ │ │
│ │ POST /run/start │ │ │
│ │───────────────────►│ │ │
│ │ │ │ │
│ │ …work begins… │ │ │
Note: the VM (Daytona) lane above is the Phase 1 — planned 🔜 execution runtime, not yet shipped.
Failure modes + handling¶
| Failure | Detection | Response |
|---|---|---|
| LLM provider timeout | Adapter timeout (300s) | Retry once with smaller model; surface to user if both fail |
| Provider rate limit | HTTP 429 | Queue; backoff; route to alternate provider if user enabled |
| VM crash | Daytona health check | Restart workspace; resume from last checkpoint (planned runtime — Phase 1 🔜) |
| Git push rejected | Exit code from git push |
Open issue on repo; pause project; notify user |
| Approval timeout | No user response in 24h | Auto-decline; surface in dashboard |
| Budget exceeded | Cost meter | Pause project; notify user; require explicit unblock |
| Recurring same-class failure | Ledger query | Auto-promote to enforced rule; stop attempting that class |
| Provider key revoked | Adapter auth error | Mark project paused; notify user via email + UI |
| Worker process OOM | Container metrics | Auto-restart; failed task flagged for manual review |