# bogdaniel/zenchron-engineering architecture

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

- Interactive diagram: https://gitdiagram.com/bogdaniel/zenchron-engineering
- Repository: https://github.com/bogdaniel/zenchron-engineering

## Overview

Zenchron Engineering is a local engineering control plane: an operator submits or plans GitHub issue work, the persistent runtime coordinates workers and governs changes through verification, provenance, policy, and authority, while the operator retains the merge decision. The README documents the workflow and major capabilities; source excerpts show deterministic analysis, policy compilation, evidence handling, authority evaluation, and reassessment. Several runtime subsystems are represented by their exact tree paths but were not excerpted, so the graph avoids asserting undocumented internal call chains.

Main entry points: [`runtime/controller.go`](https://github.com/bogdaniel/zenchron-engineering/blob/main/runtime/controller.go) (Engineering runtime), [`planning/compiler.go`](https://github.com/bogdaniel/zenchron-engineering/blob/main/planning/compiler.go) (Plan compilation), [`cmd/zenchron-engineering/operator.go`](https://github.com/bogdaniel/zenchron-engineering/blob/main/cmd/zenchron-engineering/operator.go) (CLI commands), [`runtime/supervisor.go`](https://github.com/bogdaniel/zenchron-engineering/blob/main/runtime/supervisor.go) (Runtime supervisor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Operator interface"]
  node_operator["CLI commands<br/>[operator.go]"]
  node_controller_cli["Controller commands<br/>[controller.go]"]
  node_api["Control API<br/>[api.go]"]
end

subgraph group_governance["Change governance"]
  node_planning["Plan compilation<br/>[compiler.go]"]
  node_plan_context["Assignment context<br/>[context.go]"]
  node_plan_graph["Plan graph<br/>[graph.go]"]
  node_plan_registry["Plan registry<br/>[registry.go]"]
  node_plan_resolver["Plan resolution<br/>[resolver.go]"]
  node_plan_validation["Plan validation<br/>[validate.go]"]
  node_analysis["Fact analysis<br/>[analysis.go]"]
  node_policy["Policy compiler<br/>[compiler.go]"]
  node_reassessment["Scope reassessment<br/>[reassessment.go]"]
  node_evidence["Evidence binding<br/>[evidence.go]"]
  node_authority["Authority decision<br/>[authority.go]"]
end

subgraph group_execution["Runtime execution"]
  node_runtime["Engineering runtime<br/>[controller.go]"]
  node_agents["Agent providers<br/>[agents.go]"]
  node_operations["Bounded operations<br/>[operations.go]"]
  node_git["Repository Git<br/>[repository_git.go]"]
end

subgraph group_control["Persistent control plane"]
  node_supervisor["Runtime supervisor<br/>[supervisor.go]"]
  node_reconciler["Run reconciler<br/>[reconciler.go]"]
  node_journal[("Run journal<br/>[journal.go]")]
  node_state[("SQLite state<br/>[sqlite_store.go]")]
end

subgraph group_integrations["External systems"]
  node_github["GitHub adapter<br/>[github.go]"]
  node_feedback["Review feedback<br/>[feedback.go]"]
end

node_operator_actor(("Operator"))
node_github_service["GitHub"]

node_operator_actor -->|"submits work"| node_operator
node_operator -->|"requests plan"| node_planning
node_planning -.->|"compiles assignments"| node_plan_context
node_planning -.->|"models dependencies"| node_plan_graph
node_planning -.->|"uses capabilities"| node_plan_registry
node_planning -.->|"resolves workers"| node_plan_resolver
node_planning -.->|"validates plan"| node_plan_validation
node_operator -->|"starts issue runs"| node_runtime
node_operator -->|"starts service"| node_supervisor
node_supervisor -->|"owns work"| node_runtime
node_runtime -->|"advances runs"| node_reconciler
node_reconciler -.->|"executes bounded work"| node_operations
node_runtime -->|"persists run events"| node_journal
node_runtime -.->|"stores durable state"| node_state
node_runtime -->|"gets issue context"| node_github
node_runtime -->|"invokes worker"| node_agents
node_runtime -->|"manages candidate"| node_git
node_runtime -.->|"derives facts"| node_analysis
node_runtime -.->|"compiles contract"| node_policy
node_runtime -->|"reassesses changes"| node_reassessment
node_reassessment -->|"recompiles contract"| node_policy
node_runtime -.->|"checks evidence"| node_evidence
node_runtime -.->|"requests authorization"| node_authority
node_github_service -->|"sends review comments"| node_feedback
node_feedback -->|"routes admitted feedback"| node_runtime
node_runtime -->|"publishes pull request"| node_github
node_github -->|"opens pull request"| node_github_service
node_operator_actor -->|"merges externally"| node_github_service
node_operator -.->|"controls service"| node_api
node_controller_cli -.->|"manages controller"| node_supervisor

click node_operator "https://github.com/bogdaniel/zenchron-engineering/blob/main/cmd/zenchron-engineering/operator.go"
click node_controller_cli "https://github.com/bogdaniel/zenchron-engineering/blob/main/cmd/zenchron-engineering/controller.go"
click node_api "https://github.com/bogdaniel/zenchron-engineering/blob/main/controlplane/api.go"
click node_planning "https://github.com/bogdaniel/zenchron-engineering/blob/main/planning/compiler.go"
click node_plan_context "https://github.com/bogdaniel/zenchron-engineering/blob/main/planning/context.go"
click node_plan_graph "https://github.com/bogdaniel/zenchron-engineering/blob/main/planning/graph.go"
click node_plan_registry "https://github.com/bogdaniel/zenchron-engineering/blob/main/planning/registry.go"
click node_plan_resolver "https://github.com/bogdaniel/zenchron-engineering/blob/main/planning/resolver.go"
click node_plan_validation "https://github.com/bogdaniel/zenchron-engineering/blob/main/planning/validate.go"
click node_analysis "https://github.com/bogdaniel/zenchron-engineering/blob/main/analysis/analysis.go"
click node_policy "https://github.com/bogdaniel/zenchron-engineering/blob/main/policy/compiler.go"
click node_reassessment "https://github.com/bogdaniel/zenchron-engineering/blob/main/reassessment/reassessment.go"
click node_evidence "https://github.com/bogdaniel/zenchron-engineering/blob/main/evidence/evidence.go"
click node_authority "https://github.com/bogdaniel/zenchron-engineering/blob/main/authority/authority.go"
click node_runtime "https://github.com/bogdaniel/zenchron-engineering/blob/main/runtime/controller.go"
click node_agents "https://github.com/bogdaniel/zenchron-engineering/blob/main/runtime/agents.go"
click node_operations "https://github.com/bogdaniel/zenchron-engineering/blob/main/runtime/operations.go"
click node_github "https://github.com/bogdaniel/zenchron-engineering/blob/main/runtime/github.go"
click node_git "https://github.com/bogdaniel/zenchron-engineering/blob/main/runtime/repository_git.go"
click node_feedback "https://github.com/bogdaniel/zenchron-engineering/blob/main/runtime/feedback.go"
click node_supervisor "https://github.com/bogdaniel/zenchron-engineering/blob/main/runtime/supervisor.go"
click node_reconciler "https://github.com/bogdaniel/zenchron-engineering/blob/main/runtime/reconciler.go"
click node_journal "https://github.com/bogdaniel/zenchron-engineering/blob/main/runtime/journal.go"
click node_state "https://github.com/bogdaniel/zenchron-engineering/blob/main/runtime/sqlite_store.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_operator,node_controller_cli,node_api toneBlue
class node_planning,node_plan_context,node_plan_graph,node_plan_registry,node_plan_resolver,node_plan_validation,node_analysis,node_policy,node_reassessment,node_evidence,node_authority toneAmber
class node_runtime,node_agents,node_operations,node_git toneMint
class node_supervisor,node_reconciler,node_journal,node_state toneRose
class node_github,node_feedback,node_operator_actor,node_github_service toneIndigo
```

## Components

### Operator interface

- [CLI commands](https://github.com/bogdaniel/zenchron-engineering/blob/main/cmd/zenchron-engineering/operator.go): `cmd/zenchron-engineering/operator.go`
- [Controller commands](https://github.com/bogdaniel/zenchron-engineering/blob/main/cmd/zenchron-engineering/controller.go): `cmd/zenchron-engineering/controller.go`
- [Control API](https://github.com/bogdaniel/zenchron-engineering/blob/main/controlplane/api.go): `controlplane/api.go`

### Change governance

- [Plan compilation](https://github.com/bogdaniel/zenchron-engineering/blob/main/planning/compiler.go): `planning/compiler.go`
- [Assignment context](https://github.com/bogdaniel/zenchron-engineering/blob/main/planning/context.go): `planning/context.go`
- [Plan graph](https://github.com/bogdaniel/zenchron-engineering/blob/main/planning/graph.go): `planning/graph.go`
- [Plan registry](https://github.com/bogdaniel/zenchron-engineering/blob/main/planning/registry.go): `planning/registry.go`
- [Plan resolution](https://github.com/bogdaniel/zenchron-engineering/blob/main/planning/resolver.go): `planning/resolver.go`
- [Plan validation](https://github.com/bogdaniel/zenchron-engineering/blob/main/planning/validate.go): `planning/validate.go`
- [Fact analysis](https://github.com/bogdaniel/zenchron-engineering/blob/main/analysis/analysis.go): `analysis/analysis.go`
- [Policy compiler](https://github.com/bogdaniel/zenchron-engineering/blob/main/policy/compiler.go): `policy/compiler.go`
- [Scope reassessment](https://github.com/bogdaniel/zenchron-engineering/blob/main/reassessment/reassessment.go): `reassessment/reassessment.go`
- [Evidence binding](https://github.com/bogdaniel/zenchron-engineering/blob/main/evidence/evidence.go): `evidence/evidence.go`
- [Authority decision](https://github.com/bogdaniel/zenchron-engineering/blob/main/authority/authority.go): `authority/authority.go`

### Runtime execution

- [Engineering runtime](https://github.com/bogdaniel/zenchron-engineering/blob/main/runtime/controller.go): `runtime/controller.go`
- [Agent providers](https://github.com/bogdaniel/zenchron-engineering/blob/main/runtime/agents.go): `runtime/agents.go`
- [Bounded operations](https://github.com/bogdaniel/zenchron-engineering/blob/main/runtime/operations.go): `runtime/operations.go`
- [Repository Git](https://github.com/bogdaniel/zenchron-engineering/blob/main/runtime/repository_git.go): `runtime/repository_git.go`

### Persistent control plane

- [Runtime supervisor](https://github.com/bogdaniel/zenchron-engineering/blob/main/runtime/supervisor.go): `runtime/supervisor.go`
- [Run reconciler](https://github.com/bogdaniel/zenchron-engineering/blob/main/runtime/reconciler.go): `runtime/reconciler.go`
- [Run journal](https://github.com/bogdaniel/zenchron-engineering/blob/main/runtime/journal.go): `runtime/journal.go`
- [SQLite state](https://github.com/bogdaniel/zenchron-engineering/blob/main/runtime/sqlite_store.go): `runtime/sqlite_store.go`

### External systems

- [GitHub adapter](https://github.com/bogdaniel/zenchron-engineering/blob/main/runtime/github.go): `runtime/github.go`
- [Review feedback](https://github.com/bogdaniel/zenchron-engineering/blob/main/runtime/feedback.go): `runtime/feedback.go`

### Other components

- **Operator**
- **GitHub**

## Connections

- Operator → CLI commands: submits work (evidence: `README.md`)
- CLI commands → Plan compilation: requests plan (evidence: `README.md`)
- Plan compilation → Assignment context: compiles assignments
- Plan compilation → Plan graph: models dependencies
- Plan compilation → Plan registry: uses capabilities
- Plan compilation → Plan resolution: resolves workers
- Plan compilation → Plan validation: validates plan
- CLI commands → Engineering runtime: starts issue runs (evidence: `README.md`)
- CLI commands → Runtime supervisor: starts service (evidence: `README.md`)
- Runtime supervisor → Engineering runtime: owns work (evidence: `README.md`)
- Engineering runtime → Run reconciler: advances runs (evidence: `runtime/controller.go`)
- Run reconciler → Bounded operations: executes bounded work
- Engineering runtime → Run journal: persists run events (evidence: `README.md`)
- Engineering runtime → SQLite state: stores durable state
- Engineering runtime → GitHub adapter: gets issue context (evidence: `README.md`)
- Engineering runtime → Agent providers: invokes worker (evidence: `README.md`)
- Engineering runtime → Repository Git: manages candidate (evidence: `README.md`)
- Engineering runtime → Fact analysis: derives facts
- Engineering runtime → Policy compiler: compiles contract
- Engineering runtime → Scope reassessment: reassesses changes (evidence: `README.md`)
- Scope reassessment → Policy compiler: recompiles contract (evidence: `reassessment/reassessment.go`)
- Engineering runtime → Evidence binding: checks evidence
- Engineering runtime → Authority decision: requests authorization
- GitHub → Review feedback: sends review comments (evidence: `README.md`)
- Review feedback → Engineering runtime: routes admitted feedback (evidence: `README.md`)
- Engineering runtime → GitHub adapter: publishes pull request (evidence: `README.md`)
- GitHub adapter → GitHub: opens pull request (evidence: `README.md`)
- Operator → GitHub: merges externally (evidence: `README.md`)
- CLI commands → Control API: controls service
- Controller commands → Runtime supervisor: manages controller
