# terracotta-linux/kiln architecture

> Architecture diagram of the GitHub repository terracotta-linux/kiln, 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/terracotta-linux/kiln
- Repository: https://github.com/terracotta-linux/kiln
- Video tour (about a minute): https://gitdiagram.com/terracotta-linux/kiln/video

## Overview

Kiln turns local TOML into a bootable Arch system image through frontend, resolution, realization, assembly, normalization, and OSTree deployment. The plan/realize boundary supports `check` without building; commits carry records used for change detection and reconstruction. The README documents major capabilities beyond the sampled excerpts, so those are represented at their documented subsystem paths; edges are limited to the documented workflow and sampled orchestration.

Main entry points: [`crates/kiln-cli/src/main.rs`](https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-cli/src/main.rs) (Command dispatch), [`crates/kiln-cli/src/build.rs`](https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-cli/src/build.rs) (Build and apply), [`crates/kiln-resolve/src/lib.rs`](https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-resolve/src/lib.rs) (Plan resolution), [`crates/kiln-cli/src/pipeline.rs`](https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-cli/src/pipeline.rs) (Build pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["CLI and config"]
  node_cli["Command dispatch<br/>[main.rs]"]
  node_frontend["Config frontend<br/>[lib.rs]"]
  node_config_include["Include and merge<br/>[include.rs]"]
  node_config_validate["Validate manifest<br/>[validate.rs]"]
  node_cli_check["Check commands<br/>[check.rs]"]
end

subgraph group_planning["Manifest and resolution"]
  node_manifest["Canonical manifest<br/>[manifest.rs]"]
  node_pipeline["Build pipeline<br/>[pipeline.rs]"]
  node_resolve["Plan resolution<br/>[lib.rs]"]
  node_alpm["Arch package solver<br/>[session.rs]"]
  node_aur["AUR metadata<br/>[lib.rs]"]
end

subgraph group_build["Build and image"]
  node_cli_build["Build and apply<br/>[build.rs]"]
  node_realize["Package realization<br/>[build.rs]"]
  node_sandbox["Build isolation<br/>[lib.rs]"]
  node_assembly["Root assembly<br/>[assemble.rs]"]
  node_normalize["Image normalization<br/>[normalize.rs]"]
end

subgraph group_deploy["OSTree and history"]
  node_record["Build record<br/>[record.rs]"]
  node_ostree["Commit and deploy<br/>[lib.rs]"]
  node_deployment["Generation control<br/>[deploy.rs]"]
  node_generations[("OSTree repository")]
end

node_user(("System operator"))

node_user -->|"runs commands"| node_cli
node_cli -->|"loads config"| node_frontend
node_frontend -->|"expands includes"| node_config_include
node_frontend -->|"validates input"| node_config_validate
node_config_validate -->|"produces"| node_manifest
node_cli -->|"starts workflow"| node_pipeline
node_pipeline -->|"resolves manifest"| node_resolve
node_resolve -->|"reads"| node_manifest
node_resolve -->|"queries repositories"| node_alpm
node_resolve -.->|"queries AUR"| node_aur
node_cli -->|"dispatches check"| node_cli_check
node_cli_check -->|"plans changes"| node_pipeline
node_cli -->|"dispatches build"| node_cli_build
node_cli_build -->|"plans build"| node_pipeline
node_cli_build -->|"realizes plan"| node_realize
node_realize -->|"runs isolated builds"| node_sandbox
node_cli_build -->|"assembles image"| node_assembly
node_assembly -->|"transacts packages"| node_alpm
node_assembly -->|"normalizes root"| node_normalize
node_cli_build -->|"commits image"| node_ostree
node_ostree -->|"stores build record"| node_record
node_ostree -->|"writes commit"| node_generations
node_cli -->|"dispatches generation commands"| node_deployment
node_deployment -->|"stages or reorders"| node_generations

click node_cli "https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-cli/src/main.rs"
click node_frontend "https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-config/src/lib.rs"
click node_config_include "https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-config/src/include.rs"
click node_config_validate "https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-config/src/validate.rs"
click node_manifest "https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-manifest/src/manifest.rs"
click node_pipeline "https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-cli/src/pipeline.rs"
click node_resolve "https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-resolve/src/lib.rs"
click node_alpm "https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-alpm/src/session.rs"
click node_aur "https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-aur/src/lib.rs"
click node_cli_check "https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-cli/src/check.rs"
click node_cli_build "https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-cli/src/build.rs"
click node_realize "https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-build/src/build.rs"
click node_sandbox "https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-sandbox/src/lib.rs"
click node_assembly "https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-image/src/assemble.rs"
click node_normalize "https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-image/src/normalize.rs"
click node_record "https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-record/src/record.rs"
click node_ostree "https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-ostree/src/lib.rs"
click node_deployment "https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-ostree/src/deploy.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_cli,node_frontend,node_config_include,node_config_validate,node_cli_check toneBlue
class node_manifest,node_pipeline,node_resolve,node_alpm,node_aur toneAmber
class node_cli_build,node_realize,node_sandbox,node_assembly,node_normalize toneMint
class node_record,node_ostree,node_deployment,node_generations toneRose
class node_user toneIndigo
```

## Components

### CLI and config

- [Command dispatch](https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-cli/src/main.rs): `crates/kiln-cli/src/main.rs`
- [Config frontend](https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-config/src/lib.rs): `crates/kiln-config/src/lib.rs`
- [Include and merge](https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-config/src/include.rs): `crates/kiln-config/src/include.rs`
- [Validate manifest](https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-config/src/validate.rs): `crates/kiln-config/src/validate.rs`
- [Check commands](https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-cli/src/check.rs): `crates/kiln-cli/src/check.rs`

### Manifest and resolution

- [Canonical manifest](https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-manifest/src/manifest.rs): `crates/kiln-manifest/src/manifest.rs`
- [Build pipeline](https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-cli/src/pipeline.rs): `crates/kiln-cli/src/pipeline.rs`
- [Plan resolution](https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-resolve/src/lib.rs): `crates/kiln-resolve/src/lib.rs`
- [Arch package solver](https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-alpm/src/session.rs): `crates/kiln-alpm/src/session.rs`
- [AUR metadata](https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-aur/src/lib.rs): `crates/kiln-aur/src/lib.rs`

### Build and image

- [Build and apply](https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-cli/src/build.rs): `crates/kiln-cli/src/build.rs`
- [Package realization](https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-build/src/build.rs): `crates/kiln-build/src/build.rs`
- [Build isolation](https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-sandbox/src/lib.rs): `crates/kiln-sandbox/src/lib.rs`
- [Root assembly](https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-image/src/assemble.rs): `crates/kiln-image/src/assemble.rs`
- [Image normalization](https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-image/src/normalize.rs): `crates/kiln-image/src/normalize.rs`

### OSTree and history

- [Build record](https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-record/src/record.rs): `crates/kiln-record/src/record.rs`
- [Commit and deploy](https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-ostree/src/lib.rs): `crates/kiln-ostree/src/lib.rs`
- [Generation control](https://github.com/terracotta-linux/kiln/blob/main/crates/kiln-ostree/src/deploy.rs): `crates/kiln-ostree/src/deploy.rs`
- **OSTree repository**

### Other components

- **System operator**

## Connections

- System operator → Command dispatch: runs commands
- Command dispatch → Config frontend: loads config
- Config frontend → Include and merge: expands includes
- Config frontend → Validate manifest: validates input
- Validate manifest → Canonical manifest: produces
- Command dispatch → Build pipeline: starts workflow
- Build pipeline → Plan resolution: resolves manifest
- Plan resolution → Canonical manifest: reads
- Plan resolution → Arch package solver: queries repositories
- Plan resolution → AUR metadata: queries AUR
- Command dispatch → Check commands: dispatches check
- Check commands → Build pipeline: plans changes
- Command dispatch → Build and apply: dispatches build
- Build and apply → Build pipeline: plans build
- Build and apply → Package realization: realizes plan
- Package realization → Build isolation: runs isolated builds
- Build and apply → Root assembly: assembles image
- Root assembly → Arch package solver: transacts packages
- Root assembly → Image normalization: normalizes root
- Build and apply → Commit and deploy: commits image
- Commit and deploy → Build record: stores build record
- Commit and deploy → OSTree repository: writes commit
- Command dispatch → Generation control: dispatches generation commands
- Generation control → OSTree repository: stages or reorders