Architecture

Structure du projet

Avant de lire : Cloner, compiler et tester — vous avez un checkout qui compile, et vous savez quels gates existent.

Cette page est la carte du dépôt : ce qu’est chaque fichier et répertoire de premier niveau, qui le modifie et quand, et quelles parties sont générées et ne doivent jamais être éditées à la main. Lisez-la après Cloner, compiler et tester et avant Architecture — l’architecture explique pourquoi le code est découpé ainsi ; cette page vous dit où se trouvent les choses. Après elle, vous pourrez situer n’importe quel chemin du dépôt, dire qui le modifie, et savoir si vous pouvez l’éditer à la main ou devez le régénérer.

Un gate de CI la garde honnête : python3 scripts/dev_docs.py --check échoue quand un chemin de premier niveau suivi (ou un répertoire de second niveau de crates/, bins/ ou docs/) manque dans les tableaux ci-dessous, ou quand un tableau nomme un chemin qui n’existe plus.

Lire le dépôt en cinq minutes#

Commencez à la racine et suivez les dépendances vers l’intérieur :

1. Cargo.toml — le workspace : chaque crate membre, et chaque version de dépendance (les membres n’écrivent que { workspace = true }).
2. bins/delonix-runtime-bin/src/main.rs — la CLI delonix. Chaque groupe de commandes est un module sous src/cmd/ ; suivez le groupe qui vous intéresse.
3. crates/<couche>/<crate>/src/lib.rs — le moteur. Le répertoire est la couche (foundation → contexts → adapters / providers → interfaces), et chaque lib.rs s’ouvre sur un commentaire //! disant ce que fait le crate. Les crates a une section par crate.
4. docs/dev/ — ce manuel. docs/adr/ — les décisions derrière la structure.

AGENTS.md est le long journal de travail du projet, en portugais. Il est utile pour trouver où chercher, mais certaines parties sont obsolètes ; vérifiez dans le code ce qu’il affirme.

Arborescence annotée#

.
├── 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)

Fichiers de premier niveau#

Code source (crates/, bins/, proto/, tests/)#

La liste des crates, la couche de chacun et qui dépend de qui sont des faits générés dans Architecture et Les crates ; ils ne sont pas répétés ici.

Documentation (docs/…)#

docs/ est aussi la racine de GitHub Pages. Ses fichiers de premier niveau sont un mélange : les pages HTML (index.html, cheatsheet.html, estrutura.html, …) et .nojekyll sont générés par docs/gen.py ; gen.py lui-même et du Markdown comme cli-stability.md, gitops.md, estrutura.md, guia-vm-lab.md sont des sources écrites à la main qu’il rend ; RELEASES.md est généré par scripts/gen-releases.sh ; et des rapports datés (AUDITORIA-E2E.md, RELATORIO-PRE-PRODUCAO.md, paridade-docker-podman.md, comparacao-medida.md, sovereignty-engine.md) consignent ce qui a été mesuré à une date donnée.

Outillage, CI et empaquetage (scripts/, .github/, dist/, editors/, examples/, reports/, third_party/, .ai/)#

Généré vs écrit à la main#

Tout ce qui suit est produit par une commande. Éditez la source, exécutez le générateur, commitez les deux — et attendez-vous à ce que la CI échoue si vous éditez la sortie à la main.

Pas du tout commité : les pages de manuel (delonix man --dir, vérifiées avec groff en CI) et target/.

Où va un nouveau fichier ?#

• Un type ou une règle que n’importe quelle couche peut nommer, sans E/S → crates/foundation/. Les mathématiques réseau pures vont dans delonix-net-rules ; les enregistrements uniquement-données et les noms vont dans delonix-model.
• Une décision ou un cas d’usage (quoi exécuter, ce que signifie un Kind, un plan) → crates/contexts/.
• Du code qui appelle le noyau, le disque ou un outil local (ip, nft, qemu-img) → crates/adapters/, dans le crate qui possède ce mécanisme.
• Une intégration avec un système distant → une nouvelle implémentation de port dans crates/providers/, jamais un if provider == … dans du code existant.
• Un nouveau serveur de protocole → crates/interfaces/, composé par exactement un binaire dans bins/.
• Une commande ou une option de la CLI → un module dans bins/delonix-runtime-bin/src/cmd/, avec sa traduction portugaise dans data/pt.po.
• Un nouveau crate → le répertoire de sa couche et la table LAYERS dans scripts/arch_fitness.py et [workspace.dependencies] dans Cargo.toml, dans le même commit.
• Un manifeste d’exemple → examples/ (la CI en fait un dry-run). Une décision structurelle → docs/adr/. Documentation pour contributeurs → docs/dev/.

Les règles derrière cette liste, avec des exemples, se trouvent dans Conventions de code — Structure : où va le code et Les crates.

Suivant : Architecture — pourquoi le code est découpé ainsi : les couches, les processus en exécution, le graphe des crates et l’état sur disque.