Carte d'architecture d'une page pour un prototype en désordre : méthode pratique

Pourquoi les prototypes en désordre sont difficiles à corriger sans carte

Un prototype en désordre est confus d'une manière très spécifique. Rien n'est étiqueté, les noms de dossiers semblent importants mais ne veulent rien dire, et le comportement réel est caché derrière des helpers et des bouts de code copiés-collés. Vous cliquez sur un bouton dans l'UI et trois appels API partent, un job en arrière-plan s'exécute, et des données apparaissent dans un tableau qui semble être alimenté depuis ailleurs.

Quand vous essayez de corriger des problèmes dans un repo comme ça, vous finissez par deviner. Deviner coûte cher pour deux raisons : vous perdez du temps à suivre le mauvais fichier, et vous créez de nouveaux bugs quand vous changez quelque chose qui semblait inutilisé mais qui maintenait l'app en vie en silence.

Une carte d'architecture d'une page aide parce qu'elle donne à tout le monde la même image de comment l'app fonctionne grosso modo. Ce n'est pas un diagramme parfait, et ce n'est pas la documentation de chaque classe. C'est une référence partagée pour que l'équipe puisse parler de la même chose.

Sans carte, les corrections tournent souvent en :

• modifier du code près du bug, puis découvrir que la vraie cause est deux étapes en amont
• patcher le même problème à plusieurs endroits parce que la logique est dupliquée
• casser l'auth, les paiements ou les emails parce qu'un « petit » changement a touché du middleware partagé
• oublier des dépendances externes comme des webhooks, des files d'attente ou un stockage tiers

Cette approche est particulièrement utile quand la base de code est héritée, bâclée ou générée par des outils qui produisent des démos fonctionnelles mais à la structure fragile. Beaucoup de prototypes générés par IA tombent dans cette catégorie : les flux sont implicites, et les secrets, l'auth et les règles de données sont éparpillés.

Un exemple rapide : un fondateur signale « la connexion fonctionne en local, échoue en production. » Sans carte, on a tendance à se focaliser sur le formulaire de login. Avec une carte, on voit tout le chemin : UI -> route d'auth -> recherche en base -> cookie ou token posé -> vérification middleware sur la requête suivante. Cette vue montre souvent où le flux casse vraiment.

Ce qui rend une carte d'architecture d'une page utile

Une carte d'architecture d'une page marche quand quelqu'un peut la lire en 60 secondes et dire : « Oui, c'est comme ça que ça marche. » Une fois que tout le monde s'accorde sur l'histoire, on arrête de se disputer sur des suppositions et on commence à tester les bonnes étapes.

Les meilleures cartes utilisent des mots simples. Au lieu de noms de dossiers comme src/services/authV2, étiquetez une boîte « Connexion et sessions. » Au lieu de api/routes, écrivez « Endpoints HTTP. » Ça garde la carte lisible pour les personnes non techniques, et ça vous force à nommer ce que le code fait vraiment.

Une carte d'une page vous évite aussi la sur-documentation. Vous montrez seulement les chemins qui comptent pour le business et pour les bugs que vous poursuivez. La plupart des prototypes ont quelques parcours critiques ; le reste peut attendre.

Commencez par les flux qui décident généralement si l'app marche :

• connexion et création de compte
• le flux principal (la chose pour laquelle les utilisateurs viennent)
• paiements (si vous facturez)
• emails, notifications ou webhooks
• uploads et téléchargements (si des fichiers sont impliqués)

Les flèches valent mieux que les paragraphes. Une flèche doit répondre : qui appelle qui, quelles données entrent, et ce qui en ressort. « Navigateur -> API -> Base de données » plus une note comme « crée un enregistrement user » est souvent plus utile qu'une page de texte.

Collecter des indices rapides avant de lire beaucoup de code

Quand un prototype a peu ou pas de documentation, votre premier travail n'est pas de comprendre chaque fonction. Votre premier travail est d'apprendre ce que l'app prétend faire, de quoi elle dépend, et où elle touche le monde extérieur.

Commencez par les fichiers qui « dénoncent » le projet. Un README (même mauvais) peut mentionner les fonctionnalités principales, la configuration d'hébergement, ou les problèmes connus. Les fichiers de dépendances comme package.json, requirements.txt, ou les lockfiles révèlent rapidement le framework, les drivers de base, les bibliothèques d'auth, les outils de jobs en arrière-plan, et les SDK de paiement ou d'email.

Puis vérifiez comment l'app récupère la configuration. Cherchez .env.example, des templates de configs, des Dockerfiles, et toute note sur les secrets. C'est souvent là que vous découvrez des clés manquantes, des URL de callback erronées, ou des tokens hardcodés qui fonctionnent en local mais échouent après déploiement.

Si vous voulez une checklist rapide, concentrez-vous sur :

