Architecture

Project structure

Before you read: Clone, build and test — you have a checkout that builds, and know which gates exist.

This page is the map of the repository: what each top-level file and directory is, who changes it and when, and which parts are generated and must never be edited by hand. Read it after Clone, build and test and before Architecture — the architecture explains why the code is split the way it is; this page tells you where things are. After it you can place any path in the repository, say who changes it, and know whether you may edit it by hand or must regenerate it.

A CI gate keeps it honest: python3 scripts/dev_docs.py --check fails when a tracked top-level path (or a second-level directory of crates/, bins/ or docs/) is missing from the tables below, or when a table names a path that no longer exists.

Reading the repository in five minutes#

Start at the root and follow the dependencies inward:

1. Cargo.toml — the workspace: every member crate, and every dependency version (members only write { workspace = true }).
2. bins/delonix-runtime-bin/src/main.rs — the delonix CLI. Each command group is one module under src/cmd/; follow the group you care about.
3. crates/<layer>/<crate>/src/lib.rs — the engine. The directory is the layer (foundation → contexts → adapters / providers → interfaces), and every lib.rs opens with a //! comment saying what the crate does. The crates has one section per crate.
4. docs/dev/ — this handbook. docs/adr/ — the decisions behind the structure.

AGENTS.md is the long, Portuguese working journal of the project. It is useful for finding where to look, but parts of it are out of date; confirm anything it says in the code.

Annotated tree#

.
├── Cargo.toml, Cargo.lock        workspace members, shared dependency versions, lock file
├── rust-toolchain.toml           pinned Rust toolchain (clippy + rustfmt)
├── buf.yaml                      buf modules/lint for the node contract in proto/
├── deny.toml                     cargo-deny policy (advisories, licences, sources)
├── Makefile, Delonixfile         release binaries and the secondary CLI image
├── AGENTS.md                     project journal and agent rules (Portuguese)
├── ARCHITECTURE.md               C4 model of the engine (Portuguese)
├── README.rst, CONTRIBUTING.md   user entry point, contributor entry point
├── GOVERNANCE.md, MAINTAINERS.md, CODE_OF_CONDUCT.md, SECURITY.md, LICENSE
├── .clinerules, .cursorrules     pointers to AGENTS.md for AI coding tools
├── .dockerignore, .gitignore, .git-blame-ignore-revs
├── .ai/                          skills for AI assistants (E2E quality)
├── .github/                      CI and release workflows, CODEOWNERS, issue/PR templates
├── crates/
│   ├── foundation/               pure shared types and rules (no mechanism)
│   ├── contexts/                 Compute, Stack, security decisions
│   ├── adapters/                 Linux, OCI, SDN, VM, volumes, state, scanner, telemetry
│   ├── providers/                remote systems behind ports (Proxmox VE, TrueNAS)
│   └── interfaces/               CRI, local management API, node API, MCP server
├── bins/
│   ├── delonix-runtime-bin/      the `delonix` CLI (+ templates, pt.po catalogue)
│   ├── delonix-mgmt-bin/         the `delonix-mgmt` binary
│   ├── delonix-node-api-bin/     the `delonix-node-api` binary
│   └── delonix-mcp-bin/          the `delonix-mcp` binary
├── proto/                        node contract delonix.node.v1 (draft, ADR-0040)
├── third_party/                  vendored googleapis protos (Apache-2.0)
├── tests/                        out-of-tree compatibility scripts (CRI, Docker API)
├── docs/
│   ├── adr/                      Architecture Decision Records
│   ├── api/                      OpenAPI — generated from proto/
│   ├── comandos/                 per-command user pages — generated by docs/gen.py
│   ├── dev/                      this handbook (English + translations)
│   ├── discovery/                dated investigations (historical)
│   ├── handbook/                 this handbook as HTML — generated
│   ├── releases/                 release notes, one per version (historical)
│   ├── roadmap/                  improvement-programme traceability matrix
│   ├── runtime/                  dated runtime discovery (historical)
│   └── schema/                   manifest JSON Schema — generated from code
├── scripts/                      CI gates, generators, E2E/chaos harnesses, installer
├── examples/                     manifests validated by CI
├── images/                       one folder per VM image: a `vm.yaml` recipe and a README
├── dist/                         systemd unit for delonix-cri
├── editors/                      VMfile syntax for Vim and VS Code
└── reports/                      dated audit reports (historical)

Top-level files#

Source code (crates/, bins/, proto/, tests/)#

The crate list, each crate's layer and who depends on whom are generated facts in Architecture and The crates; they are not repeated here.

Documentation (docs/…)#

docs/ is also the GitHub Pages root. Its top-level files are a mix: the HTML pages (index.html, cheatsheet.html, estrutura.html, …) and .nojekyll are generated by docs/gen.py; gen.py itself and Markdown such as cli-stability.md, gitops.md, estrutura.md, guia-vm-lab.md are hand-written sources that it renders; RELEASES.md is generated by scripts/gen-releases.sh; and dated reports (AUDITORIA-E2E.md, RELATORIO-PRE-PRODUCAO.md, paridade-docker-podman.md, comparacao-medida.md, sovereignty-engine.md) record what was measured on a given date.

Tooling, CI and packaging (scripts/, .github/, dist/, editors/, examples/, reports/, third_party/, .ai/)#

Generated vs hand-written#

Everything below is produced by a command. Edit the source, run the generator, commit both — and expect CI to fail if you edit the output by hand.

Not committed at all: the manpages (delonix man --dir, checked with groff in CI) and target/.

Where does a new file go?#

• A type or rule every layer can name, with no I/O → crates/foundation/. Pure network math goes in delonix-net-rules; data-only records and names in delonix-model.
• A decision or use case (what to run, what a Kind means, a plan) → crates/contexts/.
• Code that calls the kernel, the disk or a local tool (ip, nft, qemu-img) → crates/adapters/, in the crate that owns that mechanism.
• An integration with a remote system → a new port implementation in crates/providers/, never an if provider == … in existing code.
• A new protocol server → crates/interfaces/, composed by exactly one binary in bins/.
• A CLI command or flag → a module in bins/delonix-runtime-bin/src/cmd/, with its Portuguese translation in data/pt.po.
• A new crate → the directory of its layer and the LAYERS table in scripts/arch_fitness.py and [workspace.dependencies] in Cargo.toml, in the same commit.
• An example manifest → examples/ (CI dry-runs it). A structural decision → docs/adr/. Contributor documentation → docs/dev/.

The rules behind this list, with examples, are in Coding conventions — Structure: where code goes and The crates.

Next: Architecture — why the code is split that way: the layers, the processes at runtime, the crate graph and the state on disk.