architecture-site-interactive

Architecture de Site Interactive

Résultat

Créez un site Next.js public, orienté production, dont le contenu, le récit, l'identité visuelle et la qualité d'interaction comptent. Il s'agit d'une architecture universelle pour les sites centrés sur le contenu : sites de marque et marketing, sites SaaS et produits, pages de lancement, propriétés éditoriales, portfolios, communautés, conférences, sites de documentation et vitrines immersives.

Le noyau est fixe :

• contenu rendu par le serveur ;
• îles client étroites ;
• contrats de contenu validés ;
• tokens de design et de mouvement partagés ;
• comportement natif du navigateur ;
• SEO et accessibilité dans la réponse serveur ;
• budgets de performance par route.

Sélectionnez les modules dont le produit a besoin :

Module	Utilisation
Collection et détail de contenu	Le site contient des projets, articles, produits, personnes, événements, ou enregistrements similaires
Portfolio ou études de cas	L'organisation a besoin de prouver son travail
Archive immersive	L'exploration visuelle est une surface produit principale
Boutique	Le site vend des produits numériques ou physiques
Adaptateur CMS	Les éditeurs publient indépendamment des versions
Formulaire de contact	Un lien mail ou un calendrier est insuffisant

N'imposez pas de modules optionnels à un site qui n'en a pas besoin.

Les profils typiques réutilisent le même noyau :

• SaaS ou produit : page d'accueil, offre, fonctionnalités, collection de contenu, documentation ou journal des modifications.
• Marque ou lancement : récit de campagne, révélation produit, liste d'attente, preuve sociale.
• Éditorial : index de collection, détail d'article, auteurs, sujets, recherche.
• Communauté ou conférence : intervenants, programme, sessions, lieu, billets.
• Portfolio : index de projet, détail d'étude de cas, archive visuelle, contact.
• Commerce : catalogue, détail produit, paiement, téléchargement ou livraison.

À lire avant d'agir

• Lisez references/architecture-contract.md pour chaque construction, refonte ou changement d'architecture.
• Lisez references/code-architecture.md avant de créer des dossiers, contrats, services, adaptateurs ou actions serveur.
• Lisez references/dependency-matrix.md avant d'installer, mettre à niveau ou supprimer des dépendances.
• Pour une nouvelle application, suivez references/build-playbook.md.
• Pour de nouvelles routes, types de contenu, îles, archives, produits de boutique ou migrations, suivez references/evolve-playbook.md.
• Avant l'acceptation ou la publication, suivez references/quality-gates.md.

Les modèles réutilisables se trouvent sous assets/templates/. Ne les utilisez que lorsqu'ils correspondent à l'architecture choisie. Ne copiez pas chaque modèle aveuglément.

Invariants non négociables

1. Gardez la composition des pages et le contenu principal dans des composants serveur par défaut.
2. Placez use client à la plus petite feuille viable. Animez les enfants rendus par le serveur via des wrappers client lorsque c'est possible.
3. Traitez les contrats de données TypeScript comme la source de vérité pour chaque entité de contenu, enregistrement de métadonnées, galerie et entrée de sitemap.
4. Donnez à chaque interaction de superposition une vraie route qui fonctionne sans état client, JavaScript ou dièse.
5. Utilisez d'abord le comportement HTML natif : liens, boutons, formulaires, <dialog>, gestion du focus et historique du navigateur.
6. Gardez les secrets dans des modules réservés au serveur. Seuls les identifiants publics peuvent utiliser NEXT_PUBLIC_*.
7. Lorsqu'il y a du commerce, gardez les prix, les décisions de droits, la confirmation de paiement et les téléchargements protégés sur le serveur.
8. Respectez prefers-reduced-motion, la navigation au clavier, le focus visible, les titres sémantiques et la lisibilité sans script.
9. Gardez le contenu d'une route hors du bundle client initial d'une autre route. Transmettez de petits résumés depuis le serveur lorsqu'une coque client a besoin d'un compteur ou d'un libellé.
10. Utilisez un monolithe modulaire avec des adaptateurs de route fins, des modules de fonctionnalités possédés, des ports explicites et une seule frontière de composition.
11. Préférez les dépendances stables. Ne démarrez pas une nouvelle application de production sur une version canary de React.

Pile par défaut

Utilisez les versions exactes validées dans la matrice de dépendances, sauf si le site a une raison documentée de s'en écarter.

• Famille Node 26 LTS et pnpm.
• Next.js App Router, React, React DOM, TypeScript.
• Tailwind CSS 4 pour les tokens, le reset et la mise en page utilitaire.
• CSS Modules pour la composition spécifique à une route ou un composant.
• Motion pour l'orchestration React et les gestes.
• Dialog natif, Canvas, SVG, CSS et Web Animations API pour les interactions où ils sont suffisants.
• Icônes Lucide importées individuellement.
• Zod pour les limites de contenu et d'entrée externe.
• Vercel pour le déploiement, les analyses et la livraison d'images.
• Stripe Embedded Checkout et actions serveur lorsque le commerce est requis.

Séquence de travail