• Ce sur quoi ça tourne : framework et runtime (via les fichiers de dépendances)
• Comment les requêtes entrent : pages, endpoints API, webhooks, tâches planifiées
• Où vivent les données : migrations, fichiers de schéma, scripts de seed, modèles ORM
• Avec quoi ça parle : auth, paiements, email, stockage de fichiers, analytics
• Comment c'est censé tourner : configs de déploiement, fichiers CI, scripts "start"

Exemple : une app générée par IA « marche en local », mais les utilisateurs ne peuvent pas se connecter en production. Avant une lecture approfondie du code, vous repérez un SDK d'auth dans package.json, des URL de callback dans le template d'env, et une route /api/auth qui attend un SECRET manquant. C'est suffisant pour esquisser la chaîne clé et signaler un vrai risque si des secrets sont exposés.

Trouver les points d'entrée et les principaux flux utilisateur

Si vous commencez la cartographie à partir de fichiers aléatoires, vous allez manquer comment les gens utilisent réellement l'app. Commencez par les points d'entrée : les premiers endroits où un utilisateur réel ou un système touche votre code.

Commencez par les points d'entrée utilisateur

Cherchez les écrans qui créent le plus de changements d'état : page d'accueil, inscription/connexion, l'écran principal de travail, et toute zone admin. Même dans un prototype en désordre, ces flux révèlent généralement les objets de données centraux (utilisateurs, projets, paiements, fichiers) et les décisions clés (connecté vs non, gratuit vs payant, contrôle d'accès par rôle).

Une manière pratique de confirmer le flux est de suivre ce qui arrive après un clic de bouton : où envoie-t-il l'utilisateur, quel appel API se déclenche, et qu'est-ce qui est stocké (cookie, session, local storage, ligne en base) ?

Puis capturez les points d'entrée techniques

En parallèle, listez chaque porte d'entrée vers le backend. Ce sont souvent la raison pour laquelle les prototypes cassent en production.

• routes UI et pages principales (y compris admin)
• routes API (REST/GraphQL), server actions, edge functions
• callbacks d'auth (redirects OAuth, magic links)
• webhooks de partenaires (paiements, fournisseur d'email, CRM)
• automatisations (cron, queues, tâches planifiées)

Les appelants externes comptent aussi. Un navigateur n'est pas le seul client ; une appli mobile, un outil admin interne, ou un système partenaire peut appeler les mêmes endpoints avec des hypothèses différentes.

Exemple : une app générée par IA peut vous permettre de « Sign in » en localhost, mais en production l'URL de callback OAuth pointe vers le mauvais domaine. Marquez ce callback comme point d'entrée et ajoutez une note à côté : « Doit correspondre à l'URL déployée, sinon boucle de connexion. »

Lister les modules clés sans se perdre dans les dossiers

Les prototypes en désordre semblent souvent plus grands qu'ils ne le sont. Une façon rapide de reprendre le contrôle est de grouper le code par ce qu'il fait, pas par où il se trouve dans l'arborescence. Votre but est un petit ensemble de modules qui tiennent sur une page.

Commencez par repérer les « puits de gravité » : des fichiers que beaucoup d'autres importent ou appellent. Ils révèlent généralement les vraies frontières des modules, même si la structure du repo est aléatoire.

Un inventaire simple des modules est :

• UI : pages, composants, formulaires, et où les requêtes réseau sont déclenchées
• Surface API : handlers de routes, contrôleurs, middleware, validation des requêtes
• Logique métier : workflows comme « créer un compte » ou « checkout », plus les jobs d'arrière-plan
• Accès aux données : modèles ORM, requêtes brutes, migrations, caching, uploads de fichiers
• Intégrations : auth, paiements, email/SMS, analytics, logs

Après avoir ces catégories, assignez rapidement les fichiers. Si un fichier semble appartenir à deux endroits, marquez-le comme « frontière » et passez à la suite. Les fichiers frontière sont souvent là où se cachent les bugs (par exemple, composants UI qui construisent des filtres unsafe, ou routes API qui contiennent des règles de paiement).

Exemple : un app générée par IA peut avoir un dossier utils avec 40 fichiers. En survolant l'utilisation, vous pouvez trouver plusieurs clusters qui sont en réalité « envoi d'email », « helpers auth », et « formatage de données ». Ces clusters sont vos modules, même si les dossiers disent le contraire.

Méthode étape par étape pour esquisser la carte depuis le code

Une bonne carte d'architecture d'une page se construit à partir du comportement réel, pas des noms de dossier. La méthode la plus rapide est de choisir un flux, le suivre de bout en bout, et ne dessiner que ce que vous pouvez prouver.

Commencez par un flux que vous pouvez tracer

Choisissez un flux central avec un début et une fin clairs, comme l'inscription jusqu'à la première action réussie (créer un projet, uploader un fichier, passer une commande). Trouvez le premier point d'entrée pour ce flux : une page, une route, un contrôleur, ou un endpoint API.

Puis tracez chaque étape dans l'ordre et transformez chaque étape en boîte. Ne vous inquiétez pas des noms parfaits. Utilisez ce que le code appelle (par exemple, auth.ts, createProject, POST /api/upload). Si vous ne pouvez pas suivre une étape, marquez-la « inconnue » au lieu de deviner.

À côté de chaque boîte, capturez quelques essentiels :

• ce qui la déclenche (clic bouton, appel API, cron job, webhook)
• ce qu'elle retourne (redirect, JSON, URL de fichier, erreur)
• où l'état change (table DB, cookie, local storage)
• le principal risque ou l'hypothèse (validation manquante, confiance dans l'entrée client)

