Règles d’architecture et de modélisation

Statut documentaire : guide — voir Maturité et preuves.

Séparer strictement entité, rôle, relation et événement

L’une des règles les plus structurantes consiste à distinguer rigoureusement l’entité, le rôle, la relation et l’événement. Une entité possède une identité propre et une continuité au cours du temps. Un rôle, au contraire, est une qualification contextuelle et potentiellement temporaire. Une relation exprime un lien entre entités ou entre rôles et peut elle-même porter des attributs, une période de validité ou une base documentaire. Un événement représente un fait daté qui produit un changement d’état, une observation ou une conséquence métier.

Lorsque cette distinction n’est pas respectée, le modèle devient rapidement ambigu. Un même concept est alors utilisé pour désigner tantôt la personne, tantôt son statut, tantôt son appartenance à un groupe, tantôt un fait ponctuel. Il en résulte des schémas instables, des colonnes dont le sens change selon les cas, des écrans difficiles à expliquer et des règles métier impossibles à localiser. La première responsabilité de l’architecte consiste donc à imposer cette discipline dès les premières itérations de modélisation.

Protéger les niveaux ontologiques contre les contaminations

Un package fondationnel ne doit jamais dépendre d’un concept sectoriel, même de manière indirecte. Cette règle semble évidente, mais elle est souvent contournée par des champs, des statuts, des codes ou des énumérations qui introduisent silencieusement un vocabulaire sectoriel dans le noyau. Lorsqu’un package party commence à contenir des champs dédiés à l’éducation, à la relation client ou à la facturation, cela signifie que le noyau n’est plus maîtrisé. La bonne réponse n’est pas d’ajouter une colonne optionnelle, mais de déplacer la spécialisation au bon niveau.

De la même manière, un package transverse doit rester descriptible sans référence obligatoire à un secteur. Un package assessment ne doit pas devenir un package scolaire masqué. Un package registration-membership ne doit pas supposer qu’une inscription concerne toujours un apprenant. Si un pattern transverse ne peut plus être expliqué indépendamment d’un domaine, il faut soit le re-spécialiser, soit l’éclater en un noyau réutilisable plus propre.

Traiter la temporalité comme une propriété native du domaine

La temporalité ne doit jamais être ajoutée à la fin du projet comme une simple date de création ou de modification. Dans un système orienté connaissance, une grande partie de la vérité métier est temporelle. Un rôle est valide pendant une période donnée. Une relation peut commencer, se suspendre, être réactivée ou prendre fin. Une adresse, une classification, un accord ou un statut peuvent changer tout en devant rester historiés. Il est donc indispensable de distinguer la validité métier, la date d’effet et la date technique d’enregistrement lorsque le domaine l’exige.

Cette exigence a des conséquences directes sur la modélisation. Les entités qui portent une validité temporelle doivent l’exprimer explicitement. Les règles d’unicité doivent souvent être formulées non pas en valeur absolue, mais « à une date donnée » ou « sur une période non chevauchante ». Les opérations de mise à jour ne doivent pas écraser silencieusement l’historique lorsqu’une nouvelle occurrence datée doit en réalité être créée.

Concevoir les actions comme des intentions métier complètes

Les actions exposées par un module doivent porter des verbes métier et non des verbes purement techniques. Une action comme AssignRole a du sens parce qu’elle exprime une transformation identifiable du domaine. Une action comme SetFlagX signale généralement que le domaine n’a pas été suffisamment structuré. Cette exigence n’est pas stylistique ; elle conditionne la lisibilité de l’API, la qualité de la documentation, la traçabilité des événements et la stabilité des tests.

Pour chaque action, il faut expliciter les préconditions, les invariants préservés, les effets de bord autorisés, les événements publiés et la stratégie d’historisation associée. Si plusieurs objets sont modifiés, le document doit préciser si cela relève d’une même transaction ou d’une orchestration plus large. Cette clarté évite les effets cachés et facilite la compréhension des conséquences métier d’une opération.

Éviter les énumérations durcies lorsqu’un pattern est nécessaire

Une erreur fréquente consiste à représenter un pan entier de la sémantique métier par une chaîne de caractères ou une énumération figée. Les types de relation, les types de rôle, les schémas d’identifiant, les motifs de statut ou les classifications sont souvent traités ainsi au début d’un projet. Cette solution peut sembler efficace à court terme, mais elle devient vite limitante dès que l’on doit gérer des temporalités, des hiérarchies, des métadonnées, des droits d’usage ou des localisations par contexte.

La règle est simple : tant qu’un code reste purement classificatoire et sans comportement propre, il peut être conservé comme valeur référentielle. Dès qu’il porte des règles, des attributs ou des dépendances, il doit être élevé au rang de concept. C’est notamment le cas des rôles complexes, des relations typées avec contrainte, des schémas documentaires ou des motifs de décision.

Formaliser la réutilisation par spécialisation et non par duplication

Lorsqu’un besoin nouveau apparaît, la première question ne doit pas être « quel nouvel objet allons-nous créer ? », mais « ce besoin est-il une spécialisation d’un concept existant, une composition de patterns déjà disponibles, ou un concept réellement nouveau ? ». Cette discipline est essentielle pour construire un patrimoine logiciel et ontologique cohérent. La duplication sous un nouveau nom produit très rapidement des modèles parallèles dont les différences réelles sont minimes mais dont la maintenance devient indépendante, donc coûteuse.

La spécialisation doit toutefois rester explicite. Il ne suffit pas d’annoncer qu’un concept hérite d’un autre ; il faut préciser quels invariants sont conservés, quelles contraintes supplémentaires sont ajoutées et quels événements spécifiques apparaissent. Une spécialisation bien faite est une réduction de l’ambiguïté, non un simple mécanisme de réemploi syntaxique.