# lucheeseng827/covenant architecture

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

- Interactive diagram: https://gitdiagram.com/lucheeseng827/covenant
- Repository: https://github.com/lucheeseng827/covenant

## Overview

Covenant compiles YAML data contracts once and enforces them at file, stream, and in-process Arrow boundaries. Its merge-time workflow classifies contract changes and checks declared consumer impact; consumer manifests can also scope validation and be checked for staleness. Sampled code supports the CLI, row/Arrow engines, inference, and frontend boot behavior; serve endpoints and some CLI wiring are represented only at the documented subsystem level.

Main entry points: [`src/cli.rs`](https://github.com/lucheeseng827/covenant/blob/main/src/cli.rs) (Covenant CLI), [`src/serve.rs`](https://github.com/lucheeseng827/covenant/blob/main/src/serve.rs) (HTTP API), [`src/sources.rs`](https://github.com/lucheeseng827/covenant/blob/main/src/sources.rs) (File checks), [`src/spec.rs`](https://github.com/lucheeseng827/covenant/blob/main/src/spec.rs) (Contract parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_contract["Contract lifecycle"]
  node_spec["Contract parser<br/>[spec.rs]"]
  node_compiler["Contract compiler<br/>[compile.rs]"]
  node_infer["Sample inference<br/>[infer.rs]"]
end

subgraph group_enforcement["Data enforcement"]
  node_sources["File checks<br/>[sources.rs]"]
  node_row["Record engine<br/>[row.rs]"]
  node_arrow["Arrow engine<br/>[arrow.rs]"]
  node_gate["Stream gate<br/>[gate.rs]"]
  node_report["Check reports<br/>[report.rs]"]
end

subgraph group_change["Change impact"]
  node_diff["Contract diff<br/>[diff.rs]"]
  node_consumers["Consumer manifests<br/>[consumers.rs]"]
end

subgraph group_serve["API and console"]
  node_serve["HTTP API<br/>[serve.rs]"]
  node_console["Web console<br/>[App.tsx]"]
  node_api_client["Console API client<br/>[api.ts]"]
end

subgraph group_runtime["Runtime core"]
  node_cli["Covenant CLI<br/>[cli.rs]"]
  node_engine["Engine coordination<br/>[mod.rs]"]
  node_binary["Binary entry<br/>[main.rs]"]
end

node_author(("Contract author"))
node_data(("Data files or stream"))

node_author -->|"authors YAML"| node_spec
node_data -->|"samples records"| node_infer
node_data -->|"provides files"| node_sources
node_binary -->|"dispatches"| node_cli
node_cli -->|"loads contracts"| node_spec
node_cli -->|"runs inference"| node_infer
node_infer -->|"drafts contract"| node_spec
node_cli -->|"compiles contract"| node_compiler
node_spec -->|"provides spec"| node_compiler
node_cli -->|"checks files"| node_sources
node_sources -->|"validates records"| node_engine
node_engine -->|"coordinates row checks"| node_row
node_engine -->|"coordinates batch checks"| node_arrow
node_sources -->|"produces report"| node_report
node_cli -->|"runs stream gate"| node_gate
node_gate -->|"validates records"| node_row
node_gate -->|"emits violations"| node_report
node_cli -->|"classifies changes"| node_diff
node_cli -->|"checks manifests"| node_consumers
node_diff -->|"matches impact"| node_consumers
node_cli -->|"starts API"| node_serve
node_console -->|"uses client"| node_api_client
node_api_client -->|"requests endpoints"| node_serve
node_serve -->|"uses compiled contract"| node_compiler
node_serve -->|"runs checks"| node_sources
node_serve -->|"runs diff"| node_diff
node_serve -->|"verifies consumers"| node_consumers

click node_cli "https://github.com/lucheeseng827/covenant/blob/main/src/cli.rs"
click node_spec "https://github.com/lucheeseng827/covenant/blob/main/src/spec.rs"
click node_compiler "https://github.com/lucheeseng827/covenant/blob/main/src/compile.rs"
click node_infer "https://github.com/lucheeseng827/covenant/blob/main/src/infer.rs"
click node_sources "https://github.com/lucheeseng827/covenant/blob/main/src/sources.rs"
click node_row "https://github.com/lucheeseng827/covenant/blob/main/src/engine/row.rs"
click node_arrow "https://github.com/lucheeseng827/covenant/blob/main/src/engine/arrow.rs"
click node_gate "https://github.com/lucheeseng827/covenant/blob/main/src/gate.rs"
click node_report "https://github.com/lucheeseng827/covenant/blob/main/src/report.rs"
click node_diff "https://github.com/lucheeseng827/covenant/blob/main/src/diff.rs"
click node_consumers "https://github.com/lucheeseng827/covenant/blob/main/src/consumers.rs"
click node_serve "https://github.com/lucheeseng827/covenant/blob/main/src/serve.rs"
click node_console "https://github.com/lucheeseng827/covenant/blob/main/frontend/src/App.tsx"
click node_engine "https://github.com/lucheeseng827/covenant/blob/main/src/engine/mod.rs"
click node_binary "https://github.com/lucheeseng827/covenant/blob/main/src/main.rs"
click node_api_client "https://github.com/lucheeseng827/covenant/blob/main/frontend/src/api.ts"

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_spec,node_compiler,node_infer toneBlue
class node_sources,node_row,node_arrow,node_gate,node_report toneAmber
class node_diff,node_consumers toneMint
class node_serve,node_console,node_api_client toneRose
class node_cli,node_engine,node_binary,node_author,node_data toneIndigo
```

## Components

### Contract lifecycle

- [Contract parser](https://github.com/lucheeseng827/covenant/blob/main/src/spec.rs): `src/spec.rs`
- [Contract compiler](https://github.com/lucheeseng827/covenant/blob/main/src/compile.rs): `src/compile.rs`
- [Sample inference](https://github.com/lucheeseng827/covenant/blob/main/src/infer.rs): `src/infer.rs`

### Data enforcement

- [File checks](https://github.com/lucheeseng827/covenant/blob/main/src/sources.rs): `src/sources.rs`
- [Record engine](https://github.com/lucheeseng827/covenant/blob/main/src/engine/row.rs): `src/engine/row.rs`
- [Arrow engine](https://github.com/lucheeseng827/covenant/blob/main/src/engine/arrow.rs): `src/engine/arrow.rs`
- [Stream gate](https://github.com/lucheeseng827/covenant/blob/main/src/gate.rs): `src/gate.rs`
- [Check reports](https://github.com/lucheeseng827/covenant/blob/main/src/report.rs): `src/report.rs`

### Change impact

- [Contract diff](https://github.com/lucheeseng827/covenant/blob/main/src/diff.rs): `src/diff.rs`
- [Consumer manifests](https://github.com/lucheeseng827/covenant/blob/main/src/consumers.rs): `src/consumers.rs`

### API and console

- [HTTP API](https://github.com/lucheeseng827/covenant/blob/main/src/serve.rs): `src/serve.rs`
- [Web console](https://github.com/lucheeseng827/covenant/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Console API client](https://github.com/lucheeseng827/covenant/blob/main/frontend/src/api.ts): `frontend/src/api.ts`

### Runtime core

- [Covenant CLI](https://github.com/lucheeseng827/covenant/blob/main/src/cli.rs): `src/cli.rs`
- [Engine coordination](https://github.com/lucheeseng827/covenant/blob/main/src/engine/mod.rs): `src/engine/mod.rs`
- [Binary entry](https://github.com/lucheeseng827/covenant/blob/main/src/main.rs): `src/main.rs`

### Other components

- **Contract author**
- **Data files or stream**

## Connections

- Contract author → Contract parser: authors YAML
- Data files or stream → Sample inference: samples records
- Data files or stream → File checks: provides files
- Binary entry → Covenant CLI: dispatches
- Covenant CLI → Contract parser: loads contracts
- Covenant CLI → Sample inference: runs inference
- Sample inference → Contract parser: drafts contract
- Covenant CLI → Contract compiler: compiles contract
- Contract parser → Contract compiler: provides spec
- Covenant CLI → File checks: checks files
- File checks → Engine coordination: validates records
- Engine coordination → Record engine: coordinates row checks
- Engine coordination → Arrow engine: coordinates batch checks
- File checks → Check reports: produces report
- Covenant CLI → Stream gate: runs stream gate
- Stream gate → Record engine: validates records
- Stream gate → Check reports: emits violations
- Covenant CLI → Contract diff: classifies changes
- Covenant CLI → Consumer manifests: checks manifests
- Contract diff → Consumer manifests: matches impact
- Covenant CLI → HTTP API: starts API
- Web console → Console API client: uses client
- Console API client → HTTP API: requests endpoints
- HTTP API → Contract compiler: uses compiled contract
- HTTP API → File checks: runs checks
- HTTP API → Contract diff: runs diff
- HTTP API → Consumer manifests: verifies consumers