Nos diagrammes d'architecture étaient parfaits. Puis un rapport de bug est arrivé, et on a réalisé que personne ne comprenait vraiment comment un utilisateur se déplaçait dans le système. Voici comment on a corrigé ça.

Documenter les flux utilisateurs dans votre architecture logicielle

Le rapport de bug semblait simple : "Le checkout échoue de manière intermittente."

On avait de beaux diagrammes d'architecture. Des diagrammes C4 montrant chaque service, chaque base de données, chaque intégration. Mais quand on a essayé de tracer le parcours d'un utilisateur de "ajouter au panier" à "commande confirmée", personne n'arrivait à se mettre d'accord sur la séquence exacte. Quels services étaient impliqués ? Dans quel ordre ? Où la vérification de stock se faisait-elle — avant ou après le paiement ?

Trois ingénieurs avaient trois modèles mentaux différents. Nos diagrammes d'architecture statiques montraient la structure, mais pas le comportement. On pouvait voir les boîtes et les flèches, mais on ne pouvait pas voir comment un utilisateur se déplaçait réellement dans le système.

C'est là que j'ai réalisé qu'on avait besoin de flux utilisateurs.

Ce que sont vraiment les flux utilisateurs

Un flux utilisateur documente le parcours qu'un utilisateur prend à travers votre système pour accomplir un objectif. Pas la structure statique (c'est à ça que servent les diagrammes C4), mais la séquence dynamique :

L'utilisateur fait X
Le système répond avec Y
L'utilisateur choisit Z
Et ainsi de suite...

Ça semble évident, mais c'est étonnamment rare d'avoir ça bien documenté. La plupart des équipes ont des diagrammes d'architecture (structure du système) et de la documentation API (détails des endpoints), mais rien entre les deux qui montre comment ces pièces fonctionnent ensemble du point de vue de l'utilisateur.

Le fossé entre structure et comportement

Voici une version simplifiée de notre diagramme C4 de containers à l'époque :

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Web App   │────▶│     API     │────▶│  Database   │
└─────────────┘     └──────┬──────┘     └─────────────┘
                           │
                    ┌──────▼──────┐
                    │   Payment   │
                    │   Service   │
                    └──────┬──────┘
                           │
                    ┌──────▼──────┐
                    │   Stripe    │
                    └─────────────┘

Ça vous dit que les composants existent et comment ils se connectent. Mais ça ne répond pas : Quand un utilisateur fait un checkout, que se passe-t-il en premier ? L'API valide-t-elle le stock avant d'appeler le paiement ? Que se passe-t-il si le paiement réussit mais que le stock n'est plus disponible ?

Ces questions nécessitent de comprendre le flux, pas juste la structure.

Anatomie d'un flux utilisateur utile

Avec le temps, j'ai développé un template qui fonctionne bien pour documenter les flux :

1. Énoncé de l'objectif

Commencez par ce que l'utilisateur essaie d'accomplir :

Objectif : Compléter un achat des articles dans le panier

Ça garde le flux focalisé. Si vous vous retrouvez à documenter plusieurs objectifs, divisez en plusieurs flux.

2. Préconditions

Qu'est-ce qui doit être vrai avant que ce flux commence ?

L'utilisateur est connecté
Le panier contient au moins un article
Les articles dans le panier sont en stock (au moment du chargement de la page)

Ça évite la confusion sur l'état initial et clarifie les hypothèses.

3. Le chemin heureux

Documentez d'abord le chemin de succès attendu :

1. L'utilisateur clique sur le bouton "Checkout"
   → Web App affiche le formulaire d'adresse de livraison

2. L'utilisateur entre l'adresse de livraison, clique "Continuer"
   → API valide le format de l'adresse
   → API calcule les options de livraison
   → Web App affiche la sélection de méthode de livraison

3. L'utilisateur sélectionne la méthode de livraison, clique "Continuer"
   → API valide la méthode de livraison
   → Web App affiche le formulaire de paiement

4. L'utilisateur entre les détails de paiement, clique "Passer commande"
   → API crée une commande en attente dans la base de données
   → API appelle le Service de Paiement avec les détails de commande
   → Service de Paiement appelle Stripe pour débiter la carte
   → Service de Paiement retourne succès à l'API
   → API marque la commande comme confirmée
   → API déclenche l'email de confirmation
   → Web App affiche la page de confirmation de commande

