# pkjaslam/cambium_ai architecture

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

- Interactive diagram: https://gitdiagram.com/pkjaslam/cambium_ai
- Repository: https://github.com/pkjaslam/cambium_ai

## Overview

Cambium is a local-first, human-governed AI research institute: a task is routed to specialist work, paused at human decision gates, independently checked, and carried into reporting and close-out. The graph includes its documented council stages and major capabilities, plus the sampled router, web bridge, and MCP entry point. The README documents broader council and learning behavior than the sampled source verifies, so those links reflect documented workflow rather than inspected implementation details.

Main entry points: [`tools/cambium_run.py`](https://github.com/pkjaslam/cambium_ai/blob/main/tools/cambium_run.py) (Run orchestrator), [`mcp_server/cambium_mcp/server.py`](https://github.com/pkjaslam/cambium_ai/blob/main/mcp_server/cambium_mcp/server.py) (MCP server), [`tools/task_router.py`](https://github.com/pkjaslam/cambium_ai/blob/main/tools/task_router.py) (Task router), [`web/server/engine.py`](https://github.com/pkjaslam/cambium_ai/blob/main/web/server/engine.py) (Streamed run engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Research workflow"]
  node_run["Run orchestrator<br/>[cambium_run.py]"]
  node_router["Task router<br/>[task_router.py]"]
  node_scouts["Scouting<br/>[cambium_run.py]"]
  node_labs["Lab design<br/>[cambium_run.py]"]
  node_execution["Execution<br/>[cambium_run.py]"]
  node_verification["Verification board<br/>[cambium_run.py]"]
  node_reporting["Reporting<br/>[cambium_run.py]"]
end

subgraph group_governance["Governance and records"]
  node_human_gate["Human gates<br/>[gate.py]"]
  node_enforcement["Enforcement checks<br/>[enforce.py]"]
  node_run_state[("Run records<br/>[run_state.py]")]
  node_audit_log["Audit ledger<br/>[audit_log.py]"]
  node_learning["Learning delivery"]
end

subgraph group_interfaces["User interfaces"]
  node_web_ui["3D web interface<br/>[App.jsx]"]
  node_web_api["Bridge API<br/>[app.py]"]
  node_web_engine["Streamed run engine<br/>[engine.py]"]
  node_mcp["MCP server<br/>[server.py]"]
end

subgraph group_capabilities["Research support"]
  node_preaward["Proposal support<br/>[budget_review.py]"]
  node_disclosure["AI-use disclosure<br/>[ai_disclosure.py]"]
  node_memory["Finding recall<br/>[memory_recall.py]"]
  node_concept_graph["Concept graph<br/>[concept_graph.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"submits task"| node_run
node_run -->|"requests plan"| node_router
node_router -->|"returns phases"| node_run
node_run -->|"dispatches work"| node_scouts
node_run -->|"dispatches work"| node_labs
node_run -->|"dispatches work"| node_execution
node_run -->|"dispatches work"| node_verification
node_run -->|"dispatches work"| node_reporting
node_run -->|"pauses at gates"| node_human_gate
node_researcher -->|"decides"| node_human_gate
node_run -->|"records run"| node_run_state
node_human_gate -->|"logs decision"| node_audit_log
node_run -->|"checks controls"| node_enforcement
node_run -->|"delivers packet"| node_learning
node_researcher -->|"uses"| node_web_ui
node_web_ui -.->|"sends requests"| node_web_api
node_web_api -->|"creates run"| node_web_engine
node_web_engine -->|"routes task"| node_router
node_web_engine -->|"streams gate events"| node_researcher
node_researcher -->|"invokes tools"| node_mcp
node_mcp -->|"plans task"| node_router
node_mcp -->|"runs review"| node_preaward
node_mcp -->|"runs tool"| node_disclosure
node_mcp -->|"queries findings"| node_memory
node_mcp -->|"queries graph"| node_concept_graph

click node_run "https://github.com/pkjaslam/cambium_ai/blob/main/tools/cambium_run.py"
click node_router "https://github.com/pkjaslam/cambium_ai/blob/main/tools/task_router.py"
click node_scouts "https://github.com/pkjaslam/cambium_ai/blob/main/tools/cambium_run.py"
click node_labs "https://github.com/pkjaslam/cambium_ai/blob/main/tools/cambium_run.py"
click node_execution "https://github.com/pkjaslam/cambium_ai/blob/main/tools/cambium_run.py"
click node_verification "https://github.com/pkjaslam/cambium_ai/blob/main/tools/cambium_run.py"
click node_reporting "https://github.com/pkjaslam/cambium_ai/blob/main/tools/cambium_run.py"
click node_human_gate "https://github.com/pkjaslam/cambium_ai/blob/main/tools/gate.py"
click node_enforcement "https://github.com/pkjaslam/cambium_ai/blob/main/tools/enforce.py"
click node_run_state "https://github.com/pkjaslam/cambium_ai/blob/main/tools/run_state.py"
click node_audit_log "https://github.com/pkjaslam/cambium_ai/blob/main/tools/audit_log.py"
click node_learning "https://github.com/pkjaslam/cambium_ai/blob/main/tools/learning_delivery.py"
click node_web_ui "https://github.com/pkjaslam/cambium_ai/blob/main/web/frontend-r3f/src/App.jsx"
click node_web_api "https://github.com/pkjaslam/cambium_ai/blob/main/web/server/app.py"
click node_web_engine "https://github.com/pkjaslam/cambium_ai/blob/main/web/server/engine.py"
click node_mcp "https://github.com/pkjaslam/cambium_ai/blob/main/mcp_server/cambium_mcp/server.py"
click node_preaward "https://github.com/pkjaslam/cambium_ai/blob/main/tools/budget_review.py"
click node_disclosure "https://github.com/pkjaslam/cambium_ai/blob/main/tools/ai_disclosure.py"
click node_memory "https://github.com/pkjaslam/cambium_ai/blob/main/tools/memory_recall.py"
click node_concept_graph "https://github.com/pkjaslam/cambium_ai/blob/main/tools/concept_graph.py"

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_run,node_router,node_scouts,node_labs,node_execution,node_verification,node_reporting toneBlue
class node_human_gate,node_enforcement,node_run_state,node_audit_log,node_learning toneAmber
class node_web_ui,node_web_api,node_web_engine,node_mcp toneMint
class node_preaward,node_disclosure,node_memory,node_concept_graph toneRose
class node_researcher toneIndigo
```

## Components

### Research workflow

- [Run orchestrator](https://github.com/pkjaslam/cambium_ai/blob/main/tools/cambium_run.py): `tools/cambium_run.py`
- [Task router](https://github.com/pkjaslam/cambium_ai/blob/main/tools/task_router.py): `tools/task_router.py`
- [Scouting](https://github.com/pkjaslam/cambium_ai/blob/main/tools/cambium_run.py): `tools/cambium_run.py`
- [Lab design](https://github.com/pkjaslam/cambium_ai/blob/main/tools/cambium_run.py): `tools/cambium_run.py`
- [Execution](https://github.com/pkjaslam/cambium_ai/blob/main/tools/cambium_run.py): `tools/cambium_run.py`
- [Verification board](https://github.com/pkjaslam/cambium_ai/blob/main/tools/cambium_run.py): `tools/cambium_run.py`
- [Reporting](https://github.com/pkjaslam/cambium_ai/blob/main/tools/cambium_run.py): `tools/cambium_run.py`

### Governance and records

- [Human gates](https://github.com/pkjaslam/cambium_ai/blob/main/tools/gate.py): `tools/gate.py`
- [Enforcement checks](https://github.com/pkjaslam/cambium_ai/blob/main/tools/enforce.py): `tools/enforce.py`
- [Run records](https://github.com/pkjaslam/cambium_ai/blob/main/tools/run_state.py): `tools/run_state.py`
- [Audit ledger](https://github.com/pkjaslam/cambium_ai/blob/main/tools/audit_log.py): `tools/audit_log.py`
- [Learning delivery](https://github.com/pkjaslam/cambium_ai/blob/main/tools/learning_delivery.py): `tools/learning_delivery.py`

### User interfaces

- [3D web interface](https://github.com/pkjaslam/cambium_ai/blob/main/web/frontend-r3f/src/App.jsx): `web/frontend-r3f/src/App.jsx`
- [Bridge API](https://github.com/pkjaslam/cambium_ai/blob/main/web/server/app.py): `web/server/app.py`
- [Streamed run engine](https://github.com/pkjaslam/cambium_ai/blob/main/web/server/engine.py): `web/server/engine.py`
- [MCP server](https://github.com/pkjaslam/cambium_ai/blob/main/mcp_server/cambium_mcp/server.py): `mcp_server/cambium_mcp/server.py`

### Research support

- [Proposal support](https://github.com/pkjaslam/cambium_ai/blob/main/tools/budget_review.py): `tools/budget_review.py`
- [AI-use disclosure](https://github.com/pkjaslam/cambium_ai/blob/main/tools/ai_disclosure.py): `tools/ai_disclosure.py`
- [Finding recall](https://github.com/pkjaslam/cambium_ai/blob/main/tools/memory_recall.py): `tools/memory_recall.py`
- [Concept graph](https://github.com/pkjaslam/cambium_ai/blob/main/tools/concept_graph.py): `tools/concept_graph.py`

### Other components

- **Researcher**

## Connections

- Researcher → Run orchestrator: submits task
- Run orchestrator → Task router: requests plan
- Task router → Run orchestrator: returns phases
- Run orchestrator → Scouting: dispatches work
- Run orchestrator → Lab design: dispatches work
- Run orchestrator → Execution: dispatches work
- Run orchestrator → Verification board: dispatches work
- Run orchestrator → Reporting: dispatches work
- Run orchestrator → Human gates: pauses at gates
- Researcher → Human gates: decides
- Run orchestrator → Run records: records run
- Human gates → Audit ledger: logs decision
- Run orchestrator → Enforcement checks: checks controls
- Run orchestrator → Learning delivery: delivers packet
- Researcher → 3D web interface: uses
- 3D web interface → Bridge API: sends requests
- Bridge API → Streamed run engine: creates run
- Streamed run engine → Task router: routes task
- Streamed run engine → Researcher: streams gate events
- Researcher → MCP server: invokes tools
- MCP server → Task router: plans task
- MCP server → Proposal support: runs review
- MCP server → AI-use disclosure: runs tool
- MCP server → Finding recall: queries findings
- MCP server → Concept graph: queries graph