Frontières de l'architecture¶

Cette page répond à une question essentielle : quelle couche possède quelle responsabilité, et qu'est-ce qui a le droit de traverser cette frontière ?

Statut¶

Contrat normatif de frontière d'architecture.

Pourquoi parler de frontières ?¶

Dans un projet qui grandit, les problèmes apparaissent souvent lorsque les responsabilités deviennent floues.

Un exemple classique serait un composant Frontend qui commence à corriger une identité produit « juste pour l'affichage ». La correction peut sembler locale, mais elle crée une nouvelle vérité métier différente de celle du moteur responsable de l'identité.

Les frontières servent à empêcher ce type de dérive.

Elles protègent notamment contre :

les dépendances circulaires ;
les couplages cachés ;
les détails techniques qui remontent dans le métier ;
les écritures accidentelles ;
les vérités métier dupliquées.

Principe central¶

Chaque responsabilité importante possède un propriétaire.

Un composant ne traverse une frontière que par un mécanisme explicite et documenté : Contract, port, service ou autre interface prévue à cet effet.

Le fait que deux fichiers soient proches, qu'un ancien appel existe déjà ou qu'une solution soit rapide à coder n'autorise pas une nouvelle dépendance.

Carte des responsabilités¶

Couche	Responsabilité principale
Domain Core	Concepts métier génériques et décisions déterministes
Contracts	Formes stables d'entrée, sortie, statut et collaboration
Knowledge	Connaissances métier et référentiels réutilisables
Application	Orchestration des cas d'usage
Infrastructure	Implémentations techniques et persistance
Adapters	Traduction entre systèmes externes et contrats de la plateforme
Apps	Points d'entrée exécutables : CLI, HTTP, worker, cron
Runtime	Orchestration opérationnelle et exécution
Vertical Modules	Règles spécifiques aux familles de produits
Read Services	Audits, simulations, comparaisons, previews et rapports
Write Services	Mutations métier explicites et contrôlées
Pipeline	Transformation et enrichissement des données
Projection	Représentations dérivées destinées aux consommateurs
Frontend	Présentation des projections
Media Quality	Évaluation des preuves liées aux médias

Une frontière logique n'est pas forcément un dossier¶

Ces frontières décrivent les responsabilités du système.

Elles ne signifient pas nécessairement :

un conteneur Docker par couche ;
un serveur par couche ;
un dossier unique par responsabilité.

Pendant une migration, certains fichiers historiques peuvent encore être situés ailleurs. Ce qui compte est de savoir quelle responsabilité ils exercent réellement et vers quelle frontière canonique ils doivent converger.

Frontière du Domain Core¶

Le Domain Core possède le raisonnement métier générique.

Il ne possède jamais :

l'intégration WordPress ;
les détails SQL ou de stockage ;
l'exécution HTTP, CLI, cron ou worker ;
le parsing d'un feed marchand ;
le rendu Frontend ;
l'orchestration Runtime ;
les exceptions d'un marchand précis ;
les règles propres à une famille produit.

Si une règle est spécifique aux smartphones, appareils photo, TV ou gaming, elle doit rester hors du Domain Core tant qu'il n'est pas démontré qu'elle est réellement générique.

Frontière des Contracts¶

Les Contracts définissent la manière stable dont les couches collaborent.

Ils peuvent contenir :

DTO ;
interfaces ;
statuts normalisés ;
codes de raison ;
structures de preuve ;
règles de compatibilité ;
formes de résultats versionnées.

Ils ne contiennent pas :

SQL ;
appels WordPress ;
adapter concret ;
orchestration Runtime ;
grosse logique métier ;
comportement Frontend.

Un wrapper de compatibilité peut conserver temporairement un ancien nom, mais le Contract canonique doit rester indépendant de l'implémentation.

Frontière des Vertical Modules¶

Une verticale interprète les preuves propres à sa famille de produits.

Elle peut notamment définir :

attributs spécifiques ;
normalisation locale ;
preuves permettant de construire des candidats ;
règles de conflit ;
signaux de scoring ;
codes de raison ;
garde-fous propres à la famille.

Elle ne doit jamais :

dépendre d'une autre verticale ;
écrire directement en production ;
contourner le Resolver ;
redéfinir les statuts canoniques ;
devenir propriétaire des projections globales ;
contenir de logique Frontend.

Frontière entre lecture et écriture¶

C'est l'une des frontières les plus importantes pour exploiter CMonChoix sans risque.

Read Services¶

Ils servent à observer : audit, simulation, comparaison, prévisualisation, explication et rapport.

Ils ne doivent jamais provoquer :

INSERT ;
UPDATE ;
DELETE ;
mutation implicite d'état ;
écriture Runtime.

Write Services¶

Ils sont la voie prévue pour modifier les données métier.

Chaque écriture doit être :

explicite ;
autorisée ;
auditable ;
mesurable ;
bornée à un périmètre connu ;
réversible ou récupérable lorsque c'est possible.

Un audit ne devient donc pas automatiquement une écriture parce que son niveau de confiance est élevé.

Frontière des projections¶

Une projection transforme une vérité métier déjà approuvée en représentation destinée à un consommateur.

