Architecture Principles¶

Les principes d’architecture définissent les règles normatives qui guident chaque décision de conception, d’implémentation, de migration et d’exploitation de CMonChoix Platform.

Status¶

Normative Architecture Principles

Purpose¶

Ce document formalise les principes communs à l’ensemble de la Platform.

Ils servent de référence pour :

concevoir une nouvelle capacité métier ;
modifier le Pipeline ou le Runtime ;
introduire un Read Service ou un Write Service ;
faire évoluer une projection ;
arbitrer une dette legacy ;
vérifier qu’une implémentation respecte les frontières documentées.

Scope¶

Ces principes s’appliquent à tous les composants :

Foundation ;
Domain Core ;
Contracts ;
Vertical Modules ;
Read Services ;
Write Services ;
Pipeline ;
Runtime ;
Infrastructure ;
Adapters ;
Frontend ;
Documentation.

1. Une responsabilité principale par composant¶

Chaque composant possède une responsabilité claire et vérifiable.

Exemples :

le Domain Core porte les concepts métier génériques ;
les Vertical Modules portent la connaissance métier locale ;
les Contracts stabilisent les échanges entre couches ;
le Pipeline transforme les données entrantes ;
les Read Services observent, auditent et simulent ;
les Write Services appliquent les mutations validées ;
le Runtime orchestre l’exécution ;
le Frontend consomme des projections préparées.

Une couche ne doit jamais absorber progressivement le rôle d’une autre.

2. Une seule source de vérité métier¶

Chaque information métier importante possède une source autoritative unique.

Information	Source autoritative
Canonical Identity	Domain Core
Résultat de résolution	Resolver / contrat de résolution
Quality Score	Quality Scorer
Promotion	domaine Promotion
Health	service Health
Projection	Projection Builder + Write Service certifié
État de conflit	Conflict Policy

Une copie technique peut exister pour des besoins de lecture ou de performance, mais elle doit rester dérivée, reconstruisible et non autoritative.

3. Dépendances orientées vers les couches fondamentales¶

Une dépendance pointe vers une couche plus fondamentale ou vers un contrat explicitement autorisé.

Une couche générique ne dépend jamais d’une couche spécialisée.

Frontend / Apps / Runtime / Pipeline
                │
                ▼
Application / Read Services / Write Services
                │
                ▼
Vertical Modules / Knowledge / Contracts
                │
                ▼
Domain Core

Les dépendances circulaires et les imports transverses implicites sont interdits.

Le contrat détaillé est défini dans Architecture Dependencies.

4. Le Domain Core reste générique¶

Le Domain Core ne contient aucune règle propre à une famille produit, un marchand, un feed ou une interface.

Une nouvelle verticale doit étendre la Platform sans modifier le cœur générique.

Une règle locale ne devient générique qu’après preuve de réutilisation sur plusieurs contextes et validation explicite de son extraction.

5. Les décisions reposent sur des preuves¶

Une décision métier ou qualité doit exposer les éléments permettant de l’expliquer.

Un résultat important doit, selon son contrat, fournir :

un statut stable ;
un code de raison ;
les signaux ou preuves utilisés ;
les conflits détectés ;
une version de règle ou de moteur lorsque nécessaire.

Une décision opaque, impossible à reproduire ou à auditer n’est pas considérée comme industrialisée.

6. Le déterminisme est la règle¶

À entrées, configuration et version identiques, un composant doit produire le même résultat.

Ce principe s’applique notamment :

à la normalisation ;
à la construction des candidats ;
à la résolution ;
au scoring ;
à la détection des conflits ;
aux projections ;
aux audits Media Quality.

Le temps courant, l’ordre non garanti des données, les appels externes non figés ou les états implicites ne doivent pas modifier silencieusement le résultat.

7. Lire, auditer et simuler avant d’écrire¶

Toute mutation significative commence par une phase de lecture.

Observation
    ↓
Audit
    ↓
Simulation
    ↓
Comparaison avant / après
    ↓
Validation
    ↓
Écriture explicite

Les Read Services restent strictement read-only.

Les écritures passent par des Write Services explicites, auditables et réversibles lorsque le contexte le permet.