1. Inventoriez les surfaces publiques : pages d'accueil, index de contenu, routes de détail, chemins de conversion, routes légales, recherche, archive et commerce.
2. Figez le manifeste des routes et la carte des limites client avant l'implémentation.
3. Attribuez les propriétaires de fonctionnalités, les ports, les adaptateurs de route et les adaptateurs externes avant de créer les fichiers.
4. Modélisez les entités de contenu et les médias requis avant de construire les sections.
5. Établissez les tokens globaux, la typographie, l'espacement, les états, le comportement de mouvement réduit et les conventions d'image.
6. Construisez la coque serveur, la navigation, les fallbacks de route et les métadonnées SEO.
7. Ajoutez les îles client une par une. Enregistrez pourquoi chacune doit être côté client.
8. Construisez les superpositions avec le dialogue natif et l'état URL. Ajoutez la route de page canonique en même temps.
9. Ajoutez les visuels complexes après avoir défini leurs données, leur fallback, leur comportement de mouvement réduit et leurs limites de performance.
10. Ajoutez le CMS, le commerce, les comptes ou la persistance uniquement lorsque le modèle d'exploitation le nécessite.
11. Exécutez la vérification des limites d'architecture, l'audit structurel, les tests ciblés, les portes de qualité et l'acceptation de la prévisualisation de production.
12. Rapportez séparément le comportement implémenté, les preuves vérifiées et les limitations non vérifiées.

Règles de décision

• Utilisez les transitions CSS pour le survol, le focus, l'appui, le dévoilement, le marquee et les changements d'état simples.
• Utilisez Motion pour les variantes coordonnées, les transitions de mise en page, le glisser, la présence et l'orchestration liée au défilement.
• Utilisez Canvas ou WebGL uniquement lorsque le visuel ne peut pas être exprimé de manière fiable avec le DOM, SVG et CSS. Ajoutez une pause de visibilité, des limites de DPR, un nettoyage, un comportement de mouvement réduit et un fallback statique.
• Gardez les collections de contenu rendues par le serveur. Envoyez uniquement des compteurs, des libellés ou des enregistrements sélectionnés à une coque de superposition client.
• Utilisez un <dialog> natif pour les aperçus et les feuilles lorsque le même contenu a également une page canonique. Utilisez une route dédiée pour le contenu profond, long ou lié indépendamment.
• Utilisez du contenu de code validé pour une petite équipe qui publie avec l'application. Introduisez un CMS derrière un adaptateur de référentiel lorsque les éditeurs ont besoin d'une publication indépendante.
• Utilisez une session Stripe sans état lorsque la boutique n'a besoin que d'un achat et d'un téléchargement immédiats. Ajoutez une base de données et des webhooks vérifiés lorsque le produit a besoin de droits, de remboursements, de comptes, d'historique des commandes ou de tentatives.
• Ajoutez Radix, shadcn ou une autre bibliothèque de composants uniquement après avoir identifié la primitive qu'elle possède. Les éléments natifs et les primitives appartenant au site sont la base de référence.
• Traitez les portfolios, archives et boutiques comme des modules. Ils réutilisent les contrats de base de contenu, de route, de style, de mouvement et de sécurité.

Artefacts de construction requis

Créez et maintenez ces artefacts au niveau du site :

• docs/architecture.md : carte des routes, limites client, propriété du contenu, services externes et budgets de performance.
• src/features/*/domain et src/features/*/application : contrats et capacités validés.
• src/platform/* : adaptateurs externes et racine de composition réservée au serveur.
• src/shared/* : contrats transversaux et primitives de design éprouvés.
• src/components/* : composition serveur et îles client avec des noms explicites.
• src/app/* : pages, layouts, métadonnées, sitemap, robots et gestionnaires de routes.
• .env.example : noms et objectif, jamais de vrais secrets.
• Tests pour la validation du contenu, les machines d'état client, les actions serveur et les parcours navigateur critiques.
• Une liste de contrôle de publication avec des preuves de prévisualisation, de navigateur, d'accessibilité, de performance, de SEO et de commerce conditionnel.

Audit structurel

Exécutez la vérification des limites d'architecture et l'audit groupé après l'échafaudage et avant la publication :

pnpm arch:check
node scripts/audit_site.mjs --root /path/to/app

Utilisez --strict en CI lorsque les avertissements doivent être bloquants. Le script vérifie la présence des dépendances, la structure des routes et du contenu, les risques de secrets client/serveur, les sauvegardes de dialogue et de mouvement, les tests, les fichiers SEO et l'exposition de la source map. Il complète les tests et ne les remplace pas.

Contrat d'achèvement

Une construction n'est terminée que lorsque :

• la carte des routes et des limites correspond à l'implémentation ;
• le graphe de dépendances est acyclique et arch:check réussit ;
• les routes utilisent les API publiques des fonctionnalités et la racine de composition possède le câblage ;
• l'application se construit sans surprises de canary ou de dépendances pair ;
• le contenu critique apparaît dans le HTML serveur ;
• les superpositions, menus et chemins clavier fonctionnent et restaurent le focus ;
• les fallbacks de mouvement réduit et sans script sont vérifiés ;
• les métadonnées, le sitemap, les robots, les URL canoniques et les images sociales sont présents ;
• les charges utiles JS et images de la route initiale restent dans les budgets documentés ;
• le commerce, lorsqu'il est présent, utilise des prix gérés par le serveur, une confirmation côté serveur et des téléchargements protégés ;
• les preuves de prévisualisation et de production sont enregistrées séparément.