# Architecture, SSR et routes

## Architecture retenue

TypeScript, React et Vinext sur le starter Sites, avec App Router et Worker serveur. La couche serveur produit le HTML des pages et des résultats de recherche. Il ne s'agit pas d'un index.html unique vide rempli seulement par JavaScript. Les routes de contenu et la recherche utilisent force-dynamic ; les métadonnées sont produites côté serveur. Les composants interactifs sont limités aux favoris, à la carte, au dialogue guidé et aux préférences d’accessibilité.

La provenance technique du SSR doit être complétée par la recette HTTP : contenu, H1, canonical, title et JSON-LD recherchés dans la réponse sans exécuter JavaScript. Le Worker n'est pas un export statique. La vérification de déploiement utilise l'état retourné par Sites.

## Organisation et décisions

- app/ contient les routes et les pages, components/site/ les éléments d'interface.
- data/ contient les données éditoriales versionnées et lib/ les règles communes.
- docs/ garde les sources et décisions durables. public/images/ contient les visuels optimisés.
- Les données de la première version restent en fichiers versionnés. Aucun faux back-office, faux compte ou fausse base persistante n'est livré.
- Pour les imports et l'administration à venir : D1 et R2 disponibles sur l'hébergement Sites, à provisionner si retenus. PostgreSQL reste une option externe via HTTP ; un Worker ne doit pas dépendre de TCP brut.
- Le moteur courant est déterministe, avec correspondance textuelle et dictionnaire simple. Il ne remplace ni un vrai index à tolérance aux fautes ni un assistant de langage.

## Arborescence active

| Intention | URL |
| --- | --- |
| Accueil | / |
| Page pilier | /idees-cadeaux-noel/ |
| Destinataires | /cadeau-noel-femme/, /cadeau-noel-homme/, /cadeau-noel-enfant/, /cadeau-noel-ado/, /cadeau-noel-couple/ |
| Collègues et échange | /secret-santa/ |
| Budget | /cadeaux-par-budget/ puis moins-de-10-euros/, moins-de-20-euros/, moins-de-30-euros/, moins-de-50-euros/, moins-de-100-euros/ |
| Passions éditoriales | /cadeaux-par-passion/ puis creation/, cuisine/, lecture/ |
| Autres passions | /recherche/?passion=… ; pas de page indexable artificielle |
| Discussion guidée | /assistante/?q=… (noindex) |
| API de recherche | /api/recherche/?q=… et filtres ; JSON, sans cache |
| API de dialogue | POST /api/assistante/ ; JSON, sans cache ; aucun modèle externe |
| Aide à la lecture | /accessibilite/ et panneau commun |
| Recherche | /recherche/?pour=…&age=…&budget=…&passion=…&type=…&q=… |
| Fiche idée | /cadeaux/[slug]/ |
| Guides | /guides/ et /guides/[slug]/ |
| Solidarité | /offrir-un-don/ et /offrir-un-don/fondation-flavien/ |
| Carte personnelle | /carte-solidaire/ |
| Calendrier de l’Avent | /calendrier-de-l-avent/ ; 24 cases natives details/summary, SSR |
| Favoris locaux | /favoris/ |
| Informations | /a-propos/, /confidentialite/, /mentions-legales/ |
| Suivi de travail privé | /projet/ et /dossier/ |
| Technique | /sitemap.xml et /robots.txt |

Les futures sous-catégories du brief sont un backlog, pas des pages vides. Les URLs historiques utiles pourront remplacer ces routes nouvelles après validation du mapping.

## SEO

- Un H1 par page ; titles et descriptions spécifiques.
- Canonicals absolus fondés sur l'origine effectivement déployée, à remplacer après validation du domaine.
- Pas d'année dans les URLs pérennes.
- JSON-LD WebSite, CollectionPage, ItemList, BreadcrumbList et Article selon le contenu.
- Aucun Product/Offer, prix actuel, stock, avis ou note structurée sans produit commercial vérifié.
- Aucun FAQPage ajouté seulement pour espérer un résultat enrichi.
- Pages de recherche, favoris, carte, dossier et mentions privées exclues du sitemap.
- En phase privée, noindex global, robots bloquant et sitemap vide, afin de ne pas lister des pages non indexables. La liste des routes éligibles est centralisée dans lib/routes.ts.
- Après ouverture : basculer INDEXABLE, contrôler le domaine canonique et soumettre le sitemap, seulement après la recette de migration.

## HTTP

data/http-rules.json contient les redirections 301 et suppressions 410 explicitement approuvées. Il est vide par défaut. Les propositions de la table de migration ne sont pas automatiquement appliquées. Le Worker traite ces règles avant le rendu et ajoute les en-têtes de protection de base. Les slugs inconnus doivent répondre 404, pas afficher l'accueil avec un statut 200.

## Ajouter un moteur de recherche

`lib/search/engine.ts` définit SearchEngine et SearchResult. Le moteur local est partagé par le rendu serveur de /recherche/, l’API GET et le dialogue. Pour le remplacer par un index externe : implémenter le contrat, rendre les appels asynchrones dans les trois consommateurs, conserver les mêmes filtres et IDs canoniques, gérer délais et panne, et exécuter la recette des contraintes et zéros résultats. Les éventuels secrets restent côté serveur. Aucun service externe n’est connecté ; ce contrat est un point d’extension de code, pas une interface d’administration déjà livrée.

## Extension Noël en famille

Routes cibles, contenu SSR, médias, jeux côté navigateur et modèles documentés dans ../01-cadrage/noel-en-famille-et-avent.md. Seul /calendrier-de-l-avent/ est actif dans cette extension ; les autres rubriques ne sont pas encore des pages publiées.