Baukaalm/system-design-first

Conception système d'abord

La plupart des tickets décrivent quoi construire et cachent les questions qui décident s'il survivra au contact avec la production : combien d'utilisateurs, à quelle fréquence, combien de données, que se passe-t-il quand une dépendance est lente, qui possède la vérité quand deux rédacteurs entrent en compétition. Cette compétence rend ces questions explicites avant que le code ne soit écrit, sous une forme que l'auteur de la tâche peut lire et contester.

Le processus est : périmètre → estimation → conception de haut niveau → analyse approfondie → conclusion, appliqué à un travail réel : il existe une base de code existante, un auteur avec une intention, et un budget. L'objectif est une image nette de la fonctionnalité du point de vue du système.

Répondez dans la langue utilisée par l'utilisateur. Le bref est pour eux, pas pour vous.

1. Évaluer d'abord la profondeur

Sur-concevoir une correction de faute de frappe est aussi mauvais que sous-concevoir un flux de paiement. Choisissez le niveau, dites-le en une ligne, et consacrez-y le temps approprié.

Niveau	Tâche typique	Ce que vous produisez
L0 – trivial	Modification de copie, renommage, ajustement de style, bug évident avec une correction locale	Rien de plus. Une phrase au maximum si un risque caché existe ("cette étiquette est également mise en cache dans le CDN pendant 24h"). Ensuite, exécutez simplement la tâche.
L1 – modification locale	Nouveau champ, nouveau filtre, petite modification de point de terminaison, un hook, un ajustement de requête	Une vérification de conception de 3 à 7 lignes intégrée : ce qu'elle touche, la charge qu'elle supporte, la seule chose qui pourrait poser problème (N+1, invalidation de cache, pagination, idempotence). Puis implémentez.
L2 – fonctionnalité	Nouvel écran avec flux de données, nouveau point de terminaison + stockage, notifications, recherche, exportation, intégration avec un tiers	Le bref de conception (section 4), environ une page. Puis implémentez selon le bref.
L3 – sous-système	Nouveau service, canal temps réel, pipeline d'événements, modèle de données multi-locataire, migration d'un chemin chaud, tout ce qui contient "échelle" dans le ticket	Bref complet plus une analyse approfondie par composant risqué, alternatives envisagées, chemin de migration, quoi mesurer après le lancement.

Signaux qui font passer une tâche vers le haut d'un niveau : latence côté utilisateur, rédacteurs simultanés, fan-out (un événement → plusieurs destinataires), croissance illimitée d'une table ou d'une liste, limites de débit tiers, argent, PII, tout ce qui s'exécute selon un planning, ou solutions "temporaires" qui resteront évidemment. Signaux qui la font passer vers le bas : outils internes avec une poignée d'utilisateurs, données qui tiennent en mémoire pour toujours, expériences avec indicateur de fonctionnalité et interrupteur d'arrêt.

Si l'utilisateur demande explicitement une revue de conception ou une analyse plus approfondie, traitez-la comme L3 quelle que soit sa taille.

2. Le processus, étape par étape

Parcourez-les dans l'ordre. Pour L1, compressez-les en quelques lignes ; pour L2/L3, chaque étape devient une section du bref. references/framework.md contient les listes de contrôle de questions pour chaque étape ; lisez-le la première fois que vous exécutez un passage L2+ dans une session.

Étape 1 — Comprendre et définir le périmètre