Ajoutez services et frontières de confiance comme formes séparées

Les services externes méritent leur propre boîte car ils échouent différemment de votre code. Les plus courants : fournisseurs d'auth, processeurs de paiement, email/SMS, stockage d'objets, analytics.

Puis marquez les frontières de confiance avec de simples étiquettes sur les arêtes, comme « navigateur vers serveur » et « serveur vers tiers ». Cela vous aide à repérer où les secrets, tokens et données personnelles traversent des zones hors de votre contrôle.

Répétez la même méthode pour deux ou trois autres flux critiques jusqu'à ce que la page paraisse « remplie » mais lisible. Connexion, réinitialisation de mot de passe, et l'action principale de création/checkout suffisent généralement.

Ajoutez des notes de sécurité et de protection des données pendant la cartographie

Une carte d'architecture d'une page n'est pas seulement des boîtes et des flèches. Ajoutez de petites notes de sécurité directement sur le dessin pendant que le code est encore frais dans votre tête. Ces notes expliquent souvent pourquoi un prototype marche en mode démo mais casse (ou devient dangereux) en production.

Commencez par l'authentification. Marquez où la connexion se produit, qu'est-ce qui crée la session ou le token, et quels endpoints en dépendent. S'il y a réinitialisation de mot de passe ou OAuth, notez la route de callback et où l'app garde l'état (cookies, local storage, session serveur).

Ensuite, cherchez les secrets. Écrivez où vivent les clés API et les chaînes de connexion, et où elles pourraient fuir. Dans les prototypes en désordre, les clés finissent souvent dans le code client, des fichiers de config commités, des logs de debug, ou des messages d'erreur.

Puis suivez les entrées utilisateur dès qu'elles pénètrent le système. Étiquetez chaque frontière où des données non fiables apparaissent : formulaires, query strings, webhooks, uploads de fichiers, callbacks tiers. Ajoutez une note : « validé côté serveur » ou « UI seulement. »

Pour la sécurité DB, marquez où les requêtes sont construites. Si vous voyez du SQL brut, des filtres dynamiques, ou de la concaténation de chaînes, signalez-le sur la carte. C'est une source courante d'injection SQL et de fuites de données.

