# cairndev-sh/cairn architecture

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

- Interactive diagram: https://gitdiagram.com/cairndev-sh/cairn
- Repository: https://github.com/cairndev-sh/cairn

## Overview

Cairn is a self-hosted control plane for running AI/ML work as governed pipelines: users declare and launch flows or multi-step pipelines, and Cairn applies admission, budget, policy, and approval controls before execution, then records run state and audit evidence. The map emphasizes that workflow and its major documented capabilities, including dataflow engines, evaluation, and retrieval-augmented generation. Several links are documented in the README or SOURCE INDEX; unsampled implementation details are not treated as inspected evidence.

Main entry points: [`src/cairn/core/dispatch/leg_executor.py`](https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/dispatch/leg_executor.py) (Leg executor), [`src/cairn/core/dispatch/pipeline_launch.py`](https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/dispatch/pipeline_launch.py) (Pipeline launch), [`src/cairn/core/engine/pipeline.py`](https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/engine/pipeline.py) (Pipeline definitions), [`src/cairn/core/dispatch/pipeline_bridge.py`](https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/dispatch/pipeline_bridge.py) (Pipeline coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_author["Pipeline authoring"]
  node_cli["CLI commands<br/>[pipeline.py]"]
  node_pipeline_def["Pipeline definitions<br/>[pipeline.py]"]
  node_presets["Input presets"]
  node_packs["Domain pack registry<br/>[registry.py]"]
end

subgraph group_control["Governance and control"]
  node_launch["Pipeline launch<br/>[pipeline_launch.py]"]
  node_policy["Policy and approvals<br/>[pipeline_gates.py]"]
  node_budget["Budget controls"]
  node_api["HTTP pipeline routes<br/>[pipelines.py]"]
end

subgraph group_execution["Execution"]
  node_bridge["Pipeline coordinator<br/>[pipeline_bridge.py]"]
  node_leg["Leg executor<br/>[leg_executor.py]"]
  node_flow_defs["Flow definitions<br/>[defs.py]"]
  node_engine_select["Engine selection<br/>[engine_registry.py]"]
  node_engine_adapter["Dataflow engine adapters<br/>[engines.py]"]
  node_train_operator["Local training operator<br/>[lora.py]"]
end

subgraph group_state["State and evidence"]
  node_pipeline_store[("Pipeline records<br/>[pipeline_store.py]")]
  node_workspace[("Workspace isolation<br/>[workspace.py]")]
  node_audit[("Audit and run records<br/>[audit.py]")]
end

subgraph group_capabilities["AI capabilities"]
  node_evaluation["Model evaluation<br/>[scoring.py]"]
  node_rag["Retrieval augmented generation<br/>[query.py]"]
end

node_user(("User"))

node_user -->|"invokes"| node_cli
node_cli -->|"launches"| node_launch
node_api -->|"launches"| node_launch
node_launch -->|"resolves"| node_pipeline_def
node_launch -->|"starts"| node_bridge
node_launch -->|"checks gates"| node_policy
node_launch -.->|"loads inputs"| node_presets
node_pipeline_def -->|"uses pack"| node_packs
node_bridge -->|"submits steps"| node_leg
node_bridge -->|"persists state"| node_pipeline_store
node_leg -->|"resolves flow"| node_flow_defs
node_leg -->|"selects engine"| node_engine_select
node_engine_select -->|"loads adapter"| node_engine_adapter
node_leg -->|"reserves cost"| node_budget
node_leg -->|"enforces policy"| node_policy
node_leg -.->|"runs operator"| node_train_operator
node_pipeline_store -.->|"records outcomes"| node_audit
node_bridge -->|"scopes work"| node_workspace
node_pipeline_def -.->|"can define evaluation"| node_evaluation
node_pipeline_def -.->|"can use retrieval"| node_rag

click node_cli "https://github.com/cairndev-sh/cairn/blob/main/src/cairn/cli/commands/pipeline.py"
click node_pipeline_def "https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/engine/pipeline.py"
click node_presets "https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/pipeline_presets.py"
click node_launch "https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/dispatch/pipeline_launch.py"
click node_policy "https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/policy/pipeline_gates.py"
click node_budget "https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/budget_reservations.py"
click node_bridge "https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/dispatch/pipeline_bridge.py"
click node_leg "https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/dispatch/leg_executor.py"
click node_flow_defs "https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/dataflow/defs.py"
click node_engine_select "https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/dataflow/engine_registry.py"
click node_engine_adapter "https://github.com/cairndev-sh/cairn/blob/main/packages/cairn-operator-dataflow/src/operator_dataflow/engines.py"
click node_train_operator "https://github.com/cairndev-sh/cairn/blob/main/packages/cairn-operator-train-local/src/operator_train_local/operators/lora.py"
click node_pipeline_store "https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/storage/pipeline_store.py"
click node_workspace "https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/workspace.py"
click node_audit "https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/obs/audit.py"
click node_evaluation "https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/eval/scoring.py"
click node_rag "https://github.com/cairndev-sh/cairn/blob/main/src/cairn/services/rag/query.py"
click node_packs "https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/pack/registry.py"
click node_api "https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/triggers/routers/pipelines.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_cli,node_pipeline_def,node_presets,node_packs,node_user toneBlue
class node_launch,node_policy,node_budget,node_api toneAmber
class node_bridge,node_leg,node_flow_defs,node_engine_select,node_engine_adapter,node_train_operator toneMint
class node_pipeline_store,node_workspace,node_audit toneRose
class node_evaluation,node_rag toneIndigo
```

## Components

### Pipeline authoring

- [CLI commands](https://github.com/cairndev-sh/cairn/blob/main/src/cairn/cli/commands/pipeline.py): `src/cairn/cli/commands/pipeline.py`
- [Pipeline definitions](https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/engine/pipeline.py): `src/cairn/core/engine/pipeline.py`
- [Input presets](https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/pipeline_presets.py): `src/cairn/core/pipeline_presets.py`
- [Domain pack registry](https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/pack/registry.py): `src/cairn/core/pack/registry.py`

### Governance and control

- [Pipeline launch](https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/dispatch/pipeline_launch.py): `src/cairn/core/dispatch/pipeline_launch.py`
- [Policy and approvals](https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/policy/pipeline_gates.py): `src/cairn/core/policy/pipeline_gates.py`
- [Budget controls](https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/budget_reservations.py): `src/cairn/core/budget_reservations.py`
- [HTTP pipeline routes](https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/triggers/routers/pipelines.py): `src/cairn/core/triggers/routers/pipelines.py`

### Execution

- [Pipeline coordinator](https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/dispatch/pipeline_bridge.py): `src/cairn/core/dispatch/pipeline_bridge.py`
- [Leg executor](https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/dispatch/leg_executor.py): `src/cairn/core/dispatch/leg_executor.py`
- [Flow definitions](https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/dataflow/defs.py): `src/cairn/core/dataflow/defs.py`
- [Engine selection](https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/dataflow/engine_registry.py): `src/cairn/core/dataflow/engine_registry.py`
- [Dataflow engine adapters](https://github.com/cairndev-sh/cairn/blob/main/packages/cairn-operator-dataflow/src/operator_dataflow/engines.py): `packages/cairn-operator-dataflow/src/operator_dataflow/engines.py`
- [Local training operator](https://github.com/cairndev-sh/cairn/blob/main/packages/cairn-operator-train-local/src/operator_train_local/operators/lora.py): `packages/cairn-operator-train-local/src/operator_train_local/operators/lora.py`

### State and evidence

- [Pipeline records](https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/storage/pipeline_store.py): `src/cairn/core/storage/pipeline_store.py`
- [Workspace isolation](https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/workspace.py): `src/cairn/core/workspace.py`
- [Audit and run records](https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/obs/audit.py): `src/cairn/core/obs/audit.py`

### AI capabilities

- [Model evaluation](https://github.com/cairndev-sh/cairn/blob/main/src/cairn/core/eval/scoring.py): `src/cairn/core/eval/scoring.py`
- [Retrieval augmented generation](https://github.com/cairndev-sh/cairn/blob/main/src/cairn/services/rag/query.py): `src/cairn/services/rag/query.py`

### Other components

- **User**

## Connections

- User → CLI commands: invokes
- CLI commands → Pipeline launch: launches (evidence: `src/cairn/core/dispatch/pipeline_launch.py`)
- HTTP pipeline routes → Pipeline launch: launches (evidence: `src/cairn/core/dispatch/pipeline_launch.py`)
- Pipeline launch → Pipeline definitions: resolves (evidence: `src/cairn/core/dispatch/pipeline_launch.py`)
- Pipeline launch → Pipeline coordinator: starts (evidence: `src/cairn/core/dispatch/pipeline_launch.py`)
- Pipeline launch → Policy and approvals: checks gates (evidence: `src/cairn/core/dispatch/pipeline_launch.py`)
- Pipeline launch → Input presets: loads inputs (evidence: `src/cairn/core/dispatch/pipeline_launch.py`)
- Pipeline definitions → Domain pack registry: uses pack (evidence: `src/cairn/core/engine/pipeline.py`)
- Pipeline coordinator → Leg executor: submits steps (evidence: `src/cairn/core/dispatch/pipeline_bridge.py`)
- Pipeline coordinator → Pipeline records: persists state (evidence: `src/cairn/core/dispatch/pipeline_bridge.py`)
- Leg executor → Flow definitions: resolves flow (evidence: `src/cairn/core/dispatch/leg_executor.py`)
- Leg executor → Engine selection: selects engine (evidence: `src/cairn/core/dispatch/leg_executor.py`)
- Engine selection → Dataflow engine adapters: loads adapter (evidence: `src/cairn/core/dataflow/engine_registry.py`)
- Leg executor → Budget controls: reserves cost (evidence: `src/cairn/core/dispatch/leg_executor.py`)
- Leg executor → Policy and approvals: enforces policy
- Leg executor → Local training operator: runs operator
- Pipeline records → Audit and run records: records outcomes
- Pipeline coordinator → Workspace isolation: scopes work (evidence: `src/cairn/core/dispatch/pipeline_bridge.py`)
- Pipeline definitions → Model evaluation: can define evaluation
- Pipeline definitions → Retrieval augmented generation: can use retrieval