Vue d’ensemble de l’architecture¶

À quoi sert cette page ?¶

Cette page est le point de départ pour comprendre l’architecture de CMonChoix Platform.

Elle est volontairement écrite pour une personne qui découvre le projet. Il n’est pas nécessaire de connaître l’historique de CMonChoix ni son code pour commencer ici.

À la fin de cette page, vous devez comprendre :

quelles sont les grandes parties de la plateforme ;
quelle partie est responsable de quoi ;
dans quel ordre lire la documentation ;
pourquoi certaines responsabilités ne doivent jamais être mélangées ;
quelle méthode suivre avant de modifier des données ou du code de production.

Idée essentielle : CMonChoix est découpé en couches ayant chacune une responsabilité précise. Lorsqu’une couche commence à faire le travail d’une autre, le système devient difficile à comprendre, tester et maintenir.

Statut¶

Cette page est une porte d’entrée informative. Elle explique comment s’orienter dans l’architecture, mais ne remplace pas les contrats et invariants normatifs auxquels elle renvoie.

En cas de contradiction entre deux documents, les règles fondamentales et les contrats certifiés les plus récents priment sur les anciennes notes d’implémentation ou les rapports historiques.

Le système en une minute¶

CMonChoix reçoit des informations provenant de marchands. Ces informations doivent être importées, comprises, normalisées et transformées avant de pouvoir être affichées proprement sur le site.

Le chemin général est le suivant :

Sources marchandes
       ↓
Pipeline d’ingestion et de préparation
       ↓
Domain Core + modules verticaux
       ↓
Identité canonique et données normalisées
       ↓
Construction des projections
       ↓
Service d’écriture
       ↓
Stockage certifié
       ↓
Frontend / API / exports / audits

En langage simple :

les marchands fournissent des données ;
le Pipeline les récupère et les prépare ;
le Domain Core applique les concepts et décisions métier génériques ;
les modules verticaux ajoutent les règles propres à une famille de produits ;
les données sont transformées en représentations fiables appelées projections ;
les écritures sont effectuées par une voie contrôlée ;
le Frontend consomme les données préparées pour afficher le site.

Le Frontend ne doit donc pas essayer de refaire tout ce travail au moment où un visiteur ouvre une page.

Petit lexique avant d’aller plus loin¶

Domaine métier¶

Un domaine métier représente une partie de la logique fonctionnelle de CMonChoix : produit, catalogue, feed marchand, identité, etc. Il décrit ce que les données signifient et quelles règles leur sont applicables.

Domain Core¶

Le Domain Core est le noyau métier générique. Il contient les concepts et mécanismes de décision qui ne doivent dépendre ni d’un marchand précis, ni de WordPress, ni de l’affichage du site.

Vertical¶

Une verticale représente une famille de produits ayant ses propres connaissances métier, par exemple les smartphones ou la photo. Une règle spécifique aux smartphones doit rester dans la verticale smartphone plutôt que contaminer le noyau générique.

Pipeline¶

Le Pipeline est la chaîne de traitement qui fait passer les données marchandes de leur état brut vers un état exploitable : ingestion, normalisation, enrichissement et préparation.

Runtime¶

Le Runtime est la partie qui fait réellement exécuter les traitements : orchestration, planification, workers et contexte d’exécution. Il décide quand et comment lancer un traitement, mais il ne doit pas inventer de nouvelles règles métier.

Projection¶

Une projection est une représentation préparée des données destinée à un usage précis, notamment l’affichage ou la lecture rapide. Le Frontend consomme ces données préparées au lieu de reconstruire la vérité métier lui-même.

Contrat¶

Un contrat définit une frontière stable entre deux parties du système : entrées acceptées, sorties garanties, états possibles et responsabilités. Cela évite qu’une couche dépende des détails internes d’une autre.

Identité canonique¶

L’identité canonique est l’identité de référence retenue par la plateforme lorsqu’elle doit déterminer quels éléments représentent réellement le même produit ou la même entité.

Périmètre de l’architecture¶

La documentation d’architecture couvre notamment :

la vision de la plateforme ;
les principes et invariants ;
les dépendances autorisées ;
les frontières entre couches ;
la stratégie « Identifier First » ;
l’identité canonique ;
le Domain Core ;
les modules verticaux ;
les services de lecture et d’écriture ;
le Pipeline ;
le Runtime ;
les projections ;
Media Quality ;
le Frontend ;
l’infrastructure ;
la gouvernance et l’exploitation.

