Les erreurs d’architecture courantes dans les projets web

La plupart des erreurs d’architecture qui détruisent les projets web ne sont pas nouvelles. Elles reviennent à peu près sous la même forme, année après année, dans des projets de toutes tailles et de tous domaines. La partie coûteuse, ce n’est rarement l’erreur elle-même ; c’est le temps qu’il faut à l’équipe pour la reconnaître pour ce qu’elle est, et la latence avec laquelle son coût se révèle. Quand le symptôme devient visible (la plateforme est lente, les déploiements font peur, l’équipe réécrit au lieu de construire), le choix d’origine qui en est responsable a souvent deux ans et trois ingénieurs de retard.

Cet article est un catalogue de travail des erreurs d’architecture récurrentes que je vois le plus souvent dans les projets web. C’est le compagnon « ce qu’il faut éviter » de l’article sur le choix d’architecture. Chaque erreur ci-dessous est nommée, décrite, et associée au symptôme qui apparaît généralement en premier, pour qu’une équipe puisse se reconnaître avant que le coût ne s’accumule.

L’erreur d’architecture la plus courante, c’est de choisir la stack technologique en premier, souvent à partir de ce que l’équipe aime ou de ce qui est à la mode dans l’industrie, puis de rabattre la forme du projet dessus. La conversation commence par « on prend Next.js et Postgres sur Vercel » et n’atteint que plus tard la question de ce qu’est réellement le projet, de qui le maintient, de la forme de la charge, et des besoins du workflow éditorial.

Le symptôme apparaît vers le quatrième ou cinquième mois : des fonctionnalités qui devraient être simples exigent des contournements parce que la stack ne correspond pas naturellement au projet, ou l’équipe paie une taxe opérationnelle pour des capacités que le projet n’utilise pas. La correction, c’est de commencer les conversations d’architecture par la forme du projet et de laisser la technologie en découler, pas l’inverse.

Découper le système en plusieurs services, plusieurs bases de données, plusieurs déployables, dès le premier jour, parce que c’est à cela que ressemblent les architectures « modernes ». L’équipe n’a jamais fait tourner de système distribué auparavant, le projet a une seule équipe, et rien ne prouve encore que le découpage soit nécessaire, mais la présentation a un schéma microservices.

Le symptôme apparaît immédiatement : chaque changement exige de coordonner deux ou trois déploiements, l’environnement de développement local est hostile, et une release qui aurait pris une heure en monolithe prend une journée entière. La correction, c’est de commencer en monolithe, idéalement en monolithe modulaire, et d’extraire des services seulement quand le nombre d’équipes, les incidents de rayon d’impact ou les besoins de passage à l’échelle le justifient réellement.

Concevoir le système pour un million d’utilisateurs quand le plafond réaliste est dix mille. Ajouter une file, une couche de cache et un service mesh avant d’avoir la moindre preuve que l’un d’eux est nécessaire. Optimiser pour une charge qui existe dans une présentation, pas dans les logs d’accès.

Le symptôme, c’est une complexité opérationnelle que l’équipe ne peut pas absorber : trop de pièces mobiles, trop de dépendances en runtime, trop d’endroits où quelque chose peut mal tourner. La correction, c’est de construire pour la prochaine étape plausible, avec un chemin de mise à niveau propre, et de laisser la marge pour plus tard comme un choix délibéré plutôt qu’un investissement payé d’avance. La version honnête de la planification de capacité est dans l’article sur la plateforme scalable.

Des documents d’architecture qui plongent dans le choix de framework et le modèle de contenu et s’arrêtent à « on le déploiera quelque part ». La décision d’hébergement se prend la dernière semaine du projet, souvent par celui qui se trouve disponible, et les implications opérationnelles (qui est d’astreinte, comment marchent les rollbacks, où vont les logs, comment sont gérés les secrets) se décident la première semaine de production.

Le symptôme, c’est le déploiement qui dérape à 17h un vendredi et personne n’a l’accès ni le runbook pour le rattraper avant lundi. La correction, c’est de traiter l’hébergement et les opérations comme une partie de l’architecture dès la première conversation : qui le fait tourner, comment il se déploie, comment il est monitoré, comment il se rollback, et qui est appelé quand il casse.

Plusieurs parties du système écrivent dans les mêmes tables sans propriétaire clair. Du code applicatif lit directement les données d’un autre module parce que « c’est la même base de toute façon ». Des jobs en arrière-plan et des requêtes face à l’utilisateur touchent les mêmes lignes sans contrat documenté. La couche de données est traitée comme un tableur partagé plutôt que comme un système avec des frontières.

Le symptôme apparaît sous charge ou pendant un refactoring : un petit changement dans le modèle de données exige de mettre à jour cinq endroits dont personne ne se souvient, ou deux écritures se télescopent et la donnée finit incohérente d’une manière qu’il faut des semaines à démêler. La correction, c’est de donner à chaque table ou collection un seul module propriétaire nommé, d’interdire les lectures et écritures inter-modules, et de rendre tout accès qui franchit une frontière un appel API explicite.

Le système dépend de trois APIs externes, et les appels se font en ligne dans des requêtes face à l’utilisateur, sans timeout, sans politique de retry, sans circuit breaker, sans repli. L’intégration est traitée comme si le service externe était une fonction locale. Quand l’API tierce a un mauvais après-midi, le site face à l’utilisateur en a un pire.

Le symptôme, c’est le rapport d’incident qui remonte à un ralentissement chez un tiers que la plateforme a amplifié au lieu d’absorber. La correction, c’est de concevoir chaque intégration comme une vraie frontière : timeouts explicites, retry avec backoff, appels idempotents, chemins de repli pour les modes de panne connus, et monitoring qui distingue la latence propre de la plateforme de la latence du tiers en amont.

La phrase la plus chère dans toute décision d’architecture. Le hack CSS temporaire, l’identifiant en dur, la migration manquante, le changement de schéma qui exige un backfill, le test désactivé pour livrer le lancement. Chacun devait être quelques jours de nettoyage. Aucun n’est jamais nettoyé, parce qu’il y a toujours quelque chose de plus urgent, et le nettoyage devient silencieusement une dette structurelle.

Le symptôme, c’est le codebase qui a trente commentaires TODO et FIXME, dont aucun n’a de date ni de propriétaire, et l’équipe qui a cessé de leur faire confiance. La correction, c’est de refuser le cadrage « on corrigera plus tard » et soit de corriger maintenant, soit de créer un ticket avec un vrai propriétaire et une vraie date, soit d’accepter que c’est permanent et de mettre à jour la documentation d’architecture pour le dire. Le nettoyage fictif coûte plus cher que la dette honnête.

Les erreurs d’architecture sont prévisibles. La même poignée de schémas revient dans des projets de toutes tailles, et les reconnaître tôt est ce qui sépare les équipes qui construisent des plateformes qui vieillissent bien des équipes qui réécrivent le même système tous les deux ans. La discipline n’est pas d’être parfait ; c’est de garder le catalogue des erreurs récurrentes en tête, de les nommer quand elles apparaissent, et de traiter chacune comme une vraie décision plutôt qu’un défaut.

Le contexte plus large, dont les décisions de choix d’architecture, de découpage, de headless et de scalabilité que ces erreurs déforment le plus souvent, est rassemblé dans le cluster architecture web et plateformes. Et lorsque la question passe de « faisons-nous l’une de ces erreurs » à « nous reconnaissons le symptôme et il nous faut maintenant quelqu’un pour concevoir la correction sans casser ce qui marche actuellement », c’est exactement ce sur quoi mon accompagnement développement d’API et intégration de systèmes est centré.