Elle peut :

sélectionner des données ;
agréger ;
reformater ;
exposer une vue adaptée à un besoin.

Elle ne doit pas :

résoudre l'identité ;
masquer unknown, ambiguous ou conflict ;
créer une nouvelle identité ;
recalculer une politique verticale ;
écrire directement en persistance sans frontière Write Service.

Le Frontend consomme ensuite cette projection au lieu de repartir des feeds bruts ou des internes du Domain.

Frontière du Runtime¶

Le Runtime organise l'exécution.

Il peut :

planifier ;
invoquer ;
retry ;
monitorer ;
coordonner des services approuvés.

Il ne doit pas :

inventer une règle métier ;
changer le sens d'un statut canonique ;
contourner les Contracts ;
appeler directement un writer SQL legacy lorsqu'un Write Service existe ;
transformer implicitement un moteur d'audit en moteur de mutation.

Les résultats Runtime doivent rester observables à travers des compteurs, états structurés et erreurs stables.

Frontière de Media Quality¶

Media Quality commence par l'audit.

Son rôle est d'évaluer les preuves concernant les médias et de produire un résultat déterministe, par exemple :

matched ;
mismatched ;
unknown ;
ambiguous ;
not_applicable.

Une règle Media Quality peut détecter qu'une image semble mauvaise ou qu'un meilleur candidat existe. Elle ne doit pas remplacer ou supprimer silencieusement l'image en production.

La correction, si elle est validée, passe par une frontière d'écriture explicite.

Frontière du Frontend¶

Le Frontend consomme les projections préparées.

Il ne doit pas dépendre directement :

des feeds ;
de Candidate ;
du Resolver ;
de Conflict Policy ;
de logique brute de matching ;
des moteurs de normalisation ;
du Runtime ;
des Write Services ;
des tables marchandes de persistance.

Un fallback de présentation peut améliorer la lisibilité. Il ne doit jamais fabriquer une vérité absente ou masquer un état métier non résolu.

Le test des neuf questions¶

Avant d'introduire ou déplacer du code, répondre à ces questions :

Quelle couche possède cette responsabilité ?
La direction de dépendance est-elle autorisée ?
Existe-t-il déjà un Contract pour cette collaboration ?
Le changement mélange-t-il lecture et écriture ?
Introduit-il un détail technique dans le Domain ou Knowledge ?
Duplique-t-il une vérité métier existante ?
Les états unknown, ambiguous et conflict restent-ils explicites ?
Le comportement est-il déterministe et observable ?
Peut-on obtenir le même résultat avec une frontière plus étroite ?

Si la responsabilité reste floue, le design n'est pas prêt.

Exemple concret : une mauvaise image produit¶

Supposons qu'une page affiche une mauvaise image.

Une mauvaise correction serait :

Frontend
   ↓
Détecte que l'image semble mauvaise
   ↓
Écrit directement une nouvelle URL en base

Cette solution mélange présentation, décision qualité et écriture.

La voie attendue ressemble plutôt à :

Media Quality / Read path
   ↓
Audit et preuves
   ↓
Décision explicable
   ↓
Validation
   ↓
Write Service
   ↓
Persistance
   ↓
Projection mise à jour
   ↓
Frontend

Cette séparation peut sembler plus longue, mais elle permet de savoir qui a décidé, pourquoi, quel périmètre a été modifié et comment revenir en arrière.

Comment faire respecter les frontières¶

Ces règles doivent être protégées par :

contrôles de namespaces et imports ;
tests d'architecture ;
garde-fous SQL read-only ;
tests de Contracts ;
fixtures déterministes ;
audits CLI ;
tests d'intégration des projections et écritures ;
checklists de revue ;
exceptions documentées avec propriétaire et plan de suppression.

Une exception legacy reste une dette transitoire, pas un précédent architectural.

Pratiques interdites¶

Sont notamment interdites :

Domain Core dépendant de WordPress, SQL, Runtime, Frontend ou d'une verticale ;
verticale dépendant d'une autre verticale ;
Read Service écrivant des données ;
Frontend résolvant une identité ou recalculant la qualité ;
Adapter décidant d'une vérité métier ;
Runtime contournant Application ou Write Services ;
projection masquant des conflits ;
Contract important des namespaces d'implémentation ;
moteur d'audit modifiant implicitement la production ;
plusieurs writers canoniques concurrents pour le même champ.

Pour une personne qui reprend CMonChoix¶

Quand vous trouvez du code difficile à classer, ne commencez pas par demander « dans quel dossier le mettre ? ».

Commencez par demander :

quelle responsabilité exerce-t-il ?
qui possède cette responsabilité aujourd'hui ?
lit-il ou écrit-il ?
prend-il une décision métier ou traduit-il simplement un résultat ?
dépend-il d'une couche plus spécialisée que lui ?

Le bon emplacement découle ensuite beaucoup plus naturellement de ces réponses.

Documents associés¶

ADR liés¶

Aucun actuellement.

Évolution future¶

Une nouvelle couche ou une exception ne peut être introduite que si sa responsabilité, sa direction de dépendance, son observabilité, sa stratégie de migration et son impact de compatibilité sont explicitement documentés et testés.