Ordre de lecture recommandé¶

Pour découvrir la plateforme sans connaissances préalables, lire dans cet ordre :

Il n’est pas nécessaire de mémoriser tout cela. L’objectif est d’abord de comprendre qui possède quelle responsabilité.

Hiérarchie des documents¶

Tous les documents n’ont pas la même autorité.

Invariants d’architecture
        ↓
Contrats de dépendance et de frontière
        ↓
Contrats du domaine et des services
        ↓
Documentation Runtime et exploitation
        ↓
Notes d’implémentation et historique

Une ancienne certification ou une ancienne note peut expliquer comment le système est arrivé à son état actuel. Elle ne remplace pas l’architecture consolidée actuelle.

Qui fait quoi ?¶

Domain Core — la logique générique¶

Le Domain Core possède les concepts métier génériques et les mécanismes de décision déterministes.

Il ne doit pas dépendre directement :

de WordPress ;
d’une implémentation SQL ;
des feeds marchands ;
du code Frontend ;
de l’orchestration Runtime ;
de règles propres à une verticale.

Pourquoi ? Parce que la vérité métier centrale doit rester utilisable même si l’on remplace un jour WordPress, une base de données ou une interface.

Modules verticaux — les connaissances propres aux produits¶

Les modules verticaux possèdent les règles spécifiques à une famille de produits.

Une verticale peut compléter le comportement générique à travers les contrats prévus, mais elle ne doit pas modifier le Domain Core ni dépendre directement d’une autre verticale.

Services de lecture — observer sans modifier¶

Les Read Services servent aux audits, simulations, diagnostics, comparaisons et rapports de validation.

Ils sont strictement en lecture seule.

Lancer un diagnostic ne doit jamais réparer silencieusement la production.

Services d’écriture — modifier explicitement¶

Les Write Services possèdent les écritures métier explicites, contrôlées et auditables.

Pendant une migration, un ancien mécanisme d’écriture peut encore exister derrière cette frontière. Il reste alors un détail technique temporaire et non une deuxième source de vérité.

Pipeline — préparer les données¶

Le Pipeline possède l’ingestion, la normalisation, l’enrichissement et la préparation des preuves utilisées par la plateforme.

Il ne doit pas dépendre du Frontend ni redéfinir localement une vérité métier déjà possédée par une autre couche.

Runtime — faire exécuter¶

Le Runtime possède l’orchestration, la planification, les workers et le contexte d’exécution.

Il peut lancer les cas d’usage définis par la plateforme, mais il ne doit pas inventer des règles métier simplement parce qu’elles sont pratiques à cet endroit.

Infrastructure — implémenter techniquement¶

L’Infrastructure contient les détails techniques nécessaires : bases de données, fichiers, cache, index, Docker, stockage et intégrations techniques.

Elle sert les autres couches ; elle ne définit pas la vérité métier.

Adapters — traduire les systèmes externes¶

Les Adapters adaptent les interactions avec des systèmes externes aux formats attendus par la plateforme. Ils isolent les détails propres à ces systèmes.

Frontend — afficher¶

Le Frontend consomme des projections préparées.

Il ne doit pas :

résoudre lui-même les identités ;
normaliser les feeds ;
recalculer la vérité canonique ;
écrire directement les données métier.

Si une page doit effectuer ce genre de travail pour pouvoir s’afficher, il faut rechercher quelle couche en amont n’a pas correctement rempli sa responsabilité.

Les quatre états de décision à connaître¶

Les composants qui prennent une décision doivent autant que possible retourner des états explicites plutôt qu’un simple « oui/non ».

État technique	Signification
`resolved`	Une conclusion déterministe est suffisamment prouvée.
`unknown`	Les informations sont absentes ou insuffisantes.
`ambiguous`	Plusieurs résultats restent plausibles.
`conflict`	Des preuves incompatibles empêchent une décision sûre.

Une décision importante devrait également fournir un code de raison et des informations d’audit.

Point crucial : l’absence de preuve n’est pas une preuve positive. Une information inconnue ne doit pas être transformée silencieusement en correspondance certaine.

