Core concepts

Rhodd compiles a system in nine local stages. Four of them produce the artifacts that make Rhodd a compiler rather than a generator: the model, quality report, ownership records and handoff. This page explains the concepts behind each.

The system model

model builds a typed, in-memory representation of the whole system — every service, its kind and runtime, the modules it uses, and the relationships between them. A template copies files and forgets; the model is the object that lets Rhodd reason about the system on the next change.

The graph

graph resolves the dependencies into a directed graph and proves it acyclic. It is emitted as graph.json — the system as machine-readable data, not a diagram you maintain by hand.

{
  "nodes": ["web", "api", "postgres", "redis"],
  "edges": [
    { "from": "web", "to": "api",      "kind": "depends_on" },
    { "from": "api", "to": "postgres", "kind": "owns" }
  ],
  "cycles": 0
}

The plan

plan computes the full write set before touching disk. The plan is a dry run: it lists every file the compile intends to create, so there are no surprises.

The lock

lock hashes the input and the generated tree and freezes .rhodd.lock. It is the reproducibility receipt — re-running with the same input yields the same output_hash.

{
  "input_hash":   "sha256:a91f…3e0c",
  "output_hash":  "sha256:77bd…12af",
  "compiler":     "rhodd@0.1.0",
  "reproducible": true
}

Ownership

ownership records which paths Rhodd generates versus the source you own. Regeneration only ever rewrites generated paths, so it never clobbers your code. See Safety & boundaries.

Handoff

handoff writes the .rhodd/ai directory — a compact, ordered context pack that a future contributor, or an AI agent, can read to continue safely. AI consumes it; it never drives the compile. See AI handoff.

The .rhodd/ state

Together these land in a single state directory you can read, diff and commit:

.rhodd/
├── model.json
├── graph.json
├── plan.json
├── ownership.json
├── manifest.json
├── quality.json
└── ai/            # handoff for humans + AI
.rhodd.lock        # reproducible: true