# noobru/codex-infra architecture

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

- Interactive diagram: https://gitdiagram.com/noobru/codex-infra
- Repository: https://github.com/noobru/codex-infra

## Overview

CodexInfra turns project context and an engineering objective into bounded, validated work, then records evidence and results. Its dashboard is a read-only query layer; separate branches cover executable learning, efficiency/history, and security. The README documents these capabilities, while the source excerpts and index establish only some internal calls, so unsampled subsystem links are omitted rather than inferred.

Main entry points: [`src/engine.ts`](https://github.com/noobru/codex-infra/blob/codex/distribution/src/engine.ts) (Execution engine), [`src/autonomous-learning.ts`](https://github.com/noobru/codex-infra/blob/codex/distribution/src/autonomous-learning.ts) (Learning coordinator), [`src/supervisor.ts`](https://github.com/noobru/codex-infra/blob/codex/distribution/src/supervisor.ts) (Job supervisor), [`src/queue.ts`](https://github.com/noobru/codex-infra/blob/codex/distribution/src/queue.ts) (Shared queue)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_coordination["Work coordination"]
  node_engine["Execution engine<br/>[engine.ts]"]
  node_task_contract["Task contracts<br/>[task-contract.ts]"]
  node_supervisor["Job supervisor<br/>[supervisor.ts]"]
  node_queue["Shared queue<br/>[queue.ts]"]
  node_worker["Codex worker<br/>[codex-worker.ts]"]
  node_workflow["Workflow runner<br/>[workflow.ts]"]
  node_state[("Execution state<br/>[state.ts]")]
  node_routing["Model routing<br/>[routing.ts]"]
  node_evidence["Evidence sanitizer<br/>[evidence.ts]"]
  node_utilities["Shared file utilities"]
end

subgraph group_context["Project context"]
  node_registry["Project registry<br/>[registry.ts]"]
  node_context_pack["Context selection<br/>[context-pack.ts]"]
  node_knowledge_learning["Knowledge learning"]
end

subgraph group_learning["Executable learning"]
  node_autonomous_learning["Learning coordinator"]
  node_learning_store[("Learning store<br/>[knowledge-store.ts]")]
  node_learning_runtime["Capability runtime"]
  node_evaluation["Evaluation<br/>[evaluation.ts]"]
  node_learning_builder["Capability builder"]
  node_learning_sandbox["Isolated testing"]
end

subgraph group_insight["Observation and history"]
  node_observability["Observation service<br/>[observability.ts]"]
  node_efficiency["Efficiency history"]
  node_security_reports["Security reports"]
end

subgraph group_interfaces["User interfaces"]
  node_dashboard["Dashboard UI<br/>[Home.tsx]"]
  node_ui_api["Dashboard API client<br/>[api.ts]"]
  node_ui_components["Dashboard panels<br/>[components.tsx]"]
end

node_owner(("Project owner"))

node_owner -->|"submits objective"| node_engine
node_engine -->|"loads project context"| node_registry
node_engine -->|"builds contract"| node_task_contract
node_engine -->|"augments context"| node_knowledge_learning
node_engine -->|"builds context pack"| node_context_pack
node_engine -->|"dispatches job"| node_supervisor
node_engine -.->|"persists execution"| node_state
node_supervisor -->|"uses queue"| node_queue
node_supervisor -.->|"starts work"| node_worker
node_queue -->|"runs workflows"| node_workflow
node_queue -->|"runs learning"| node_autonomous_learning
node_worker -->|"selects model"| node_routing
node_worker -->|"sanitizes results"| node_evidence
node_autonomous_learning -->|"reads and writes"| node_learning_store
node_autonomous_learning -->|"builds capabilities"| node_learning_builder
node_autonomous_learning -->|"tests capabilities"| node_learning_sandbox
node_autonomous_learning -->|"coordinates activation"| node_learning_runtime
node_knowledge_learning -->|"uses store"| node_learning_store
node_knowledge_learning -->|"uses evaluations"| node_evaluation
node_dashboard -->|"requests observations"| node_ui_api
node_dashboard -->|"renders panels"| node_ui_components
node_ui_api -->|"queries views"| node_observability
node_observability -->|"reads state"| node_state
node_efficiency -->|"reads history data"| node_state
node_security_reports -->|"uses project registry"| node_registry

click node_engine "https://github.com/noobru/codex-infra/blob/codex/distribution/src/engine.ts"
click node_task_contract "https://github.com/noobru/codex-infra/blob/codex/distribution/src/task-contract.ts"
click node_supervisor "https://github.com/noobru/codex-infra/blob/codex/distribution/src/supervisor.ts"
click node_queue "https://github.com/noobru/codex-infra/blob/codex/distribution/src/queue.ts"
click node_worker "https://github.com/noobru/codex-infra/blob/codex/distribution/src/codex-worker.ts"
click node_workflow "https://github.com/noobru/codex-infra/blob/codex/distribution/src/workflow.ts"
click node_state "https://github.com/noobru/codex-infra/blob/codex/distribution/src/state.ts"
click node_registry "https://github.com/noobru/codex-infra/blob/codex/distribution/src/registry.ts"
click node_context_pack "https://github.com/noobru/codex-infra/blob/codex/distribution/src/context-pack.ts"
click node_knowledge_learning "https://github.com/noobru/codex-infra/blob/codex/distribution/src/knowledge-learning.ts"
click node_routing "https://github.com/noobru/codex-infra/blob/codex/distribution/src/routing.ts"
click node_evidence "https://github.com/noobru/codex-infra/blob/codex/distribution/src/evidence.ts"
click node_autonomous_learning "https://github.com/noobru/codex-infra/blob/codex/distribution/src/autonomous-learning.ts"
click node_learning_store "https://github.com/noobru/codex-infra/blob/codex/distribution/src/knowledge-store.ts"
click node_learning_runtime "https://github.com/noobru/codex-infra/blob/codex/distribution/src/learning-runtime.ts"
click node_evaluation "https://github.com/noobru/codex-infra/blob/codex/distribution/src/evaluation.ts"
click node_learning_builder "https://github.com/noobru/codex-infra/blob/codex/distribution/src/learning-builder.ts"
click node_learning_sandbox "https://github.com/noobru/codex-infra/blob/codex/distribution/src/learning-sandbox.ts"
click node_observability "https://github.com/noobru/codex-infra/blob/codex/distribution/src/observability.ts"
click node_efficiency "https://github.com/noobru/codex-infra/blob/codex/distribution/src/efficiency-history.ts"
click node_security_reports "https://github.com/noobru/codex-infra/blob/codex/distribution/src/security-report-service.ts"
click node_dashboard "https://github.com/noobru/codex-infra/blob/codex/distribution/ui/src/Home.tsx"
click node_ui_api "https://github.com/noobru/codex-infra/blob/codex/distribution/ui/src/api.ts"
click node_ui_components "https://github.com/noobru/codex-infra/blob/codex/distribution/ui/src/components.tsx"
click node_utilities "https://github.com/noobru/codex-infra/blob/codex/distribution/src/legacy/command-os-utils.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_engine,node_task_contract,node_supervisor,node_queue,node_worker,node_workflow,node_state,node_routing,node_evidence,node_utilities toneBlue
class node_registry,node_context_pack,node_knowledge_learning toneAmber
class node_autonomous_learning,node_learning_store,node_learning_runtime,node_evaluation,node_learning_builder,node_learning_sandbox toneMint
class node_observability,node_efficiency,node_security_reports toneRose
class node_dashboard,node_ui_api,node_ui_components,node_owner toneIndigo
```

## Components

### Work coordination

- [Execution engine](https://github.com/noobru/codex-infra/blob/codex/distribution/src/engine.ts): `src/engine.ts`
- [Task contracts](https://github.com/noobru/codex-infra/blob/codex/distribution/src/task-contract.ts): `src/task-contract.ts`
- [Job supervisor](https://github.com/noobru/codex-infra/blob/codex/distribution/src/supervisor.ts): `src/supervisor.ts`
- [Shared queue](https://github.com/noobru/codex-infra/blob/codex/distribution/src/queue.ts): `src/queue.ts`
- [Codex worker](https://github.com/noobru/codex-infra/blob/codex/distribution/src/codex-worker.ts): `src/codex-worker.ts`
- [Workflow runner](https://github.com/noobru/codex-infra/blob/codex/distribution/src/workflow.ts): `src/workflow.ts`
- [Execution state](https://github.com/noobru/codex-infra/blob/codex/distribution/src/state.ts): `src/state.ts`
- [Model routing](https://github.com/noobru/codex-infra/blob/codex/distribution/src/routing.ts): `src/routing.ts`
- [Evidence sanitizer](https://github.com/noobru/codex-infra/blob/codex/distribution/src/evidence.ts): `src/evidence.ts`
- [Shared file utilities](https://github.com/noobru/codex-infra/blob/codex/distribution/src/legacy/command-os-utils.js): `src/legacy/command-os-utils.js`

### Project context

- [Project registry](https://github.com/noobru/codex-infra/blob/codex/distribution/src/registry.ts): `src/registry.ts`
- [Context selection](https://github.com/noobru/codex-infra/blob/codex/distribution/src/context-pack.ts): `src/context-pack.ts`
- [Knowledge learning](https://github.com/noobru/codex-infra/blob/codex/distribution/src/knowledge-learning.ts): `src/knowledge-learning.ts`

### Executable learning

- [Learning coordinator](https://github.com/noobru/codex-infra/blob/codex/distribution/src/autonomous-learning.ts): `src/autonomous-learning.ts`
- [Learning store](https://github.com/noobru/codex-infra/blob/codex/distribution/src/knowledge-store.ts): `src/knowledge-store.ts`
- [Capability runtime](https://github.com/noobru/codex-infra/blob/codex/distribution/src/learning-runtime.ts): `src/learning-runtime.ts`
- [Evaluation](https://github.com/noobru/codex-infra/blob/codex/distribution/src/evaluation.ts): `src/evaluation.ts`
- [Capability builder](https://github.com/noobru/codex-infra/blob/codex/distribution/src/learning-builder.ts): `src/learning-builder.ts`
- [Isolated testing](https://github.com/noobru/codex-infra/blob/codex/distribution/src/learning-sandbox.ts): `src/learning-sandbox.ts`

### Observation and history

- [Observation service](https://github.com/noobru/codex-infra/blob/codex/distribution/src/observability.ts): `src/observability.ts`
- [Efficiency history](https://github.com/noobru/codex-infra/blob/codex/distribution/src/efficiency-history.ts): `src/efficiency-history.ts`
- [Security reports](https://github.com/noobru/codex-infra/blob/codex/distribution/src/security-report-service.ts): `src/security-report-service.ts`

### User interfaces

- [Dashboard UI](https://github.com/noobru/codex-infra/blob/codex/distribution/ui/src/Home.tsx): `ui/src/Home.tsx`
- [Dashboard API client](https://github.com/noobru/codex-infra/blob/codex/distribution/ui/src/api.ts): `ui/src/api.ts`
- [Dashboard panels](https://github.com/noobru/codex-infra/blob/codex/distribution/ui/src/components.tsx): `ui/src/components.tsx`

### Other components

- **Project owner**

## Connections

- Project owner → Execution engine: submits objective (evidence: `README.md`)
- Execution engine → Project registry: loads project context (evidence: `src/engine.ts`)
- Execution engine → Task contracts: builds contract (evidence: `src/engine.ts`)
- Execution engine → Knowledge learning: augments context (evidence: `src/engine.ts`)
- Execution engine → Context selection: builds context pack (evidence: `src/engine.ts`)
- Execution engine → Job supervisor: dispatches job (evidence: `src/engine.ts`)
- Execution engine → Execution state: persists execution (evidence: `src/engine.ts`)
- Job supervisor → Shared queue: uses queue (evidence: `src/supervisor.ts`)
- Job supervisor → Codex worker: starts work
- Shared queue → Workflow runner: runs workflows (evidence: `src/queue-worker.ts`)
- Shared queue → Learning coordinator: runs learning (evidence: `src/queue-worker.ts`)
- Codex worker → Model routing: selects model (evidence: `src/codex-worker.ts`)
- Codex worker → Evidence sanitizer: sanitizes results (evidence: `src/codex-worker.ts`)
- Learning coordinator → Learning store: reads and writes (evidence: `src/autonomous-learning.ts`)
- Learning coordinator → Capability builder: builds capabilities (evidence: `src/autonomous-learning.ts`)
- Learning coordinator → Isolated testing: tests capabilities (evidence: `src/autonomous-learning.ts`)
- Learning coordinator → Capability runtime: coordinates activation (evidence: `src/autonomous-learning.ts`)
- Knowledge learning → Learning store: uses store (evidence: `src/knowledge-learning.ts`)
- Knowledge learning → Evaluation: uses evaluations (evidence: `src/knowledge-learning.ts`)
- Dashboard UI → Dashboard API client: requests observations (evidence: `ui/src/Home.tsx`)
- Dashboard UI → Dashboard panels: renders panels (evidence: `ui/src/Home.tsx`)
- Dashboard API client → Observation service: queries views (evidence: `ui/src/api.ts`)
- Observation service → Execution state: reads state (evidence: `src/observability.ts`)
- Efficiency history → Execution state: reads history data (evidence: `src/efficiency-history.ts`)
- Security reports → Project registry: uses project registry (evidence: `src/security-report-service.ts`)