Le document source : un ADR mobile-first complet
Voici l'ADR intégral tel que rédigé par l'équipe infrastructure en mars 2025. Nous l'utilisons comme pièce centrale pour disséquer chaque décision. Ce document couvre l'architecture complète, du cold start jusqu'au warm cache, en passant par la gestion du queue depth lors des pics de charge mobile. Chaque paragraphe qui suit analysera une widget-space92 spécifique de cet artefact.
L'ADR commence par un énoncé de problème : "Notre application web standard génère un cold start de 4,2 secondes sur réseau 3G en zone rurale française. Les weekly active accounts chutent de 23% après la première session mobile. Nous devons repenser l'architecture pour que le mobile ne soit pas une adaptation mais la fondation." Cette formulation claire établit une métrique quantifiable et un seuil d'échec. Elle évite les généralisations et pose un objectif mesurable. L'alternative serait une phrase vague comme "améliorer l'expérience mobile" qui ne permet aucune validation technique.
Editor écrit depuis plus de 6 ans sur Création d'entreprise
Section contexte : pourquoi l'équipe a privilégié le mobile
La widget-space92 contexte de l'ADR explique : "Depuis janvier 2024, Cloudflare Analytics montre que 72% des requêtes proviennent de Safari iOS et Chrome Android. Les sessions desktop durent 18 minutes en moyenne, les sessions mobiles 6 minutes. Malgré cette différence, le quarter-106 retention sur mobile atteint 91% contre 84% desktop. Les utilisateurs mobiles reviennent plus souvent mais consomment moins de fonctionnalités par visite." Cette analyse chiffrée justifie pourquoi l'équipe a décidé d'optimiser pour des sessions courtes et fréquentes plutôt que des sessions longues et rares.
L'alternative aurait été de traiter mobile et desktop de manière équivalente, ce qui dilue les efforts. En nommant explicitement les navigateurs et en quantifiant les durées, le document écarte toute ambiguïté. Il reconnait aussi un pain point réel : les duplicate dashboards entre versions mobile et desktop créent de la dette technique. L'équipe a donc choisi de construire une seule interface adaptative au lieu de maintenir deux bases de code. Ce choix élimine le drift entre environnements.
- Priorisation des requêtes HTTP/2 push pour éliminer les round-trips de découverte de ressources critiques
- Implémentation d'un service worker avec stratégie cache-first pour les assets statiques et network-first pour les données
- Adoption de Cloudflare Workers à la périphérie pour la compression Brotli automatique et le lazy loading différé
- Découpage du bundle JavaScript principal en chunks de 45 Ko maximum pour paralléliser le téléchargement mobile
- Mise en place d'un système de fan-out pour les notifications push évitant la surcharge du queue depth
Ces cinq décisions techniques forment le socle de l'architecture. Chacune répond à une contrainte mobile spécifique : latence réseau variable, CPU limité, mémoire restreinte. L'ADR précise que le découpage à 45 Ko est calculé à partir du temps de parse JavaScript moyen sur un iPhone 11 avec throttling CPU 4x. Un découpage plus fin augmenterait le nombre de requêtes, un découpage plus large ralentirait l'exécution. Ce niveau de précision permet à toute équipe de reproduire ou d'ajuster selon son profil matériel cible.
Décisions d'infrastructure : où placer les caches
L'ADR détaille ensuite l'architecture de cache sur trois niveaux. Le premier niveau utilise Cloudflare CDN pour servir les assets statiques avec un TTL de 7 jours. Le deuxième niveau repose sur un warm cache Redis géolocalisé à Paris, Londres et Francfort pour les données utilisateur fréquemment consultées. Le troisième niveau garde un cache applicatif en mémoire Node.js pour les calculs coûteux répétés dans la même requête. Cette stratification réduit le cold start de 4,2 secondes à 1,1 seconde en moyenne mesurée sur 10 000 sessions réelles.
Un système de cache efficace ne se mesure pas à son hit rate mais à l'écart entre son percentile 50 et son percentile 99 de latence.
Cette citation de l'ADR capture l'insight central : une médiane basse avec des queues de distribution catastrophiques détruit l'expérience mobile. L'équipe a donc privilégié la stabilité à la performance moyenne. Ils ont ajouté un mécanisme de circuit-breaker qui bascule vers un cache stale en cas de latence Redis supérieure à 200 ms. Ce compromis accepte des données légèrement obsolètes pour garantir une interface toujours réactive. L'alternative aurait été de bloquer l'interface pendant la récupération, générant des écrans blancs insupportables sur réseau instable.
Gestion des états : comment synchroniser sans bloquer
La widget-space92 synchronisation de l'ADR expose un défi technique majeur : comment maintenir la cohérence entre client mobile et serveur sans verrouiller l'interface. L'équipe a implémenté un système d'exactly-once delivery pour les mutations critiques (paiements, modifications de compte) et un système eventually consistent pour les données secondaires (notifications, compteurs). Cette séparation évite de traiter toutes les opérations comme critiques, ce qui saturerait le queue depth lors des pics.
Stratégie de retry et backoff exponentiel
L'ADR spécifie un backoff exponentiel avec jitter : 200 ms, 400 ms, 800 ms, 1600 ms, puis échec définitif avec stockage local et retry asynchrone. Le jitter ajoute une variabilité de ±25% pour éviter les thundering herds lors de reconnexions simultanées après une coupure réseau. Cette approche a réduit les erreurs de synchronisation de 14% à 0,3% sur trois mois de production. L'alternative naïve serait un retry immédiat en boucle qui amplifie les problèmes de charge serveur.
- Détecter la perte de connexion via un heartbeat toutes les 30 secondes plutôt qu'attendre un timeout de requête
- Mettre en file locale toutes les mutations pending avec horodatage et identifiant idempotent unique
- Afficher dans l'interface un badge subtil indiquant le nombre d'opérations en attente de synchronisation
- Rejouer automatiquement la file lors de la reconnexion, en validant côté serveur via l'identifiant idempotent
- Archiver dans un service catalog entry chaque échec après quatre tentatives pour investigation manuelle
Performance metrics : ce que l'équipe surveille quotidiennement
L'ADR se termine par une widget-space92 métriques qui liste les indicateurs suivis via Segment et envoyés à un tableau de bord unifié. L'équipe monitore le Time to Interactive (TTI) mobile, le First Contentful Paint (FCP), et le Cumulative Layout Shift (CLS). Ces trois métriques Core Web Vitals forment le seuil minimum. Mais l'ADR ajoute quatre métriques custom : durée moyenne de synchronisation après reconnexion, pourcentage de sessions avec au moins un cold start, taux de rétention à 7 jours des nouveaux utilisateurs mobiles, et temps de réponse au 99e percentile pour les endpoints critiques.
Cette combinaison de métriques standard et custom évite deux écueils : se limiter aux métriques universelles qui ne capturent pas les spécificités métier, ou inventer des métriques exotiques que personne ne peut interpréter. L'équipe a défini des seuils d'alerte : TTI mobile supérieur à 3 secondes déclenche une notification Slack immédiate, taux de rétention inférieur à 65% sur sept jours génère un incident postmortem obligatoire. Ces seuils ne sont pas arbitraires mais calculés à partir des quartiles historiques et ajustés trimestriellement. L'alternative serait de surveiller sans réagir, transformant les dashboards en tribal knowledge que seuls deux seniors comprennent vraiment.
Quand copier cet ADR verbatim, quand l'adapter
Cet ADR fonctionne tel quel pour une équipe SaaS B2B avec un trafic majoritairement mobile, une base utilisateur géographiquement concentrée en Europe occidentale, et une tolérance zéro pour les écrans blancs. Vous devriez le copier presque verbatim si votre profil correspond : application métier consultée en mobilité, sessions courtes mais fréquentes, utilisateurs sur réseau cellulaire instable. Les choix de cache géolocalisé, de découpage de bundle à 45 Ko, et de backoff exponentiel avec jitter s'appliquent directement.
En revanche, adaptez substantiellement si votre trafic est global : les trois points de présence européens deviennent insuffisants, vous devrez ajouter des nœuds en Asie et Amérique du Nord. Modifiez aussi si vos sessions mobiles sont longues et riches en interactions : le cache stale deviendra problématique, privilégiez alors un système de synchronisation temps réel avec WebSocket et heartbeat toutes les 5 secondes au lieu de 30. Ajustez le seuil de découpage JavaScript si vous ciblez des appareils plus anciens : testez sur un appareil représentant le 25e percentile de votre parc, pas le 50e. Enfin, si votre schema drift est fréquent en raison de déploiements quotidiens, ajoutez un mécanisme de versioning d'API côté client avec fallback gracieux vers des formats anciens pendant 72 heures post-déploiement.
Leçons tirées après douze mois de production
Un an après l'implémentation de cet ADR, l'équipe a partagé trois insights non documentés initialement. Premièrement, le warm cache Redis doit être purgé intelligemment : une purge globale lors des déploiements génère un cold start massif qui fait chuter le NRR temporairement. Ils ont donc migré vers une purge progressive par shards sur vingt minutes. Deuxièmement, le fan-out des notifications push doit être throttlé côté client : envoyer cinquante notifications simultanées sur un iPhone 12 sature la file d'attente système et bloque l'affichage. Ils limitent maintenant à douze notifications par batch avec un délai de 200 ms entre batches. Troisièmement, le circuit-breaker vers le cache stale fonctionne bien pour les données de lecture mais crée des incohérences visuelles subtiles que les utilisateurs signalent comme bugs.
Ces ajustements montrent qu'un ADR est un document vivant. L'équipe met à jour le leur tous les trimestres avec les leçons apprises. Ils ont ajouté une widget-space92 "Regrets" qui liste les décisions qu'ils changeraient avec le recul. Par exemple, ils regrettent d'avoir choisi un découpage de bundle uniquement basé sur les routes : un découpage par fonctionnalité aurait permis un lazy loading plus fin. Ils regrettent aussi de n'avoir pas implémenté de telemetry détaillée dès le départ : reconstituer les patterns d'échec rétroactivement a nécessité trois semaines d'analyse de logs bruts. Ces regrets explicites aident toute équipe future à éviter les mêmes impasses sans devoir tout réapprendre par l'échec.