# cordum-io/cordum architecture

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

- Interactive diagram: https://gitdiagram.com/cordum-io/cordum
- Repository: https://github.com/cordum-io/cordum

## Overview

Cordum is an AI-agent control plane with an Edge compliance firewall. The principal workflow is an API or edge event entering the gateway, passing governance and safety controls, then being dispatched by the scheduler or executed as a workflow; outcomes and audit evidence are surfaced through the API and dashboard. The README documents the service stack, while source-index references and excerpts support selected internal relationships. Many subsystem details are unsampled, so their links are omitted rather than inferred.

Main entry points: [`core/controlplane/gateway`](https://github.com/cordum-io/cordum/tree/main/core/controlplane/gateway) (API Gateway), [`core/controlplane/scheduler/engine.go`](https://github.com/cordum-io/cordum/blob/main/core/controlplane/scheduler/engine.go) (Job Scheduler), [`core/controlplane/gateway/handlers_edge_llm_ingest.go`](https://github.com/cordum-io/cordum/blob/main/core/controlplane/gateway/handlers_edge_llm_ingest.go) (Edge Event Ingest), [`core/workflow/engine.go`](https://github.com/cordum-io/cordum/blob/main/core/workflow/engine.go) (Workflow Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Access and Edge"]
  node_gateway["API Gateway"]
  node_edge_ingest["Edge Event Ingest"]
  node_agentd["Edge Agent<br/>[app.go]"]
  node_mcp["MCP Service<br/>[server.go]"]
  node_dashboard["Dashboard<br/>[App.tsx]"]
end

subgraph group_govern["Governance and Safety"]
  node_governance["Policy Evaluation<br/>[evaluator.go]"]
  node_actiongates["Action Gates<br/>[pipeline.go]"]
  node_safety["Safety Kernel<br/>[kernel.go]"]
  node_policybundles["Policy Bundles<br/>[bundles.go]"]
end

subgraph group_execution["Execution"]
  node_scheduler["Job Scheduler<br/>[engine.go]"]
  node_workflow["Workflow Engine<br/>[engine.go]"]
  node_worker["Agent Worker<br/>[worker.go]"]
  node_context["Context Engine<br/>[service.go]"]
  node_jobstore[("Job Store<br/>[job_store.go]")]
end

subgraph group_operations["Visibility and Operations"]
  node_audit["Audit Pipeline<br/>[consumer.go]"]
  node_edge_store[("Edge Event Store<br/>[store.go]")]
  node_evals["Evaluation Extraction<br/>[pipeline.go]"]
  node_sdk["Client SDK<br/>[client.go]"]
end

node_user(("API Client"))
node_external_proxy(("LLM Proxy"))

node_user -->|"submits requests"| node_gateway
node_gateway -.->|"evaluates policy"| node_governance
node_gateway -.->|"submits jobs"| node_scheduler
node_scheduler -.->|"checks safety"| node_safety
node_scheduler -.->|"persists jobs"| node_jobstore
node_scheduler -.->|"dispatches work"| node_worker
node_workflow -->|"publishes job packets"| node_scheduler
node_gateway -.->|"manages workflows"| node_workflow
node_external_proxy -->|"sends LLM events"| node_edge_ingest
node_edge_ingest -->|"appends events"| node_edge_store
node_agentd -.->|"reports edge activity"| node_gateway
node_mcp -->|"uses gateway handlers"| node_gateway
node_gateway -.->|"applies action gates"| node_actiongates
node_gateway -.->|"serves policy bundles"| node_policybundles
node_gateway -.->|"provides context service"| node_context
node_dashboard -.->|"requests status"| node_gateway
node_sdk -.->|"calls API"| node_gateway
node_gateway -.->|"exports audit records"| node_audit
node_evals -->|"queries decisions"| node_jobstore
node_edge_ingest -->|"classifies interactions"| node_safety

click node_gateway "https://github.com/cordum-io/cordum/tree/main/core/controlplane/gateway"
click node_edge_ingest "https://github.com/cordum-io/cordum/blob/main/core/controlplane/gateway/handlers_edge_llm_ingest.go"
click node_agentd "https://github.com/cordum-io/cordum/blob/main/core/edge/agentd/app.go"
click node_mcp "https://github.com/cordum-io/cordum/blob/main/core/mcp/server.go"
click node_dashboard "https://github.com/cordum-io/cordum/blob/main/dashboard/src/App.tsx"
click node_governance "https://github.com/cordum-io/cordum/blob/main/core/governance/evaluator/evaluator.go"
click node_actiongates "https://github.com/cordum-io/cordum/blob/main/core/policy/actiongates/pipeline.go"
click node_safety "https://github.com/cordum-io/cordum/blob/main/core/controlplane/safetykernel/kernel.go"
click node_policybundles "https://github.com/cordum-io/cordum/blob/main/core/controlplane/gateway/policybundles/bundles.go"
click node_scheduler "https://github.com/cordum-io/cordum/blob/main/core/controlplane/scheduler/engine.go"
click node_workflow "https://github.com/cordum-io/cordum/blob/main/core/workflow/engine.go"
click node_worker "https://github.com/cordum-io/cordum/blob/main/sdk/runtime/worker.go"
click node_context "https://github.com/cordum-io/cordum/blob/main/core/contextwindow/engine/service.go"
click node_jobstore "https://github.com/cordum-io/cordum/blob/main/core/infra/store/job_store.go"
click node_audit "https://github.com/cordum-io/cordum/blob/main/core/audit/consumer.go"
click node_edge_store "https://github.com/cordum-io/cordum/blob/main/core/edge/store.go"
click node_evals "https://github.com/cordum-io/cordum/blob/main/core/evals/extraction/pipeline.go"
click node_sdk "https://github.com/cordum-io/cordum/blob/main/sdk/client/client.go"

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_gateway,node_edge_ingest,node_agentd,node_mcp,node_dashboard,node_user toneBlue
class node_governance,node_actiongates,node_safety,node_policybundles toneAmber
class node_scheduler,node_workflow,node_worker,node_context,node_jobstore toneMint
class node_audit,node_edge_store,node_evals,node_sdk toneRose
class node_external_proxy toneIndigo
```

## Components

### Access and Edge

- [API Gateway](https://github.com/cordum-io/cordum/tree/main/core/controlplane/gateway): `core/controlplane/gateway`
- [Edge Event Ingest](https://github.com/cordum-io/cordum/blob/main/core/controlplane/gateway/handlers_edge_llm_ingest.go): `core/controlplane/gateway/handlers_edge_llm_ingest.go`
- [Edge Agent](https://github.com/cordum-io/cordum/blob/main/core/edge/agentd/app.go): `core/edge/agentd/app.go`
- [MCP Service](https://github.com/cordum-io/cordum/blob/main/core/mcp/server.go): `core/mcp/server.go`
- [Dashboard](https://github.com/cordum-io/cordum/blob/main/dashboard/src/App.tsx): `dashboard/src/App.tsx`

### Governance and Safety

- [Policy Evaluation](https://github.com/cordum-io/cordum/blob/main/core/governance/evaluator/evaluator.go): `core/governance/evaluator/evaluator.go`
- [Action Gates](https://github.com/cordum-io/cordum/blob/main/core/policy/actiongates/pipeline.go): `core/policy/actiongates/pipeline.go`
- [Safety Kernel](https://github.com/cordum-io/cordum/blob/main/core/controlplane/safetykernel/kernel.go): `core/controlplane/safetykernel/kernel.go`
- [Policy Bundles](https://github.com/cordum-io/cordum/blob/main/core/controlplane/gateway/policybundles/bundles.go): `core/controlplane/gateway/policybundles/bundles.go`

### Execution

- [Job Scheduler](https://github.com/cordum-io/cordum/blob/main/core/controlplane/scheduler/engine.go): `core/controlplane/scheduler/engine.go`
- [Workflow Engine](https://github.com/cordum-io/cordum/blob/main/core/workflow/engine.go): `core/workflow/engine.go`
- [Agent Worker](https://github.com/cordum-io/cordum/blob/main/sdk/runtime/worker.go): `sdk/runtime/worker.go`
- [Context Engine](https://github.com/cordum-io/cordum/blob/main/core/contextwindow/engine/service.go): `core/contextwindow/engine/service.go`
- [Job Store](https://github.com/cordum-io/cordum/blob/main/core/infra/store/job_store.go): `core/infra/store/job_store.go`

### Visibility and Operations

- [Audit Pipeline](https://github.com/cordum-io/cordum/blob/main/core/audit/consumer.go): `core/audit/consumer.go`
- [Edge Event Store](https://github.com/cordum-io/cordum/blob/main/core/edge/store.go): `core/edge/store.go`
- [Evaluation Extraction](https://github.com/cordum-io/cordum/blob/main/core/evals/extraction/pipeline.go): `core/evals/extraction/pipeline.go`
- [Client SDK](https://github.com/cordum-io/cordum/blob/main/sdk/client/client.go): `sdk/client/client.go`

### Other components

- **API Client**
- **LLM Proxy**

## Connections

- API Client → API Gateway: submits requests
- API Gateway → Policy Evaluation: evaluates policy
- API Gateway → Job Scheduler: submits jobs
- Job Scheduler → Safety Kernel: checks safety
- Job Scheduler → Job Store: persists jobs
- Job Scheduler → Agent Worker: dispatches work
- Workflow Engine → Job Scheduler: publishes job packets (evidence: `core/workflow/engine.go`)
- API Gateway → Workflow Engine: manages workflows
- LLM Proxy → Edge Event Ingest: sends LLM events (evidence: `core/controlplane/gateway/handlers_edge_llm_ingest.go`)
- Edge Event Ingest → Edge Event Store: appends events (evidence: `core/controlplane/gateway/handlers_edge_llm_ingest.go`)
- Edge Agent → API Gateway: reports edge activity
- MCP Service → API Gateway: uses gateway handlers
- API Gateway → Action Gates: applies action gates
- API Gateway → Policy Bundles: serves policy bundles
- API Gateway → Context Engine: provides context service
- Dashboard → API Gateway: requests status
- Client SDK → API Gateway: calls API
- API Gateway → Audit Pipeline: exports audit records
- Evaluation Extraction → Job Store: queries decisions (evidence: `core/evals/extraction/pipeline.go`)
- Edge Event Ingest → Safety Kernel: classifies interactions (evidence: `core/controlplane/gateway/handlers_edge_llm_ingest.go`)