• Reformulez la fonctionnalité en un paragraphe comme le système la voit : acteurs, déclencheurs, entrées, sorties, effets secondaires.
• Séparez les exigences fonctionnelles (ce qu'elle fait) des non-fonctionnelles (comment elle le fait : échelle, latence, disponibilité, cohérence, durabilité, sécurité, coût, opérabilité). Les tickets ne mentionnent presque jamais le deuxième type ; déduisez-les du contexte produit et dites qu'ils sont déduits.
• Écrivez ce qui est hors périmètre, pour que le bref ne s'agrandisse pas silencieusement.
• Recueillez l'intention de l'auteur : texte du ticket, description de la PR, commentaires, conceptions liées, ADR existants, comment des fonctionnalités similaires ont été construites dans ce dépôt. L'auteur a généralement une conception en tête ; mettez-la en surface plutôt que de la remplacer.
• Posez à l'utilisateur uniquement les questions qui modifient matériellement la conception (par ex. "cela doit-il être visible en une seconde, ou une minute suffit-elle ?"). Pour tout le reste, énoncez une hypothèse et passez à autre chose ; les hypothèses vont dans le bref.

Étape 2 — Estimer

Les chiffres transforment les opinions en décisions. Faites une estimation de coin de table même lorsque le ticket n'en a pas ; references/estimation.md contient les nombres de référence (échelle de latence, puissances de deux, neuf de disponibilité, capacités par nœud) et des exemples travaillés.

• Utilisateurs / locataires → utilisateurs actifs quotidiens → actions par jour → QPS moyen et de pointe (le pic est généralement 2 à 5 fois la moyenne, plus pour les flux en rafale comme "tout le monde ouvre l'application à 9h").
• Ratio lecture/écriture, taille de la charge utile → stockage par jour / an, bande passante.
• Croissance : quel est le nombre dans 12 mois si le produit réussit ?
• Là où des chiffres réels existent (analytiques, nombres de lignes DB, tableaux de bord existants, limites de configuration), utilisez-les et citez la source ; sinon donnez une fourchette et marquez-la comme une hypothèse.

Utilisez ensuite les chiffres pour éliminer des motifs, pas seulement pour les justifier : "à 30 écritures/s une table Postgres avec un index est acceptable ; une file d'attente n'est pas nécessaire pour le débit, seulement si nous voulons des tentatives et un découplage du fournisseur de courriel."

Étape 3 — Cartographier la conception actuelle (as-is)

Lisez le code avant de le décrire. Nommez les fichiers, modules, tables, points de terminaison, travaux, caches, files d'attente réels. N'inventez pas de composants.

• Quels composants la fonctionnalité touche-t-elle ? Dessinez le flux de données dans un court diagramme textuel (client → BFF → service → Postgres, événement → file → worker).
• Où se trouve l'état et qui le possède (DB, cache, magasin client, URL) ?
• Quelles primitives existantes peuvent être réutilisées (une table outbox, un exécuteur de travaux, un cache de requêtes, un hub WebSocket, un composant Pagination partagé) ?
• Chemins chauds, goulots d'étranglement connus, SPOF existants, limites actuelles (limites de débit, tailles de page, délais d'attente) que la fonctionnalité hérite.
• Pour une tâche frontend, le as-is reste un système : couche de récupération de données, politique de cache, limites de bundle, transport temps réel — voir references/frontend.md.

Étape 4 — Proposer la conception cible (to-be)

Partez de l'intention de l'auteur. Si elle est solide, dites-le et resserrez-la ; si elle entre en conflit avec les chiffres ou avec un mode de défaillance bien connu, montrez le conflit avec sa conséquence et proposez le plus petit changement qui le corrige. L'auteur prend la décision ; votre travail est de rendre le compromis visible.

• Conception de haut niveau sous forme de diagramme textuel, plus le contrat API (points de terminaison / événements / messages avec leurs formes) et le modèle de données (tables, clés, index, rétention).
• Pour chaque choix non trivial, nommez le motif et l'alternative que vous avez rejetée, avec la raison liée aux chiffres de l'étape 2. references/patterns.md est le catalogue : mise à l'échelle, mise en cache, asynchrone/files d'attente, magasins de données et cohérence, styles d'API et transport temps réel, limitation de débit, génération d'ID, fiabilité, observabilité — chacun avec "utiliser quand / éviter quand / compromis".
• Mappez la fonctionnalité à un système canonique quand cela correspond ("c'est un système de notification : file d'attente + workers par canal + déduplication", "c'est un fan-out de flux d'actualités", "c'est un limiteur de débit"). La dernière section du catalogue liste les formes canoniques et leurs blocs de construction standard. L'analogie donne au lecteur un point de référence connu et une liste de contrôle de ce dont ces systèmes ont généralement besoin.
• Préférez les primitives existantes du dépôt et la conception la plus simple qui répond aux chiffres avec une marge. Dites explicitement quelles mises à niveau sont reportées et quel signal les déclencherait ("ajouter un réplica en lecture quand le p95 de cette requête dépasse 200 ms ou que la table dépasse 50M de lignes").

