# 33zepha/cortexlab_ architecture

> Architecture diagram of the GitHub repository 33zepha/cortexlab_, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/33zepha/cortexlab_
- Repository: https://github.com/33zepha/cortexlab_

## Overview

#### Purpose and entry points
Cortex Lab is a Node.js governance/runtime system for disciplined AI-agent execution: policy-controlled routing, traceable event recording, and mission-state projection. The core entry points are the runtime modules under `runtime/`, the HTTP/SSE server at `server/index.mjs`, and the Vite-based operational console rooted at `web/src/main.jsx`.

#### Governance source of truth
Constitution files define agent roles and core rules, while generated manifests and registry data provide runtime-consumable policy metadata. This separates human-authored governance from executable lookup structures.
- `constitution/core.yaml`
- `constitution/agents.yaml`
- `manifests/agents.json`
- `registry/registry.json`

#### Registry compilation and controls
Build scripts compile the constitution/control definitions into registry and bundle artifacts used by the runtime. Control schemas encode enforceable invariants such as prohibited debug logging or label conventions, rather than relying on agent discretion.
- `generate-registry.mjs`
- `compile-bundle.mjs`
- `manifests/controls.json`
- `schemas/ctrl-no-debug-log.yaml`

#### Agent routing and authority boundary
The router is the primary authorization/control boundary: it determines whether an agent action is allowed under registered authority and controls. The chief-of-staff module coordinates mission-level agent work, while checks evaluate runtime constraints before or during execution.
- `runtime/router.mjs`
- `runtime/chief-of-staff.mjs`
- `runtime/checks.mjs`

#### Durable event ledger and projections
Execution is captured as newline-delimited ledger events. The event store owns append/read behavior; mission projection derives current mission state from the append-only event history. This makes decisions, transitions, and closures auditable rather than stored only as mutable state.
- `runtime/event-store.mjs`
- `runtime/mission-projection.mjs`
- `ledger/events.ndjson`

#### Service/API and live delivery
The Node server exposes the backend API, runs missions, and streams runtime changes over Server-Sent Events. It is the integration boundary between governance/runtime logic and the browser console; no external hosted service is indicated.
- `server/index.mjs`
- `runtime/chief-of-staff.mjs`
- `runtime/event-store.mjs`

#### Mission-control web console
A separate React/Vite frontend consumes API, router, ledger, and derived dashboard view models to render operational status. Mission Control focuses on execution topology, timeline, health, inspection, and terminal/event docks; Console Overview provides broader operational visibility.
- `web/src/main.jsx`
- `web/src/pages/MissionControl.jsx`
- `web/src/components/dashboard/ExecutionCanvas.jsx`
- `web/src/lib/dashboard-view-model.js`

#### Runtime and infrastructure
Core execution requires Node.js 18+. The frontend is a Vite React application with a development proxy to the backend and production static assets served alongside the Node API/SSE service. CI includes a visual-proof workflow, while tests lock core authority, registry, routing, runtime, and ledger contracts.
- `package.json`
- `web/package.json`
- `web/vite.config.js`
- `.github/workflows/ui-visual-proof.yml`