5. L'utilisateur voit la confirmation avec le numéro de commande

Notez quelques choses :

Chaque étape inclut ce que l'utilisateur fait ET comment le système répond
On spécifie quels composants gèrent chaque action
Le niveau de détail est suffisant pour comprendre le flux sans lire le code

4. Chemins d'erreur et cas limites

Le chemin heureux n'est que le début. La vraie valeur vient de documenter ce qui se passe quand les choses tournent mal :

Paiement refusé :

À l'étape 4, si Stripe retourne payment_declined :
→ Service de Paiement retourne erreur à l'API
→ API ne marque PAS la commande comme confirmée
→ API supprime la commande en attente
→ Web App affiche message "Paiement refusé"
→ L'utilisateur peut réessayer avec un autre moyen de paiement

Stock modifié :

À l'étape 4, avant de créer la commande en attente :
→ API revérifie la disponibilité du stock
→ Si article maintenant indisponible :
  → API retourne inventory_error
  → Web App affiche "Article plus disponible" avec lien vers le panier
  → L'utilisateur doit retirer l'article et recommencer le checkout

Timeout réseau :

À l'étape 4, si le Service de Paiement ne répond pas en 30 secondes :
→ API ne réessaie PAS (pour éviter les doubles débits)
→ API retourne timeout_error
→ Web App affiche "Veuillez vérifier votre email pour confirmer le statut"
→ Job en background vérifie le statut du paiement après 5 minutes
→ Si paiement réussi : marquer commande confirmée, envoyer email
→ Si paiement échoué : nettoyer la commande en attente

Ces chemins d'erreur sont là où les bugs se cachent. Ce sont aussi là où la plupart de la documentation s'arrête, c'est pourquoi les bugs s'y cachent.

5. Notes techniques

Ajoutez tout contexte technique pertinent :

Notes techniques :
- La vérification de stock et le paiement ne sont PAS atomiques. Race condition
  possible mais acceptable vu la faible probabilité et le processus de résolution manuelle.
- Le webhook Stripe fournit une confirmation de secours si la réponse API est perdue.
- Les commandes en attente de plus d'1 heure sont nettoyées par un job planifié.

Connecter les flux à l'architecture

C'est là que ça devient puissant : lier les flux utilisateurs à vos diagrammes C4.

Dans Archyl, on peut annoter quels composants sont impliqués dans chaque étape d'un flux. Ça crée une traçabilité bidirectionnelle :

Vous regardez un flux ? Voyez quels composants il touche.
Vous regardez un composant ? Voyez quels flux passent par lui.

Quand ce bug de checkout est arrivé, on aurait pu :

Ouvrir le flux de checkout
Voir exactement quels services étaient impliqués
Tracer jusqu'à l'étape spécifique qui échouait
Comprendre la gestion d'erreur à ce point

Au lieu de ça, on a passé deux jours à redécouvrir comment notre propre système fonctionnait.

Différents types de flux

Tous les flux ne sont pas les mêmes. On les catégorise :

Flux utilisateurs

Séquences initiées par l'utilisateur depuis l'UI :

Flux de checkout
Flux d'inscription
Flux de réinitialisation de mot de passe
Flux de mise à jour de profil

Ceux-ci commencent par une action utilisateur et finissent par un résultat visible.

Flux système

Séquences initiées par la machine :

Job de réconciliation nocturne
Traitement de webhooks
Cascades event-driven
Notifications planifiées

Ceux-ci sont tout aussi importants mais souvent moins documentés parce qu'il n'y a pas d'UI à voir.

Flux d'intégration

Séquences cross-système :

Import de commandes tierces
Batches de règlement de paiement
Synchronisation de données avec des partenaires

Ceux-ci impliquent typiquement des systèmes hors de votre contrôle et ont plus de modes de défaillance potentiels.

Comment on documente les flux maintenant

Après ce fiasco de débogage de checkout, on a établi un processus :

Chaque fonctionnalité majeure a un flux

Quand on construit une nouvelle fonctionnalité, on documente le flux avant d'écrire le code. Ça sert de document de design et persiste comme documentation.

Le format est du simple markdown :

# Fonctionnalité : Avis utilisateurs

## Objectif