Étape 5 — Analyse approfondie de ce qui peut casser

Pour L2, choisissez les une ou deux parties les plus risquées ; pour L3, parcourez-les toutes. Questions standard, dans l'ordre approximatif de leur fréquence de nuisance :

1. Concurrence et idempotence — doubles soumissions, tentatives, deux rédacteurs, livraison au moins une fois. Où se trouve la clé d'idempotence ? Quelle est la contrainte d'unicité ?
2. Cohérence — qui lit des données obsolètes et pendant combien de temps ; est-ce acceptable ; chemin d'invalidation du cache ; lecture de ses propres écritures.
3. Défaillance d'une dépendance — fournisseur en panne, file d'attente en retard, module distant qui échoue à charger. Délais d'attente, tentatives avec gigue, disjoncteur, dégradation gracieuse, ce que voit l'utilisateur.
4. Points chauds — clés chaudes, locataires célèbres, listes illimitées, N+1, analyses de table complètes, index manquant, ruée vers le cache à l'expiration.
5. Croissance — la table/liste/file d'attente qui croît sans limite ; rétention, archivage, pagination (curseur vs offset), partitionnement.
6. Migration et déploiement — backfill, période de double écriture, indicateur de fonctionnalité, chemin de retour arrière, modifications de contrat rétrocompatibles.
7. Sécurité et confidentialité — autorisation au niveau des données (isolation des locataires), PII dans les journaux/files d'attente, limitation de débit sur les points de terminaison publics, validation des entrées.
8. Observabilité — quelle métrique prouve que cela fonctionne (SLI), quelle alerte se déclenche quand cela ne fonctionne pas, quoi journaliser pour déboguer une seule requête.

Étape 6 — Conclure, proposer la visualisation

Les diagrammes coûtent des jetons, donc ils sont sur option. Le bref lui-même utilise uniquement des flux textuels sur une ligne (client → API → Postgres).

Pour L2 et L3, terminez le bref par une question, accompagnée des questions ouvertes, dans la langue de l'utilisateur :

Dessiner l'architecture ? 1 — diagramme as-is / to-be dans le terminal · 2 — plus un dossier de conception (Mermaid + architecture.html) · 3 — non

• Ne dessinez qu'après que l'utilisateur a choisi 1 ou 2, en suivant references/visualization.md. N'attendez pas la réponse pour commencer à implémenter ; si l'utilisateur passe à autre chose sans répondre, c'est un "non".
• Sautez la question et dessinez immédiatement seulement lorsque l'utilisateur a déjà demandé un diagramme, une image, une visualisation ou le dossier de conception.
• Si personne ne peut répondre (une exécution non interactive, CI, une évaluation), ne dessinez pas et ne demandez pas ; mentionnez en une ligne que les diagrammes sont disponibles sur demande.
• Ne le proposez jamais pour L0 ou L1.

Produisez le bref (section suivante), puis continuez avec la tâche : implémentez selon le bref, conservez le bref dans la description de la PR / MR également, et listez les questions ouvertes pour l'auteur plutôt que de les décider silencieusement.

3. Règles de jugement

