Alveolus

Apparence

Filtrer les règles par style d’implémentation

Mettre en place un projet ​

Un projet qui suit ces règles déclare quatre artefacts, que certaines règles lisent, et installe les building blocks.

Artefacts du projet ​

La plupart des règles se jugent sur le code seul. Certaines dépendent de ce que le projet a déclaré : quels contextes existent et comment ils se parlent, quels mots sont permis, quelles décisions ont été prises.

ArtefactEmplacement suggéréRègles qui en dépendent
Context mapdocs/context-map.mdCTX-01, CTX-13, CTX-04, CTX-07, CTX-11, MAP-01, MAP-02, MAP-03, MAP-04, PRC-04, REP-06
Glossairedocs/<context>/glossary.mdENT-11, CTX-03, PLC-05, CTX-02, CTX-08, CTX-09
Décisions (ADR)docs/adr/NNNN-title.mdToutes les règles conditionnelles, AGG-10, CTX-16, CTX-13, et les waivers structurels
Propriété du codeCODEOWNERSCTX-12, MAP-03

Dans un monorepo, docs/ peut se trouver à côté de chaque application. L’essentiel est qu’on les trouve sans chercher, et qu’ils changent dans la même MR que le code qu’ils décrivent.

Sans ces artefacts

Une règle qui dépend d’un artefact absent ne peut pas conclure à un défaut. Elle devient une question, et la revue signale l’artefact manquant dans son résumé.

Context map ​

Elle déclare les contextes et leurs relations. Sa forme la plus détaillée est le code d’intégration lui-même : la carte dit ce que ce code doit respecter (MAP-01).

Pour chaque contexte :

  • le nom, tel que le langage le dit ;
  • le type de subdomain : core, supporting ou generic (CTX-13) ;
  • l’équipe propriétaire (CTX-12) ;
  • le dossier du code ;
  • les tables qu’il possède, que personne d’autre ne lit (MAP-02) ;
  • les aggregates conservés, jamais supprimés physiquement (REP-06).

Pour chaque relation entre deux contextes :

  • lequel est upstream, lequel est downstream ;
  • le pattern de chaque côté : open host service, published language, anticorruption layer, conformist, customer-supplier, partnership, shared kernel ou separate ways ;
  • le mode d’intégration : appel dans le processus, HTTP, messages ;
  • le contrat publié, c’est-à-dire le dossier public ou le schéma qui le décrit (PUB-01).

Enfin, les zones déclarées big ball of mud (MAP-04), qu’architecture.json déclare aussi (CTX-14), et les shared kernels avec leurs deux équipes (MAP-03).

md
## Contextes

| Contexte | Subdomain | Équipe | Dossier | Tables | Aggregates conservés |
| --- | --- | --- | --- | --- | --- |
| Payments | core | Équipe Payments | src/payments | transfer, transfer_leg | Transfer |
| Treasury | supporting | Équipe Treasury | src/treasury | wallet, funding | Wallet |

## Relations

| Upstream | Downstream | Côté upstream | Côté downstream | Intégration | Contrat |
| --- | --- | --- | --- | --- | --- |
| Treasury | Payments | Open host service, published language | Anticorruption layer | Appel dans le processus | src/treasury/public |
| Payments | Treasury | Published language | Conformist | Messages (outbox) | src/payments/public/transfer-executed.v1.ts |

Glossaire ​

Un glossaire par contexte : le langage n’est pas universel (CTX-01). Il relie le langage de l’équipe au code, et liste les termes à ne pas employer.

ColonneContenu
TermeLe mot tel que l’équipe le dit.
CodeLe nom dans le code (classe, méthode, event).
DéfinitionUne phrase, validée avec les experts métier.
Termes rejetésLes synonymes ou anciens noms à ne pas employer dans ce contexte (CTX-03).
md
| Terme | Code | Définition | Termes rejetés |
| --- | --- | --- | --- |
| Virement | `Transfer` | Un ordre de transférer un montant d’un wallet vers un bénéficiaire. | Paiement, transaction |
| Exécuter | `execute()` | Débiter le wallet et envoyer le virement. | Traiter, gérer |

Un glossaire vieillit : un terme absent n’est pas forcément une erreur, c’est une question (CTX-03).

Décisions (ADR) ​

Une décision d’architecture par fichier, numérotée et jamais réécrite : une nouvelle ADR la remplace et la marque « superseded ». Format court : contexte, décision, conséquences, règles concernées.

Une ADR est attendue pour :

  • activer une règle conditionnelle : multi-tenant (ENT-09) ;
  • s’écarter d’un choix par défaut d’Alveolus ;
  • trancher une question que posent les règles : cohérence dans la transaction ou eventual consistency (AGG-10), style structurel (CTX-16), investissement tactique (CTX-13) ;
  • appuyer un waiver structurel, cité par le commentaire du waiver (voir les waivers).

Propriété du code ​

Un fichier CODEOWNERS attribue chaque dossier de contexte à une seule équipe (CTX-12). Un dossier de shared kernel demande l’approbation des deux équipes qui le partagent (MAP-03). On le déclare par une ligne de commentaire juste au-dessus de son entrée :

# shared kernel: money, owned by payments and treasury (MAP-03)
/src/money/ @bank/payments @bank/treasury

Outillage ​

Les building blocks et les règles pour Claude Code sont livrés dans deux packages publiés sur npm, réutilisables d’un projet à l’autre. Premiers pas montre comment les installer.

PackageContenu
@alveolus/coreAggregateRoot, Entity, ValueObject, Identifier, DomainEvent, DomainError, les ports (Clock, IdGenerator), les repositories, CommandHandler et QueryHandler, UnitOfWork, Outbox et OutboxRelay, Result. Aucune dépendance à l’exécution.
@alveolus/claude-rulesLes règles, en règles de Claude Code chargées par dossier, trois skills pour mener une user story de la conception à la revue, et un agent de revue. S’installe en dépendance de développement.