Main entry points: [`server/index.mjs`](https://github.com/33zepha/cortexlab_/blob/main/server/index.mjs) (Node API & SSE server), [`runtime/event-store.mjs`](https://github.com/33zepha/cortexlab_/blob/main/runtime/event-store.mjs) (Event store), [`runtime/router.mjs`](https://github.com/33zepha/cortexlab_/blob/main/runtime/router.mjs) (Authority router), [`manifests/controls.json`](https://github.com/33zepha/cortexlab_/blob/main/manifests/controls.json) (Control manifest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_governance["Governance"]
  node_constitution["Constitution rules<br/>YAML policy<br/>[core.yaml]"]
  node_agent_roles["Agent roles<br/>YAML policy<br/>[agents.yaml]"]
  node_registry_generator["Registry generator<br/>build script"]
  node_registry[("Authority registry<br/>registry data<br/>[registry.json]")]
  node_control_schema["Control schema<br/>YAML control"]
  node_controls["Control manifest<br/>[controls.json]"]
  node_bundle_compiler["Bundle compiler<br/>build script<br/>[compile-bundle.mjs]"]
  node_agent_manifest["Agent manifest<br/>[agents.json]"]
end

subgraph group_runtime["Runtime"]
  node_router{{"Authority router<br/>runtime module<br/>[router.mjs]"}}
  node_checks["Runtime checks<br/>runtime module<br/>[checks.mjs]"]
  node_chief_of_staff["Chief of staff<br/>runtime module<br/>[chief-of-staff.mjs]"]
  node_event_store["Event store<br/>runtime module<br/>[event-store.mjs]"]
  node_ledger[("Event ledger<br/>NDJSON ledger<br/>[events.ndjson]")]
  node_mission_projection["Mission projection<br/>runtime module"]
end

subgraph group_delivery["Service &amp; Console"]
  node_server{{"Node API &amp; SSE server<br/>HTTP/SSE service<br/>[index.mjs]"}}
  node_web_app["Console entry<br/>React/Vite app<br/>[main.jsx]"]
  node_mission_control["Mission Control<br/>React page<br/>[MissionControl.jsx]"]
  node_execution_canvas["Execution canvas<br/>dashboard component"]
  node_dashboard_view_model["Dashboard view model<br/>frontend model"]
  node_vite_config["Vite proxy &amp; build<br/>frontend config<br/>[vite.config.js]"]
end

node_constitution -->|"compiled into"| node_registry_generator
node_agent_roles -->|"compiled into"| node_registry_generator
node_registry_generator -->|"produces"| node_registry
node_control_schema -->|"defines"| node_controls
node_controls -->|"bundled by"| node_bundle_compiler
node_agent_manifest -->|"bundled by"| node_bundle_compiler
node_registry -->|"authorizes against"| node_router
node_controls -->|"enforces"| node_checks
node_router -->|"evaluates constraints"| node_checks
node_chief_of_staff -->|"routes agent actions"| node_router
node_chief_of_staff -->|"records execution"| node_event_store
node_router -->|"records decisions"| node_event_store
node_event_store -->|"appends and reads"| node_ledger
node_event_store -->|"supplies event history"| node_mission_projection
node_server -->|"runs missions"| node_chief_of_staff
node_server -->|"reads and streams events"| node_event_store
node_server -->|"API and SSE"| node_web_app
node_web_app -->|"renders"| node_mission_control
node_mission_control -->|"composes"| node_execution_canvas
node_dashboard_view_model -->|"feeds view data"| node_mission_control
node_server -->|"supplies runtime data"| node_dashboard_view_model
node_vite_config -.->|"development proxy"| node_server

click node_constitution "https://github.com/33zepha/cortexlab_/blob/main/constitution/core.yaml"
click node_agent_roles "https://github.com/33zepha/cortexlab_/blob/main/constitution/agents.yaml"
click node_registry_generator "https://github.com/33zepha/cortexlab_/blob/main/generate-registry.mjs"
click node_registry "https://github.com/33zepha/cortexlab_/blob/main/registry/registry.json"
click node_control_schema "https://github.com/33zepha/cortexlab_/blob/main/schemas/ctrl-no-debug-log.yaml"
click node_controls "https://github.com/33zepha/cortexlab_/blob/main/manifests/controls.json"
click node_bundle_compiler "https://github.com/33zepha/cortexlab_/blob/main/compile-bundle.mjs"
click node_agent_manifest "https://github.com/33zepha/cortexlab_/blob/main/manifests/agents.json"
click node_router "https://github.com/33zepha/cortexlab_/blob/main/runtime/router.mjs"
click node_checks "https://github.com/33zepha/cortexlab_/blob/main/runtime/checks.mjs"
click node_chief_of_staff "https://github.com/33zepha/cortexlab_/blob/main/runtime/chief-of-staff.mjs"
click node_event_store "https://github.com/33zepha/cortexlab_/blob/main/runtime/event-store.mjs"
click node_ledger "https://github.com/33zepha/cortexlab_/blob/main/ledger/events.ndjson"
click node_mission_projection "https://github.com/33zepha/cortexlab_/blob/main/runtime/mission-projection.mjs"
click node_server "https://github.com/33zepha/cortexlab_/blob/main/server/index.mjs"
click node_web_app "https://github.com/33zepha/cortexlab_/blob/main/web/src/main.jsx"
click node_mission_control "https://github.com/33zepha/cortexlab_/blob/main/web/src/pages/MissionControl.jsx"
click node_execution_canvas "https://github.com/33zepha/cortexlab_/blob/main/web/src/components/dashboard/ExecutionCanvas.jsx"
click node_dashboard_view_model "https://github.com/33zepha/cortexlab_/blob/main/web/src/lib/dashboard-view-model.js"
click node_vite_config "https://github.com/33zepha/cortexlab_/blob/main/web/vite.config.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_constitution,node_agent_roles,node_registry_generator,node_registry,node_control_schema,node_controls,node_bundle_compiler,node_agent_manifest toneBlue
class node_router,node_checks,node_chief_of_staff,node_event_store,node_ledger,node_mission_projection toneAmber
class node_server,node_web_app,node_mission_control,node_execution_canvas,node_dashboard_view_model,node_vite_config toneMint
```

## Components

### Governance

Human rules and executable policy metadata.

- [Constitution rules](https://github.com/33zepha/cortexlab_/blob/main/constitution/core.yaml): YAML policy · Defines core rules and agent roles. · `constitution/core.yaml`
- [Agent roles](https://github.com/33zepha/cortexlab_/blob/main/constitution/agents.yaml): YAML policy · `constitution/agents.yaml`
- [Registry generator](https://github.com/33zepha/cortexlab_/blob/main/generate-registry.mjs): build script · Compiles governance into runtime lookup data. · `generate-registry.mjs`
- [Authority registry](https://github.com/33zepha/cortexlab_/blob/main/registry/registry.json): registry data · Runtime-consumable agent authority metadata. · `registry/registry.json`
- [Control schema](https://github.com/33zepha/cortexlab_/blob/main/schemas/ctrl-no-debug-log.yaml): YAML control · Encodes enforceable runtime invariants. · `schemas/ctrl-no-debug-log.yaml`
- [Control manifest](https://github.com/33zepha/cortexlab_/blob/main/manifests/controls.json): manifest · `manifests/controls.json`
- [Bundle compiler](https://github.com/33zepha/cortexlab_/blob/main/compile-bundle.mjs): build script · `compile-bundle.mjs`
- [Agent manifest](https://github.com/33zepha/cortexlab_/blob/main/manifests/agents.json): manifest · `manifests/agents.json`

### Runtime

Authorization, orchestration, and auditable state.

- [Authority router](https://github.com/33zepha/cortexlab_/blob/main/runtime/router.mjs): runtime module · Primary action authorization and control boundary. · `runtime/router.mjs`
- [Runtime checks](https://github.com/33zepha/cortexlab_/blob/main/runtime/checks.mjs): runtime module · Evaluates execution constraints. · `runtime/checks.mjs`
- [Chief of staff](https://github.com/33zepha/cortexlab_/blob/main/runtime/chief-of-staff.mjs): runtime module · Coordinates mission-level agent work. · `runtime/chief-of-staff.mjs`
- [Event store](https://github.com/33zepha/cortexlab_/blob/main/runtime/event-store.mjs): runtime module · Owns ledger append and read operations. · `runtime/event-store.mjs`
- [Event ledger](https://github.com/33zepha/cortexlab_/blob/main/ledger/events.ndjson): NDJSON ledger · Append-only audit history. · `ledger/events.ndjson`
- [Mission projection](https://github.com/33zepha/cortexlab_/blob/main/runtime/mission-projection.mjs): runtime module · Derives current mission state from events. · `runtime/mission-projection.mjs`

### Service & Console

API/SSE delivery and operational UI.

- [Node API & SSE server](https://github.com/33zepha/cortexlab_/blob/main/server/index.mjs): HTTP/SSE service · Runs missions and bridges runtime to the browser. · `server/index.mjs`
- [Console entry](https://github.com/33zepha/cortexlab_/blob/main/web/src/main.jsx): React/Vite app · `web/src/main.jsx`
- [Mission Control](https://github.com/33zepha/cortexlab_/blob/main/web/src/pages/MissionControl.jsx): React page · Operational execution and timeline console. · `web/src/pages/MissionControl.jsx`
- [Execution canvas](https://github.com/33zepha/cortexlab_/blob/main/web/src/components/dashboard/ExecutionCanvas.jsx): dashboard component · `web/src/components/dashboard/ExecutionCanvas.jsx`
- [Dashboard view model](https://github.com/33zepha/cortexlab_/blob/main/web/src/lib/dashboard-view-model.js): frontend model · Transforms runtime data for operational views. · `web/src/lib/dashboard-view-model.js`
- [Vite proxy & build](https://github.com/33zepha/cortexlab_/blob/main/web/vite.config.js): frontend config · Proxies development traffic and builds production assets. · `web/vite.config.js`

## Connections

- Constitution rules → Registry generator: compiled into
- Agent roles → Registry generator: compiled into
- Registry generator → Authority registry: produces
- Control schema → Control manifest: defines
- Control manifest → Bundle compiler: bundled by
- Agent manifest → Bundle compiler: bundled by
- Authority registry → Authority router: authorizes against
- Control manifest → Runtime checks: enforces
- Authority router → Runtime checks: evaluates constraints
- Chief of staff → Authority router: routes agent actions
- Chief of staff → Event store: records execution
- Authority router → Event store: records decisions
- Event store → Event ledger: appends and reads
- Event store → Mission projection: supplies event history
- Node API & SSE server → Chief of staff: runs missions
- Node API & SSE server → Event store: reads and streams events
- Node API & SSE server → Console entry: API and SSE
- Console entry → Mission Control: renders
- Mission Control → Execution canvas: composes
- Dashboard view model → Mission Control: feeds view data
- Node API & SSE server → Dashboard view model: supplies runtime data
- Vite proxy & build → Node API & SSE server: development proxy