• Les chiffres avant les motifs. Ne recommandez jamais Kafka, le sharding, CQRS, un cluster de cache dédié ou des microservices sans une estimation qui les nécessite. La simplicité est une fonctionnalité ; la complexité doit gagner sa place.
• Expliquez, ne faites pas la leçon. Chaque recommandation porte un "parce que" d'une phrase que l'auteur peut vérifier. Les analogies avec des systèmes canoniques sont bienvenues ; les listes de mots à la mode ne le sont pas.
• Respectez la conception de l'auteur. Présentez les désaccords comme "X causera Y à la charge Z ; le correctif le moins cher est W". S'il préfère toujours sa voie, implémentez sa voie et notez le risque dans le bref.
• Le code existant est une preuve. Lisez-le. Un bref qui décrit des composants qui n'existent pas est pire que pas de bref.
• Séparez l'indispensable du souhaitable. Marquez chaque recommandation comme "nécessaire maintenant", "nécessaire avant le lancement" ou "nécessaire à ~N utilisateurs".
• Le frontend compte. La mise en cache côté client, la pagination, les mises à jour optimistes, le transport temps réel, les limites de bundle et l'isolation des défaillances sont de la conception système ; references/frontend.md couvre la version côté client de chaque étape.
• Restez dans la langue et le vocabulaire de l'utilisateur. Traduisez les noms de motifs si l'équipe le fait ; conservez le terme anglais entre parenthèses la première fois.

4. Le bref de conception

Utilisez cette structure pour L2 et L3. Gardez les titres ; ne supprimez une section que lorsqu'elle est vraiment vide et dites-le en une ligne. Visez une page pour L2. references/brief-template.md contient un exemple rempli et le formulaire compact L1.

# Bref de conception : <fonctionnalité>

**Profondeur :** L2 · **Statut :** proposition · **Intention de l'auteur :** <une ligne>

## 1. Périmètre
Fonctionnel : ...
Non fonctionnel (déduit sauf indication contraire) : échelle · latence · disponibilité · cohérence · sécurité · coût
Hors périmètre : ...
Hypothèses : ...

## 2. Estimations
| Métrique | Maintenant | +12 mois | Source |
| --- | --- | --- | --- |
| UAQ / locataires | | | |
| QPS de pointe (lecture / écriture) | | | |
| Croissance du stockage | | | |
Conclusion : <ce que les chiffres permettent / interdisent>

## 3. Conception actuelle (as-is)
<flux textuel sur une ligne> · propriété de l'état · primitives réutilisables · limites héritées
Fichiers : ...

## 4. Conception cible (to-be)
<flux textuel sur une ligne> · contrat API · modèle de données · analogie système canonique
Choix de motifs : <motif> — parce que <raison> ; rejeté <alternative> parce que <raison>.

## 5. Risques et analyses approfondies
1. <risque> → atténuation (nécessaire maintenant / avant le lancement / à N)
...

## 6. Déploiement, migration, observabilité
Indicateurs, backfill, retour arrière · SLI + alerte · quoi journaliser

## 7. Questions ouvertes pour l'auteur
- ...
- Dessiner l'architecture ? 1 — diagramme dans le terminal · 2 — plus dossier de conception · 3 — non

## 8. Plan d'implémentation
Étapes ordonnées, chacune assez petite pour être revue.

5. Références — quoi lire quand

Fichier	Lire quand
references/framework.md	Premier passage L2+ dans une session : listes de contrôle de questions par étape, liste NFR, comment extraire l'intention de l'auteur, anti-modèles d'analyse.
references/estimation.md	Chaque fois que vous avez besoin d'un chiffre : échelle de latence, neuf, capacités par nœud, calculs QPS/stockage, exemples travaillés.
references/patterns.md	Choisir ou justifier un motif ; mapper une fonctionnalité à un système canonique (chat, flux, notifications, autocomplétion de recherche, synchronisation de fichiers, limiteur de débit, magasin KV, générateur d'ID, paiements, ...). Possède une table des matières.
references/frontend.md	La tâche est une modification d'interface utilisateur / SPA / micro-frontend : cache de récupération de données, pagination, temps réel, limites de bundle, isolation des défaillances, chiffres côté client.
references/brief-template.md	Rédaction du bref : exemple L2 complet et formulaire compact L1 intégré.
references/visualization.md	Uniquement après que l'utilisateur a demandé des diagrammes (Étape 6). Les dessiner : règles de diagramme en boîte dans le terminal, conventions Mermaid, mise en page du dossier de conception, comment remplir assets/architecture.html.