# darknorthaco/ddframework architecture

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

- Interactive diagram: https://gitdiagram.com/darknorthaco/ddframework
- Repository: https://github.com/darknorthaco/ddframework

## Overview

DDFramework is a transport-agnostic engine for governed rituals, append-only records, read-only advisory analysis, and simulation. The principal workflow is operator invocation of a ritual or audit: the executor checks and records ledger state; GHOST reads validated state, evaluates rules, and writes a separate advisory stream. The Constitutional Agent Shell is a documented application layer that consumes the kernel. Simulation provides read-only what-if analyses. Edges reflect excerpts, SOURCE INDEX references, or README statements; some executor and application links remain unverified because their call sites were not shown.

Main entry points: [`ddf-core/ddf_py/ddf/_sim_cli.py`](https://github.com/darknorthaco/ddframework/blob/main/ddf-core/ddf_py/ddf/_sim_cli.py) (Simulation CLI), [`ghost-observer/ghost/advisor.py`](https://github.com/darknorthaco/ddframework/blob/main/ghost-observer/ghost/advisor.py) (Advisor orchestration), [`ghost-observer/ghost/rules/__init__.py`](https://github.com/darknorthaco/ddframework/blob/main/ghost-observer/ghost/rules/__init__.py) (Advisor rules), [`AO/crates/ca-shell/src/rituals.rs`](https://github.com/darknorthaco/ddframework/blob/main/AO/crates/ca-shell/src/rituals.rs) (Shell rituals)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Ritual execution"]
  node_executor["ddf-exec CLI<br/>[main.rs]"]
end

subgraph group_audit["Ledger integrity"]
  node_ledger[("Ledger engine<br/>[ledger.rs]")]
  node_canonical["Canonical JSON<br/>[canonical.rs]"]
  node_sha["SHA-256<br/>[sha256.rs]"]
  node_timestamp["Timestamps<br/>[timestamp.rs]"]
  node_reader["Ledger reader<br/>[reader.py]"]
end

subgraph group_observer["GHOST advising"]
  node_advisor["Advisor orchestration<br/>[advisor.py]"]
  node_context["Advisor data model<br/>[model.py]"]
  node_rules["Advisor rules<br/>[__init__.py]"]
  node_rule_r003["Binary staleness"]
  node_rule_r004["Waiver expiry"]
  node_rule_r007["Ledger staleness"]
  node_writer[("Advisory writer<br/>[advisory_writer.py]")]
end

subgraph group_simulation["Simulation"]
  node_sim_cli["Simulation CLI<br/>[_sim_cli.py]"]
  node_doctrine_diff["Doctrine diff<br/>[doctrine_diff.py]"]
  node_ritual_dryrun["Ritual dry run<br/>[ritual_dryrun.py]"]
  node_ledger_replay["Ledger replay<br/>[ledger_replay.py]"]
  node_advisory_replay["Advisory replay<br/>[advisory_replay.py]"]
  node_drift_simulation["Drift simulation"]
end

subgraph group_application["Agent shell"]
  node_shell_cli["Shell CLI<br/>[main.rs]"]
  node_shell_rituals["Shell rituals<br/>[rituals.rs]"]
  node_shell_config["Shell configuration<br/>[config.rs]"]
  node_shell_kernel["Kernel adapter<br/>[kernel.rs]"]
  node_shell_record["Shell ledger records<br/>[ledger_record.rs]"]
end

node_operator(("Operator"))

node_operator -->|"invokes rituals"| node_executor
node_executor -.->|"uses ledger"| node_ledger
node_ledger -->|"canonicalizes entries"| node_canonical
node_ledger -->|"hashes entries"| node_sha
node_canonical -->|"computes hashes"| node_sha
node_executor -.->|"uses timestamps"| node_timestamp
node_operator -->|"requests verification"| node_reader
node_advisor -->|"reads validated ledger"| node_reader
node_advisor -->|"builds context"| node_context
node_advisor -->|"runs checks"| node_rules
node_rules -->|"registers rule"| node_rule_r003
node_rules -->|"registers rule"| node_rule_r004
node_rules -->|"registers rule"| node_rule_r007
node_rule_r004 -->|"reads context"| node_context
node_advisor -->|"appends advisories"| node_writer
node_operator -->|"requests simulation"| node_sim_cli
node_sim_cli -->|"dispatches"| node_doctrine_diff
node_sim_cli -->|"dispatches"| node_ritual_dryrun
node_sim_cli -->|"dispatches"| node_ledger_replay
node_sim_cli -->|"dispatches"| node_advisory_replay
node_sim_cli -->|"dispatches"| node_drift_simulation
node_operator -->|"uses shell"| node_shell_cli
node_shell_cli -.->|"dispatches rituals"| node_shell_rituals
node_shell_rituals -->|"verifies engine"| node_shell_kernel
node_shell_rituals -->|"appends events"| node_shell_record
node_shell_rituals -->|"reads configuration"| node_shell_config

click node_executor "https://github.com/darknorthaco/ddframework/blob/main/ddf-exec-core/src/main.rs"
click node_ledger "https://github.com/darknorthaco/ddframework/blob/main/ddf-exec-core/src/ledger.rs"
click node_canonical "https://github.com/darknorthaco/ddframework/blob/main/ddf-exec-core/src/canonical.rs"
click node_sha "https://github.com/darknorthaco/ddframework/blob/main/ddf-exec-core/src/sha256.rs"
click node_timestamp "https://github.com/darknorthaco/ddframework/blob/main/ddf-exec-core/src/timestamp.rs"
click node_reader "https://github.com/darknorthaco/ddframework/blob/main/ghost-observer/ghost/reader.py"
click node_advisor "https://github.com/darknorthaco/ddframework/blob/main/ghost-observer/ghost/advisor.py"
click node_context "https://github.com/darknorthaco/ddframework/blob/main/ghost-observer/ghost/model.py"
click node_rules "https://github.com/darknorthaco/ddframework/blob/main/ghost-observer/ghost/rules/__init__.py"
click node_rule_r003 "https://github.com/darknorthaco/ddframework/blob/main/ghost-observer/ghost/rules/r003_binary_stale.py"
click node_rule_r004 "https://github.com/darknorthaco/ddframework/blob/main/ghost-observer/ghost/rules/r004_waiver_expiring.py"
click node_rule_r007 "https://github.com/darknorthaco/ddframework/blob/main/ghost-observer/ghost/rules/r007_ledger_staleness.py"
click node_writer "https://github.com/darknorthaco/ddframework/blob/main/ghost-observer/ghost/advisory_writer.py"
click node_sim_cli "https://github.com/darknorthaco/ddframework/blob/main/ddf-core/ddf_py/ddf/_sim_cli.py"
click node_doctrine_diff "https://github.com/darknorthaco/ddframework/blob/main/ddf-core/simulation/doctrine_diff.py"
click node_ritual_dryrun "https://github.com/darknorthaco/ddframework/blob/main/ddf-core/simulation/ritual_dryrun.py"
click node_ledger_replay "https://github.com/darknorthaco/ddframework/blob/main/ddf-core/simulation/ledger_replay.py"
click node_advisory_replay "https://github.com/darknorthaco/ddframework/blob/main/ddf-core/simulation/advisory_replay.py"
click node_drift_simulation "https://github.com/darknorthaco/ddframework/blob/main/ddf-core/simulation/drift_simulation.py"
click node_shell_cli "https://github.com/darknorthaco/ddframework/blob/main/AO/crates/ca-shell/src/main.rs"
click node_shell_rituals "https://github.com/darknorthaco/ddframework/blob/main/AO/crates/ca-shell/src/rituals.rs"
click node_shell_config "https://github.com/darknorthaco/ddframework/blob/main/AO/crates/ca-shell/src/config.rs"
click node_shell_kernel "https://github.com/darknorthaco/ddframework/blob/main/AO/crates/ca-shell/src/kernel.rs"
click node_shell_record "https://github.com/darknorthaco/ddframework/blob/main/AO/crates/ca-shell/src/ledger_record.rs"

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_executor toneBlue
class node_ledger,node_canonical,node_sha,node_timestamp,node_reader toneAmber
class node_advisor,node_context,node_rules,node_rule_r003,node_rule_r004,node_rule_r007,node_writer toneMint
class node_sim_cli,node_doctrine_diff,node_ritual_dryrun,node_ledger_replay,node_advisory_replay,node_drift_simulation toneRose
class node_shell_cli,node_shell_rituals,node_shell_config,node_shell_kernel,node_shell_record,node_operator toneIndigo
```

## Components

### Ritual execution

- [ddf-exec CLI](https://github.com/darknorthaco/ddframework/blob/main/ddf-exec-core/src/main.rs): `ddf-exec-core/src/main.rs`

### Ledger integrity

- [Ledger engine](https://github.com/darknorthaco/ddframework/blob/main/ddf-exec-core/src/ledger.rs): `ddf-exec-core/src/ledger.rs`
- [Canonical JSON](https://github.com/darknorthaco/ddframework/blob/main/ddf-exec-core/src/canonical.rs): `ddf-exec-core/src/canonical.rs`
- [SHA-256](https://github.com/darknorthaco/ddframework/blob/main/ddf-exec-core/src/sha256.rs): `ddf-exec-core/src/sha256.rs`
- [Timestamps](https://github.com/darknorthaco/ddframework/blob/main/ddf-exec-core/src/timestamp.rs): `ddf-exec-core/src/timestamp.rs`
- [Ledger reader](https://github.com/darknorthaco/ddframework/blob/main/ghost-observer/ghost/reader.py): `ghost-observer/ghost/reader.py`

### GHOST advising

- [Advisor orchestration](https://github.com/darknorthaco/ddframework/blob/main/ghost-observer/ghost/advisor.py): `ghost-observer/ghost/advisor.py`
- [Advisor data model](https://github.com/darknorthaco/ddframework/blob/main/ghost-observer/ghost/model.py): `ghost-observer/ghost/model.py`
- [Advisor rules](https://github.com/darknorthaco/ddframework/blob/main/ghost-observer/ghost/rules/__init__.py): `ghost-observer/ghost/rules/__init__.py`
- [Binary staleness](https://github.com/darknorthaco/ddframework/blob/main/ghost-observer/ghost/rules/r003_binary_stale.py): `ghost-observer/ghost/rules/r003_binary_stale.py`
- [Waiver expiry](https://github.com/darknorthaco/ddframework/blob/main/ghost-observer/ghost/rules/r004_waiver_expiring.py): `ghost-observer/ghost/rules/r004_waiver_expiring.py`
- [Ledger staleness](https://github.com/darknorthaco/ddframework/blob/main/ghost-observer/ghost/rules/r007_ledger_staleness.py): `ghost-observer/ghost/rules/r007_ledger_staleness.py`
- [Advisory writer](https://github.com/darknorthaco/ddframework/blob/main/ghost-observer/ghost/advisory_writer.py): `ghost-observer/ghost/advisory_writer.py`

### Simulation

- [Simulation CLI](https://github.com/darknorthaco/ddframework/blob/main/ddf-core/ddf_py/ddf/_sim_cli.py): `ddf-core/ddf_py/ddf/_sim_cli.py`
- [Doctrine diff](https://github.com/darknorthaco/ddframework/blob/main/ddf-core/simulation/doctrine_diff.py): `ddf-core/simulation/doctrine_diff.py`
- [Ritual dry run](https://github.com/darknorthaco/ddframework/blob/main/ddf-core/simulation/ritual_dryrun.py): `ddf-core/simulation/ritual_dryrun.py`
- [Ledger replay](https://github.com/darknorthaco/ddframework/blob/main/ddf-core/simulation/ledger_replay.py): `ddf-core/simulation/ledger_replay.py`
- [Advisory replay](https://github.com/darknorthaco/ddframework/blob/main/ddf-core/simulation/advisory_replay.py): `ddf-core/simulation/advisory_replay.py`
- [Drift simulation](https://github.com/darknorthaco/ddframework/blob/main/ddf-core/simulation/drift_simulation.py): `ddf-core/simulation/drift_simulation.py`

### Agent shell

- [Shell CLI](https://github.com/darknorthaco/ddframework/blob/main/AO/crates/ca-shell/src/main.rs): `AO/crates/ca-shell/src/main.rs`
- [Shell rituals](https://github.com/darknorthaco/ddframework/blob/main/AO/crates/ca-shell/src/rituals.rs): `AO/crates/ca-shell/src/rituals.rs`
- [Shell configuration](https://github.com/darknorthaco/ddframework/blob/main/AO/crates/ca-shell/src/config.rs): `AO/crates/ca-shell/src/config.rs`
- [Kernel adapter](https://github.com/darknorthaco/ddframework/blob/main/AO/crates/ca-shell/src/kernel.rs): `AO/crates/ca-shell/src/kernel.rs`
- [Shell ledger records](https://github.com/darknorthaco/ddframework/blob/main/AO/crates/ca-shell/src/ledger_record.rs): `AO/crates/ca-shell/src/ledger_record.rs`

### Other components

- **Operator**

## Connections

- Operator → ddf-exec CLI: invokes rituals (evidence: `README.md`)
- ddf-exec CLI → Ledger engine: uses ledger
- Ledger engine → Canonical JSON: canonicalizes entries (evidence: `ddf-exec-core/src/ledger.rs`)
- Ledger engine → SHA-256: hashes entries (evidence: `ddf-exec-core/src/ledger.rs`)
- Canonical JSON → SHA-256: computes hashes (evidence: `ddf-exec-core/src/canonical.rs`)
- ddf-exec CLI → Timestamps: uses timestamps
- Operator → Ledger reader: requests verification (evidence: `README.md`)
- Advisor orchestration → Ledger reader: reads validated ledger (evidence: `ghost-observer/ghost/advisor.py`)
- Advisor orchestration → Advisor data model: builds context (evidence: `ghost-observer/ghost/advisor.py`)
- Advisor orchestration → Advisor rules: runs checks (evidence: `ghost-observer/ghost/advisor.py`)
- Advisor rules → Binary staleness: registers rule (evidence: `ghost-observer/ghost/rules/__init__.py`)
- Advisor rules → Waiver expiry: registers rule (evidence: `ghost-observer/ghost/rules/__init__.py`)
- Advisor rules → Ledger staleness: registers rule (evidence: `ghost-observer/ghost/rules/__init__.py`)
- Waiver expiry → Advisor data model: reads context (evidence: `ghost-observer/ghost/rules/r004_waiver_expiring.py`)
- Advisor orchestration → Advisory writer: appends advisories (evidence: `ghost-observer/ghost/advisor.py`)
- Operator → Simulation CLI: requests simulation (evidence: `README.md`)
- Simulation CLI → Doctrine diff: dispatches (evidence: `ddf-core/ddf_py/ddf/_sim_cli.py`)
- Simulation CLI → Ritual dry run: dispatches (evidence: `ddf-core/ddf_py/ddf/_sim_cli.py`)
- Simulation CLI → Ledger replay: dispatches (evidence: `ddf-core/ddf_py/ddf/_sim_cli.py`)
- Simulation CLI → Advisory replay: dispatches (evidence: `ddf-core/ddf_py/ddf/_sim_cli.py`)
- Simulation CLI → Drift simulation: dispatches (evidence: `ddf-core/ddf_py/ddf/_sim_cli.py`)
- Operator → Shell CLI: uses shell (evidence: `README.md`)
- Shell CLI → Shell rituals: dispatches rituals
- Shell rituals → Kernel adapter: verifies engine (evidence: `AO/crates/ca-shell/src/rituals.rs`)
- Shell rituals → Shell ledger records: appends events (evidence: `AO/crates/ca-shell/src/rituals.rs`)
- Shell rituals → Shell configuration: reads configuration (evidence: `AO/crates/ca-shell/src/rituals.rs`)