Enfin, notez les permissions. Un endpoint « derrière auth » n'est pas la même chose qu'« autorisé ». Marquez où les vérifs de rôle, les contrôles de propriété (l'utilisateur ne peut voir que ses propres enregistrements), et les actions admin sont appliqués.

Si vous avez besoin d'une petite checklist d'annotations, utilisez :

• type d'auth et où elle est vérifiée
• où vivent les secrets et s'ils sont exposés
• où la validation a lieu
• comment la base est interrogée (ORM vs SQL brut)
• où les règles d'autorisation sont appliquées

Erreurs communes qui rendent la carte trompeuse

Le but est la clarté, pas l'exhaustivité. La façon la plus rapide de ruiner une carte d'une page est de la traiter comme un index de fichiers. Vous vous retrouvez avec une page dense qui n'explique toujours pas le comportement de l'app.

Un autre piège est de nommer les boîtes d'après des outils plutôt que des comportements. « Next.js + tRPC + Prisma » dit à un dev ce que vous avez utilisé, mais pas ce qui se passe quand un utilisateur se connecte, téléverse un fichier, ou paye. Une carte doit se lire comme une histoire simple : qui appelle quoi, quelles données bougent, et ce qui peut échouer.

Erreurs courantes :

• dessiner chaque dossier et rater les quelques flux qui comptent (connexion, paiements, actions admin, onboarding)
• nommer les boîtes d'après la stack tech plutôt que l'action (« Créer facture » vaut mieux que « Service backend »)
• oublier les chemins silencieux comme les cron jobs, queues, et webhooks entrants qui n'échouent qu'en production
• mélanger les environnements (mocks locaux, fausses clés, services absents après déploiement)
• omettre le modèle de données, puis se demander pourquoi la logique métier se contredit entre écrans

Les suppositions ne sont pas le problème ; les suppositions cachées le sont. Si vous n'êtes pas sûr que « les emails sont envoyés par le fournisseur A » ou que « un job tourne toutes les heures », écrivez « supposé » ou « inconnu ». Ça transforme la confusion en tâches claires.

Vérifications rapides avant de partager la carte

Avant d'envoyer la carte à un collègue ou client, faites une passe de sanity rapide. Le but n'est pas la perfection. C'est vérifier que la page dit la vérité et oriente vers les bonnes questions.

Essayez ceci : pouvez-vous expliquer le flux utilisateur principal en moins de deux minutes en ne montrant que ce qui est sur la page ? Si vous continuez à dire « et puis il se passe des trucs », ajoutez une boîte ou une flèche manquante.

Cinq vérifications qui détectent la plupart des problèmes :

• chaque service externe apparaît quelque part (auth, email/SMS, paiements, stockage de fichiers, analytics)
• au moins une boîte « stockage de données » existe (DB, stockage d'objets) avec des flèches lecture/écriture
• les frontières de confiance sont visibles (client, votre serveur, tiers)
• les points d'entrée sont évidents (routes, endpoints, jobs, webhooks)
• les risques majeurs sont visibles (gestion auth/session, secrets, validation des entrées)

Ensuite, ajoutez un petit coin « Inconnus » avec jusqu'à cinq items. Rendez-les spécifiques pour que quelqu'un puisse les confirmer rapidement.

Exemple : cartographier un prototype généré par IA qui casse en production

Un fondateur hérite d'un prototype Bolt ou Lovable qui marche en localhost, mais s'effondre après déploiement. Les utilisateurs voient la landing page, mais l'inscription échoue et personne ne peut se connecter.

Commencez par une action utilisateur réelle : « Créer un compte. » Vous n'avez pas besoin de boîtes parfaites. Vous avez besoin des quelques boîtes qui expliquent qui parle à qui et où les données changent.

Une carte typique pour cette situation inclut :

• UI navigateur (formulaire d'inscription) qui appelle une action serveur ou une route API
• le code serveur parle à un provider d'auth et reçoit un callback
• le serveur écrit une ligne user en base
• un service email envoie les messages de vérification
• des variables d'environnement fournissent clés et URL de callback

Tracez ensuite l'étape qui échoue en production. L'UI soumet, le serveur redirige vers le provider d'auth, puis le callback revient sur un domaine différent de celui attendu parce que l'URL de callback est encore configurée pour localhost. Dans les pires cas, le bundle client contient un secret d'auth parce qu'il était stocké dans une var d'env publique.

Pendant que vous cartographiez, ajoutez de petites notes rouges qui rendent les premiers correctifs évidents :

• secret exposé dans la config côté client
• vérifications de rôle ou de propriété manquantes sur des endpoints sensibles
• noms de table incohérents (users vs user, profile vs profiles)
• callbacks d'auth pointant vers localhost ou le mauvais domaine

Le résultat n'est pas un joli diagramme. C'est de la clarté et un ordre de correction plus sûr.

Prochaines étapes : transformer la carte en plan de réparation

Une carte d'architecture d'une page ne sert que si elle change ce que vous faites ensuite. Servez-vous-en pour transformer le « bricolage de bugs au hasard » en un ordre de travail clair, afin d'attaquer d'abord les risques qui bloquent le plus.

Un ordre de correction pratique pour la plupart des prototypes en désordre :

• stabiliser l'authentification et les sessions (login, rôles, stockage des tokens, reset de mot de passe)
• confirmer le modèle de données (tables, relations, migrations, points de validation)
• réparer le flux utilisateur central (l'action que le produit doit accomplir de bout en bout)
• traiter les extras (notifications, analytics, outils admin)

Puis décidez si vous devez patcher, refactoriser ou reconstruire :

• Patch quand le flux est clair et que les problèmes sont isolés (une intégration cassée, quelques requêtes mauvaises).
• Refactor quand l'app fonctionne mais que la structure vous empêche d'avancer (logique dupliquée, frontières floues).
• Reconstruire quand la carte montre une architecture spaghetti (tout parle à tout, les secrets sont éparpillés, aucun endroit sûr pour ajouter des contrôles).

Gardez la one-pager à jour pendant que vous réparez. Chaque fois que vous déplacez une responsabilité (par exemple, centraliser l'accès DB ou mettre les vérifs d'auth en middleware), mettez la carte à jour pour que l'équipe ne retombe pas dans les suppositions.

Si vous voulez un second avis sur une base de code générée par IA, FixMyMess (fixmymess.ai) commence par un diagnostic du code et peut aider à réparer des problèmes comme une authentification cassée, des secrets exposés, et un accès aux données unsafe avant que vous n'investissiez du temps dans des réécritures.