L'utilisateur soumet un avis pour un produit acheté

## Préconditions

- L'utilisateur est connecté
- L'utilisateur a acheté le produit
- Le produit autorise les avis

## Flux

1. L'utilisateur clique "Écrire un avis" sur la page produit
   ...

## Gestion d'erreurs

...

## Composants impliqués

- Web App
- API Gateway
- Service d'Avis
- Service Produit
- Service de Notification

## ADRs liés

- ADR-0023: Stratégie de modération des avis

Revue de flux dans les PRs

Si une PR change un flux documenté, on exige que la documentation du flux soit mise à jour. Les templates de PR incluent : "Ce changement modifie-t-il des flux utilisateurs ? Si oui, mettez à jour les docs de flux."

Audit trimestriel des flux

Chaque trimestre, on parcourt les flux critiques en équipe :

Ouvrir la documentation du flux
Tracer à travers le code/système réel
Identifier les divergences
Mettre à jour la documentation ou corriger les bugs

Ça semble être de l'overhead, mais ça a attrapé de vrais problèmes. Deux fois on a découvert que des changements de code avaient cassé le comportement documenté sans que personne ne s'en rende compte.

Erreurs courantes

Erreur 1 : Trop de détails

Un document de flux ne devrait pas se lire comme du code. Si vous documentez des requêtes de base de données individuelles, vous êtes au mauvais niveau. Concentrez-vous sur les étapes visibles par l'utilisateur et les interactions au niveau service.

Erreur 2 : Documenter seulement les chemins heureux

Le chemin heureux est facile. Les chemins d'erreur sont là où vivent les bugs. Forcez-vous à répondre : "Que se passe-t-il si cette étape échoue ?"

Erreur 3 : Ne pas mettre à jour après les changements

Un flux documenté qui ne correspond pas à la réalité est pire que pas de documentation. Ça crée une fausse confiance et mène à des hypothèses erronées pendant le débogage.

Erreur 4 : Traiter les flux comme statiques

Les flux utilisateurs évoluent. De nouvelles fonctionnalités ajoutent des étapes. Des optimisations en retirent. Les tests A/B changent le comportement. Traitez les flux comme des documents vivants, pas des artefacts ponctuels.

Outils et formats

Vous n'avez pas besoin d'outils spéciaux pour la documentation de flux. Du markdown dans votre repository fonctionne très bien. Ce qui compte c'est la cohérence et la découvrabilité.

Cela dit, les diagrammes visuels de flux peuvent aider pour les séquences complexes. Des outils comme Mermaid vous permettent d'écrire des diagrammes comme du code :

sequenceDiagram
    participant U as Utilisateur
    participant W as Web App
    participant A as API
    participant P as Service Paiement
    participant S as Stripe

    U->>W: Clic "Passer commande"
    W->>A: POST /orders
    A->>A: Créer commande en attente
    A->>P: Traiter paiement
    P->>S: Débiter carte
    S-->>P: Succès
    P-->>A: Paiement confirmé
    A->>A: Marquer commande confirmée
    A-->>W: Détails commande
    W-->>U: Page de confirmation

La clé c'est le contrôle de version. Les diagrammes de flux dans Figma ou Lucidchart tendent à dériver de la réalité parce qu'ils sont déconnectés du processus de développement.

Conclusion

Les diagrammes d'architecture statiques vous disent de quoi est fait votre système. Les flux utilisateurs vous disent comment il se comporte. Vous avez besoin des deux.

La prochaine fois que vous déboguez un problème complexe à travers plusieurs services, demandez-vous : "Avons-nous un flux documenté pour ça ?" Si la réponse est non, vous passerez des heures à reconstruire comment les pièces s'assemblent — des heures qui auraient pu être économisées avec un simple document.

Commencez avec votre flux le plus critique. Pour la plupart des systèmes, c'est probablement l'authentification ou le chemin de conversion principal (checkout, inscription, action core). Documentez le chemin heureux, puis forcez-vous à documenter au moins trois cas d'erreur.

Votre futur vous — déboguant frénétiquement à 2h du matin — vous remerciera.

Plus sur la documentation d'architecture : Introduction au modèle C4 | Architecture Decision Records | Pourquoi la documentation compte

Documenter les flux utilisateurs dans votre architecture logicielle - Archyl Blog