8. Media Quality est audit-first¶

Le moteur Media Quality observe la cohérence entre les médias et les informations produit.

Par défaut, il :

classe les cas ;
produit des preuves ;
expose des métriques ;
ne modifie aucune donnée métier ;
ne supprime aucune image ;
ne remplace aucune URL.

Toute correction automatique doit être séparée du moteur d’audit, activée explicitement et exécutée par une frontière d’écriture certifiée.

9. Les conflits ne sont jamais masqués¶

Un conflit réel doit être représenté par un état explicite.

Les états canoniques sont :

resolved ;
unknown ;
ambiguous ;
conflict.

Une absence de preuve ne doit pas être transformée en résolution positive.

Un conflit de marque, de famille produit, de modèle ou de variante bloquante ne doit jamais être dissimulé par un score moyen ou une heuristique permissive.

10. Lecture et écriture restent séparées¶

Une opération ne doit pas mélanger silencieusement diagnostic et mutation.

les Read Services mesurent et expliquent ;
les Write Services appliquent une intention validée ;
le Runtime orchestre sans contourner ces frontières ;
les Adapters traduisent les interactions externes sans créer de vérité métier.

Les accès SQL directs ne doivent pas devenir une API métier implicite.

11. Les migrations sont progressives¶

La Platform évolue de manière incrémentale.

Le legacy reste disponible tant que le remplacement n’est pas certifié.

Les wrappers et shims sont acceptables lorsqu’ils :

préservent une compatibilité nécessaire ;
restent minces ;
ne créent pas de nouvelle logique métier ;
sont documentés comme dette transitoire ;
possèdent une trajectoire de réduction ou de suppression.

Une réécriture globale sans preuve préalable est contraire à ce principe.

12. Toute évolution est reproductible¶

Une évolution industrialisée doit pouvoir être rejouée et vérifiée.

Elle doit disposer, selon son risque, de :

jeux de données ou échantillons identifiés ;
commandes documentées ;
métriques avant / après ;
tests automatiques ;
logs structurés ;
procédure de rollback ;
version de configuration ou de règles.

Une validation manuelle ponctuelle ne constitue pas à elle seule une certification.

13. L’observabilité fait partie du contrat¶

Les composants importants exposent des métriques compréhensibles.

Les compteurs doivent notamment permettre de distinguer :

éléments parcourus ;
éléments éligibles ;
éléments évalués ;
éléments résolus ;
cas inconnus ;
cas ambigus ;
conflits ;
erreurs techniques ;
écritures demandées et réellement appliquées.

Les métriques doivent être stables, nommées et interprétables sans lire le code source.

14. La documentation suit le comportement réel¶

La documentation normative décrit le fonctionnement actuel ou la cible explicitement identifiée.

Elle doit distinguer clairement :

comportement actif ;
compatibilité legacy ;
dette connue ;
évolution prévue ;
règle normative.

Une documentation obsolète ou contradictoire constitue une dette d’architecture.

Conséquences architecturales¶

Ces principes interdisent notamment :

d’ajouter une règle métier dans le Frontend ;
d’introduire une règle Smartphone ou Photo dans le Domain Core ;
de recalculer une vérité déjà disponible dans une couche consommatrice ;
de faire écrire un Read Service ;
de faire décider un Adapter ;
de modifier une projection directement depuis une règle métier ;
de masquer un conflit par une valeur par défaut ;
d’activer une mutation Media Quality implicite ;
d’introduire une dépendance circulaire ;
de contourner un Write Service par un accès SQL opportuniste.

Critères de conformité¶

Une évolution est conforme lorsque :

sa responsabilité est placée dans la bonne couche ;
ses dépendances respectent le contrat d’architecture ;
ses entrées et sorties sont explicites ;
son résultat est déterministe ;
les décisions sont explicables ;
les lectures et écritures sont séparées ;
les conflits restent visibles ;
les métriques et tests permettent de vérifier son comportement ;
la documentation correspond au code réellement exécuté.

None currently.

Future Evolution¶

De nouveaux principes peuvent être ajoutés uniquement s’ils restent compatibles avec la Platform Foundation, les invariants existants et le contrat de dépendances.