Principes d'architecture¶

Les principes d'architecture sont les règles qui guident les choix de conception, de développement, de migration et d'exploitation de CMonChoix Platform.

Statut¶

Document normatif d'architecture.

À quoi sert cette page ?¶

Quand plusieurs solutions semblent possibles, cette page aide à choisir celle qui respecte le mieux l'architecture de CMonChoix.

Elle sert notamment à décider :

où placer une nouvelle règle métier ;
si une dépendance est acceptable ;
si un audit peut écrire ;
comment faire évoluer le Pipeline ou le Runtime ;
comment remplacer progressivement du code historique ;
comment vérifier qu'une nouvelle implémentation ne contourne pas les frontières existantes.

Pour une personne qui reprend le projet, ces principes sont importants car ils permettent de raisonner même sans connaître tous les fichiers.

1. Une responsabilité principale par composant¶

Chaque composant doit avoir une mission claire.

Par exemple :

le Domain Core porte les concepts métier génériques ;
les Vertical Modules portent les connaissances propres aux familles de produits ;
les Contracts définissent les formes d'échange stables 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 déjà préparées.

Pourquoi ?¶

Si plusieurs couches font le même travail, la plateforme finit par posséder plusieurs vérités concurrentes.

Signal d'alerte¶

Si une correction oblige à ajouter la même règle dans plusieurs endroits, il faut probablement rechercher un propriétaire unique plutôt que dupliquer le comportement.

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

Chaque information métier importante possède un propriétaire autoritatif unique.

Information	Propriétaire attendu
Identité canonique	Domain Core / résolution d'identité
Résultat de résolution	Resolver et son contrat
Score qualité	Quality Scorer
Promotion	domaine Promotion
État de santé	service Health
Projection	Projection Builder + Write Service certifié
État de conflit	Conflict Policy

Une copie technique peut exister pour accélérer une lecture ou un affichage. Elle reste une copie dérivée et doit pouvoir être reconstruite.

Exemple¶

Si WordPress stocke une projection produit pour l'affichage, cela ne signifie pas que WordPress devient propriétaire de l'identité du produit.

3. Les dépendances vont vers les couches fondamentales¶

Une couche générique ne doit pas dépendre d'une couche plus spécialisée.

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

En langage simple¶

Le cœur métier ne doit pas connaître l'interface ou la technologie qui l'utilise.

Le détail complet se trouve dans Dépendances d'architecture.

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

Le Domain Core ne contient pas de règle propre :

à un marchand ;
à un feed précis ;
à WordPress ;
à une famille produit comme Smartphone ou Photo ;
à une interface utilisateur.

Une règle locale ne devient générique qu'après avoir démontré qu'elle s'applique réellement à plusieurs contextes.

5. Une décision importante doit être explicable¶

Une décision métier ou qualité doit exposer ce qui a permis de la prendre.

Selon le contrat, un résultat doit pouvoir fournir :

un statut ;
un code de raison ;
les preuves ou signaux utilisés ;
les conflits détectés ;
la version des règles ou du moteur.

Pourquoi ?¶

Sans cela, un résultat incorrect devient très difficile à diagnostiquer.

Une décision que l'on ne peut pas expliquer ou reproduire n'est pas considérée comme industrialisée.

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

Avec les mêmes entrées, la même configuration et la même version de règles, un composant doit produire le même résultat.

Cela s'applique notamment à :

la normalisation ;
la construction des candidats ;
la résolution d'identité ;
le scoring ;
la détection des conflits ;
les projections ;
les audits Media Quality.

Pourquoi ?¶

Si le même produit peut produire deux résultats différents sans changement explicite, il devient presque impossible de comprendre une régression.

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 en lecture seule.

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

Règle pratique¶

Si une commande de diagnostic modifie les données qu'elle est censée observer, il faut considérer cela comme un défaut d'architecture.

8. Media Quality commence par l'audit¶

Media Quality sert d'abord à comprendre la cohérence entre une image 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.

Une correction automatique doit être séparée du moteur d'audit et exécutée par une voie d'écriture explicite.

9. Les conflits ne sont jamais masqués¶

Les états canoniques importants incluent :

resolved ;
unknown ;
ambiguous ;
conflict.

Une absence de preuve ne doit jamais être transformée en résultat certain pour « faire fonctionner » le système.

Exemple¶

Si deux preuves indiquent des modèles incompatibles, il vaut mieux produire conflict que choisir arbitrairement le modèle qui a le meilleur score.

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 ;
les Adapters traduisent les interactions avec l'extérieur.

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

11. Les migrations sont progressives¶

CMonChoix évolue de manière incrémentale.

Le code historique — souvent appelé legacy — reste disponible tant que son remplacement n'est pas certifié.

Des wrappers ou shims peuvent être conservés temporairement s'ils :

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

À retenir¶

On ne supprime pas un ancien chemin uniquement parce qu'un nouveau fichier existe. Il faut d'abord prouver que le runtime n'en dépend plus.

12. Toute évolution importante doit être reproductible¶

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

Selon son niveau de risque, elle doit disposer de :

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

Un contrôle visuel ponctuel ne constitue pas à lui seul une certification.

13. L'observabilité fait partie du fonctionnement correct¶

Les composants importants doivent exposer des métriques compréhensibles.

On doit pouvoir distinguer, selon le cas :

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

Une métrique doit être compréhensible sans devoir relire toute l'implémentation PHP.

14. La documentation suit le comportement réel¶

La documentation doit distinguer clairement :

ce qui est actif aujourd'hui ;
ce qui n'est qu'une cible ;
ce qui existe seulement pour compatibilité ;
ce qui est historique ;
ce qui constitue une dette connue.

Une capacité dormante ne doit pas être présentée comme active simplement parce que son code existe encore.

La documentation et les tests doivent évoluer avec le code dans le même chantier.

Ce que ces principes interdisent concrètement¶

Ils interdisent notamment :

d'ajouter une règle métier dans le Frontend ;
de mettre 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 avec une valeur par défaut ;
d'activer une mutation Media Quality implicite ;
d'introduire une dépendance circulaire ;
de contourner un Write Service avec un accès SQL opportuniste.

Comment vérifier une modification¶

Avant de considérer une évolution comme correcte, vérifier :

que sa responsabilité est placée dans la bonne couche ;
que ses dépendances sont autorisées ;
que ses entrées et sorties sont explicites ;
que son résultat est reproductible ;
que ses décisions peuvent être expliquées ;
que lecture et écriture sont séparées ;
que les conflits restent visibles ;
que métriques et tests permettent de vérifier le comportement ;
que la documentation correspond réellement au code exécuté.

Pour une personne qui reprend le projet¶

Quand vous ne savez pas si une modification est bien conçue, posez-vous ces quatre questions :

Qui est propriétaire de cette responsabilité ?
Est-ce que je lis ou est-ce que j'écris ?
Est-ce que je crée une deuxième source de vérité ?
Pourrai-je expliquer et vérifier le résultat après coup ?

Si l'une de ces réponses reste floue, il vaut mieux poursuivre le diagnostic avant de modifier le code.

Documents associés¶

Évolution future¶

De nouveaux principes peuvent être ajoutés s'ils protègent une propriété durable de la plateforme et restent compatibles avec la Foundation, les invariants et le contrat de dépendances existants.