Règle de sécurité : lire avant d’écrire¶

Toute correction importante doit suivre cette séquence :

Audit
  ↓
Simulation
  ↓
Comparaison
  ↓
Validation
  ↓
Écriture explicite
  ↓
Vérification après écriture

Cette discipline s’applique notamment :

aux reconstructions de projections ;
aux corrections d’identité ;
aux changements de gouvernance ;
aux opérations Media Quality.

Exemple simple¶

Si une image produit semble incorrecte, la première action ne doit pas être de remplacer ou supprimer l’image en base.

On commence par établir ce que le système voit, quelle image il considère comme actuelle, quelles preuves sont disponibles et quel remplacement serait justifié. L’écriture ne vient qu’après validation.

Media Quality¶

Media Quality est un mécanisme d’évaluation des preuves concernant les médias. Ce n’est pas une procédure de nettoyage destructif automatique.

Son comportement normal est d’abord d’auditer :

examiner l’image principale actuelle ;
la comparer aux informations produit normalisées ;
produire un état stable et un code de raison ;
proposer un remplacement lorsqu’il est réellement démontré ;
ne modifier les données que par une voie d’écriture explicite et certifiée.

L’absence de bonne image de remplacement n’autorise jamais à supprimer arbitrairement l’image existante.

Voir Media Quality Engine.

Déterminisme et reproductibilité¶

À entrées validées et configuration identiques, la plateforme doit autant que possible produire les mêmes décisions métier et les mêmes projections.

Un composant critique doit donc rendre explicites :

la version des entrées ;
la version des règles ou du contrat ;
l’état du résultat ;
les codes de raison ;
les métadonnées d’exécution ;
le périmètre d’écriture lorsqu’une modification a lieu.

L’heure, l’état du réseau ou l’ordre dans lequel les marchands sont traités ne doivent pas modifier silencieusement une décision canonique, sauf si ces éléments font explicitement partie des entrées de la décision.

Comment CMonChoix évolue sans tout casser¶

La plateforme est migrée progressivement.

La méthode actuelle est :

identifier une responsabilité existante ;
définir ou certifier sa frontière ;
introduire un contrat ou service canonique ;
conserver temporairement une compatibilité avec l’ancien système si nécessaire ;
déplacer progressivement les consommateurs vers la nouvelle voie ;
supprimer l’ancien code uniquement après vérification Runtime et certification.

Le code de compatibilité est donc temporaire. Il ne doit jamais devenir une seconde implémentation métier concurrente.

Avant de modifier l’architecture¶

Avant toute modification importante, vérifier que :

la couche propriétaire de la responsabilité est clairement identifiée ;
le sens des dépendances reste autorisé ;
les connaissances génériques et verticales restent séparées ;
lecture et écriture ne sont pas mélangées ;
les états de résultat restent déterministes et auditables ;
toute mutation de production est explicite ;
les points d’entrée Runtime utilisent les services certifiés ;
documentation et tests évoluent ensemble ;
une compatibilité temporaire ne devient pas une implémentation parallèle permanente.

Si vous ne savez pas quelle couche doit recevoir une modification, ne choisissez pas au hasard le fichier le plus facile à modifier. Commencez par retrouver la responsabilité dans cette documentation.

Pour la personne qui reprend le projet¶

Vous n’avez pas besoin de comprendre tout CMonChoix dès le premier jour.

Pour intervenir sans risque :

identifier le symptôme ou le besoin ;
retrouver la couche responsable dans cette page ;
lire la documentation de cette couche ;
rechercher le contrat ou l’invariant correspondant ;
commencer par une observation ou un audit ;
ne modifier la production qu’après avoir compris le chemin complet de la donnée ;
vérifier le résultat après toute écriture.

Une commande qui « fonctionne » n’est pas suffisante pour conclure qu’une intervention est correcte. Il faut aussi comprendre ce qu’elle lit, ce qu’elle modifie et quelle source de vérité elle utilise.

Documents liés¶

ADR liés¶

Aucun actuellement.

Évolution future¶

Cette vue d’ensemble peut évoluer si un nouveau document devient un point d’entrée normatif. Toute évolution doit préserver les règles de dépendance, la discipline « lire avant d’écrire » et le principe d’une source de vérité unique.