7. Cartographier le système utile
Pourquoi ce chapitre existe
Face à un système inconnu, deux erreurs sont fréquentes. La première est de ne rien cartographier : on suit le flux apparent jusqu'à ce que l'on découvre une dépendance après la mise en production. La seconde est de tenter de représenter toute l'architecture : le diagramme devient illisible avant d'être terminé et n'aide aucune décision concrète.
Une cartographie utile n'est pas une représentation exhaustive du patrimoine. C'est un modèle temporaire, construit pour répondre à une question de changement. Son périmètre est gouverné par le risque que nous cherchons à évaluer.
Les idées essentielles
- Une carte a une question et un lecteur ; sans cela, elle devient une décoration ou une dette documentaire.
- Les flux de données, les frontières de responsabilité et les modes de défaillance sont plus instructifs que la seule liste des composants.
- Les dépendances humaines — équipe, compétence, accord de déploiement — peuvent être aussi limitantes que les dépendances techniques.
- Une carte doit déclarer ses zones inconnues ; une précision imaginaire est plus dangereuse qu'un trou visible.
Cartographier par scénarios
La bonne unité de cartographie est souvent un scénario : « une commande est confirmée », « un client supprime son compte », « un partenaire envoie un événement en retard », « une personne d'astreinte diagnostique une hausse d'erreurs ». Partir d'un scénario permet de suivre ce qui circule — demande, donnée, événement, autorisation, décision — et d'identifier les frontières traversées.
Un diagramme de composants répond à la question « qu'existe-t-il ? ». Un scénario répond à « que dépend de quoi lorsque ce comportement doit être vrai ? ». Les deux sont nécessaires, mais le second est généralement plus utile pour préparer un changement.
Cette représentation n'est pas encore suffisante. Pour un changement de règle de disponibilité, il faut annoter ce que le diagramme ne montre pas : la donnée est-elle répliquée ? quelle est sa fraîcheur ? l'événement peut-il être livré deux fois ? quelle équipe possède la règle ? que se passe-t-il si la facturation échoue après la confirmation ? Le niveau de détail est dicté par les conséquences de ces réponses.
Les quatre cartes qui révèlent le plus de risques
| Carte | Ce qu'elle rend visible | Quand l'utiliser |
|---|---|---|
| Flux de comportement | Étapes, effets de bord et dépendances enchaînées | Une modification traverse plusieurs composants |
| Flux de données | Création, transformation, stockage, rétention et consommateurs | Une donnée change de sens, de format ou de cycle de vie |
| Frontières de responsabilité | Équipes, contrats, droits de décision et astreinte | Le changement exige une coordination ou une escalade |
| Modes de défaillance | Dépendances lentes, indisponibles, incohérentes ou en retard | Une erreur partielle peut créer un dommage ou un état difficile à réparer |
Une même décision ne réclame pas les quatre cartes au même degré. Une modification de libellé peut ne nécessiter qu'un parcours utilisateur ; une suppression de donnée personnelle doit considérer flux de données, contrats, responsabilités et modes de reprise.
Inclure le temps et l'historique
Les cartes synchrones donnent une illusion trompeuse. Dans les systèmes distribués, l'ordre, le délai et la répétition font partie du comportement. Un événement peut arriver avant un autre, être livré plusieurs fois ou ne jamais être consommé. Une migration peut coexister plusieurs jours avec deux versions de l'application. Une donnée peut avoir été produite sous une règle qui n'existe plus.
Pour chaque frontière critique, il faut donc poser des questions temporelles : qui écrit en premier ? quelle version peut lire quelle forme de données ? combien de temps une incohérence est-elle acceptable ? comment une reprise est-elle distinguée d'une nouvelle action ? Ces questions sont souvent absentes du code local, alors qu'elles déterminent la sécurité du changement.
Un diagramme qui ne porte ni date, ni question, ni propriétaire est facile à croire et difficile à corriger. Préférez une carte modeste, liée à un scénario et révisée lors d'un changement, à une « architecture cible » que personne ne confronte au réel.
Cartographier les décisions et pas seulement les flux
Un flux répond à la question « que se passe-t-il ? ». Pour préparer un changement, il faut aussi savoir « qui décide quoi ? ». Une demande de remboursement peut passer par un API, un moteur de règles, un prestataire et une base de données. Le chemin reste incomplet si l'on ignore qui détermine l'éligibilité, qui peut déroger à une règle, quelle donnée tranche un conflit et qui décide de la communication utilisateur en cas d'échec.
Annoter les décisions transforme la carte en outil de responsabilité. Elle révèle les décisions dupliquées — deux services interprètent le même statut — et les décisions orphelines — tout le monde lit une donnée mais personne n'est autorisé à définir son sens. Elle indique également quels interlocuteurs doivent être associés à la revue, non parce qu'ils possèdent un composant, mais parce qu'ils possèdent le contexte d'une conséquence.
| Décision | Information d'entrée | Autorité | Effet produit | Question de risque |
|---|---|---|---|---|
| Remboursement autorisé | Paiement, date, raison, contrat | Domaine Facturation | Écriture, événement, communication | Que se passe-t-il si le partenaire est indisponible ? |
| Accès administrateur | Rôle, organisation, délégation | Domaine Identité | Jeton ou refus | Quel audit explique cette autorisation ? |
| Prix appliqué | Offre, contrat, devise, date d'effet | Domaine Tarification | Montant figé | Quelle règle s'applique aux commandes historiques ? |
Utiliser une carte pour décider ce qui ne doit pas être couplé
La carte rend visible une distinction essentielle : un composant peut avoir besoin du résultat d'une décision sans avoir besoin de toutes ses données ni de sa logique. Le portail client a besoin de savoir qu'un remboursement est en cours ; il n'a pas besoin de connaître la règle détaillée de calcul ni d'accéder à la table de paiement. Cette différence indique une frontière de contrat et réduit le nombre de lecteurs qui doivent être mis à jour lors de la prochaine évolution.
Exemple filé — Cartographier une notification qui n'est pas un détail
Une équipe modifie le texte d'une notification de renouvellement. La carte de scénario révèle qu'elle est produite à partir d'un événement qui déclenche aussi un export de conformité et un calcul de commission. Le texte est sans risque ; l'événement est une frontière partagée. La modification prévue inclut finalement une séparation entre le contenu de communication, détenu par le produit, et le fait de renouvellement, détenu par le domaine Abonnement. La carte a évité que la personnalisation d'un message modifie par accident un contrat dont elle n'avait pas besoin.
Anti-patterns
Dessiner des boîtes sans écrire les relations
Une boîte « service de paiement » reliée à une boîte « commandes » ne dit rien sur le contrat, la direction de dépendance, la donnée partagée, le mode de défaillance ou la responsabilité. Les flèches et leurs annotations portent l'information qui permet de raisonner.
Limiter la carte aux services possédés par l'équipe
Les systèmes qui cassent un changement sont souvent juste au-delà de la frontière d'équipe : client mobile, entrepôt de données, outil de support, fournisseur SaaS, script manuel. Une carte orientée risque suit l'effet, même lorsqu'il traverse une responsabilité différente.
Confondre la carte souhaitée et la carte actuelle
Une architecture cible est utile pour orienter l'évolution. Elle ne doit jamais masquer les adaptateurs, duplications et exceptions qui existent encore. Un plan de changement commence par la réalité, y compris lorsqu'elle est inconfortable.
Bonnes pratiques
Annoter les contrats et les propriétés, pas seulement les noms
Sur les relations qui comptent, préciser l'information transmise, l'auteur de la vérité, les garanties d'ordre ou d'idempotence, les délais attendus et le propriétaire du contrat. Cette discipline met en évidence les questions auxquelles le système n'a pas encore de réponse.
Faire de la carte un artefact de travail
Une carte liée à une décision, une revue ou un incident sera tenue à jour parce qu'elle sert. Elle peut vivre à côté du code, dans un ADR ou dans la documentation du service. Son succès ne se mesure pas à son esthétique ; il se mesure à sa capacité à réduire une surprise lors du prochain changement.
Checklist — Une carte est-elle suffisante pour décider ?
- La question de changement et le scénario de référence sont-ils indiqués ?
- Les flux de données, d'événements ou d'autorisations pertinents sont-ils représentés ?
- Les contrats fragiles, dépendances externes et responsabilités d'équipe sont-ils visibles ?
- Les délais, répétitions, versions ou données historiques qui comptent sont-ils nommés ?
- Les inconnues sont-elles explicitement distinguées des faits établis ?
- La carte permet-elle d'identifier ce qui doit être testé, observé ou coordonné ?
À retenir
Une bonne carte ne prétend pas contenir le système. Elle contient juste assez de réalité pour éclairer une décision. Elle suit les comportements, les données, le temps et les responsabilités qui donnent à un changement son véritable rayon d'action.