JWE/docs/architecture.md

JWE v2 — Décisions d'architecture (Agent Architecte)

Date : 2026-07-16 · Mission : refonte GeoGuessr souverain (voir projet_geoguessr_97x.md)

1. Décision back-end : SvelteKit seul (pas de Strapi)

Décision : SvelteKit seul, avec les lieux dans un fichier JSON versionné dans Git.

Arguments :

• Frugalité OKI : un seul processus Node à héberger, pas de CMS + admin + DB à maintenir, pas de surface d'attaque supplémentaire. SQLite serait de toute façon peu utile pour un corpus de ~40 lieux statiques.
• Critère du prompt (« qui ajoute les lieux ? ») : le corpus est éditorial, produit par l'Agent Contenu et relu. Le workflow Git (pull request = relecture + crédits photos vérifiés) est la modération. Le docs/contribution.md documente l'ajout d'un lieu par PR.
• Livrables finaux : le guide de déploiement demandé est « SvelteKit + Tile Server » — Strapi n'y figure pas.
• Anti-triche : le JSON reste côté serveur (src/lib/server/), jamais importé par le client ; les endpoints filtrent les champs. Impossible de faire plus simple.

Si un jour des contributeurs non-dev doivent saisir des lieux en masse, la porte vers Strapi reste ouverte (le schéma JSON est le content-type tout désigné), mais ce n'est pas le besoin actuel.

2. Architecture des tiles MapLibre

• Rendu : MapLibre GL JS (verrouillé), chargé en lazy (import dynamique uniquement sur les écrans de jeu / exploration).
• Dev / démo : tiles vectorielles OpenFreeMap — libres, basées OpenStreetMap, sans clé API. Style custom OKI (JSON de style propre, dérivé du style Positron, re-teinté : mer bleu profond caraïbe, terre sable, végétation verte dense, labels sobres — pas le « bleu Google »).
• Prod auto-hébergée : tileserver-gl + extraits .mbtiles OpenStreetMap des 4 régions (Guadeloupe, Martinique, Guyane, La Réunion — quelques dizaines de Mo au total). Procédure dans docs/deploiement.md. Le style OKI accepte l'URL des tiles par variable d'environnement (PUBLIC_TILES_URL), bascule sans changement de code.
• Contrainte géographique : maxBounds = enveloppe union des 4 régions (≈ lon −63…57, lat −23…18) + minZoom, donc impossible de scroller en Europe/Amérique du Nord. 4 boutons « saut de région » (GUADELOUPE / MARTINIQUE / GUYANE / RÉUNION) replacent la vue sur la région. Limite connue : l'enveloppe rectangulaire inclut l'Atlantique tropical et le Brésil — inoffensif (aucun indice sur le lieu), documenté.
• Attribution © OpenStreetMap contributors affichée.

3. Stratégie Wikipedia / Wikidata

Principe : rien de stocké en base, interroge l'API en temps réel avec cache court, côté serveur uniquement.

Endpoint serveur : GET /api/wiki/[qid] (ex. Q3077840 = Fort Delgrès — l'exemple Q2216838 du prompt initial était erroné, corrigé par l'Agent Contenu)

1. wbgetentities sur www.wikidata.org → récupère le sitelink frwiki (et le libellé fr en fallback). Fallback de langue : fr uniquement — décision d'audit (A3) : pas de repli sur enwiki, on préfère l'appel à contribution qu'une redirection silencieuse vers l'anglais.
2. GET https://fr.wikipedia.org/api/rest_v1/page/summary/{titre} → title, extract, content_urls, thumbnail.
3. Réponse normalisée : { qid, title, extract, url, thumbnail, description }.
4. QID sans sitelink frwiki → 404 {"reason":"no-frwiki"} (cas intermédiaire, A3) : le front affiche la variante Cas B « Pwen blindé — Pa nyen an fransé » (la fiche Wikidata existe, l'article français reste à traduire/créer ; CTA recherche pré-remplie + lien vers la fiche Wikidata). wikidata_id null côté lieu → Cas B « lacune totale » inchangé.
5. Cache : Map en mémoire, TTL 24 h + Cache-Control: max-age=86400. User-Agent explicite (JWE-OKI/x.y (contact)) comme demandé par la politique Wikimédia.

4. Arborescence du projet

JWE/                          (dépôt existant — l'ancien PHP est conservé tel quel)
├── app/                      ← nouvelle application SvelteKit 2 / Svelte 5
│   ├── src/
│   │   ├── lib/
│   │   │   ├── server/
│   │   │   │   ├── lieux.ts        (accès données + sélection aléatoire + scoring)
│   │   │   │   └── data/lieux.json (corpus 40 lieux — serveur uniquement)
│   │   │   ├── components/         (GameMap, PhotoPanel, ResultPanel, ScoreCard…)
│   │   │   ├── i18n/               (fr.ts, gcf.ts, store)
│   │   │   ├── styles/oki.css      (tokens couleurs OKI)
│   │   │   └── utils/              (score.ts, geo.ts)
│   │   ├── routes/
│   │   │   ├── +layout.svelte      (header, switch langue FR/CR)
│   │   │   ├── +page.svelte        (accueil : 4 régions, modes, Jouer)
│   │   │   ├── jeu/[mode]/         (écran de jeu split photo/carte)
│   │   │   ├── explorer/           (mode Aprann : carte pleine page)
│   │   │   └── api/
│   │   │       ├── round/+server.ts      (GET : lieu aléatoire SANITISÉ)
│   │   │       ├── photo/[id]/+server.ts (GET : proxy photo sharp → WebP, sans EXIF, cache 24 h)
│   │   │       ├── guess/+server.ts      (POST : {placeId, lat, lon, hints, timeMs} → score + vérité)
│   │   │       ├── lieux/+server.ts      (GET : catalogue sanitise pour Explorer, SANS id)
│   │   │       └── wiki/[qid]/+server.ts (GET : extrait Wikipedia, cache 24 h)
│   │   ├── app.html / app.d.ts
│   │   └── service-worker.ts       (PWA)
│   ├── static/                     (manifest.webmanifest, icônes, photos éventuelles)
│   └── package.json / svelte.config.js / vite.config.ts
├── docs/                         (architecture, déploiement, contribution, audit)
├── content/                      (sources de travail de l'Agent Contenu : crédits photos)
└── projet_geoguessr_97x.md

5. Spécifications API REST (anti-triche)

Endpoint	Méthode	Payload	Réponse
/api/round?region=&mode=&exclude=	GET	—	{ id, nom, nom_creole, categorie, difficulte, photo{url,credit,alt,srcset}, indices[] } — jamais coordonnees, commune, region, wikidata_id. photo.url = /api/photo/<uuid> (opaque, proxy serveur — C4) + photo.srcset { "400", "800", "1200" }
/api/photo/[id]?w=	GET	w ∈ {400, 800, 1200} (défaut 1200)	image/webp retraitée (sharp : rotation auto, métadonnées EXIF/GPS supprimées), Cache-Control: public, max-age=86400, immutable, cache mémoire 24 h. 404 si id inconnu, 400 si w invalide. Fetch amont = URL Commons du corpus uniquement (pas de proxy ouvert)
/api/guess	POST	{ id, lat, lon, hintsUsed, timeMs? }	{ distanceKm, score, radiusEffKm, coordonnees, commune, region, nom, wikidata_id }
/api/lieux	GET	—	Catalogue sanitise pour Explorer (coords arrondies à 0.05°, mode sans score). Sans id (anti-corrélation round → commune, C4) ; photos en URLs Commons directes (mode sans enjeu)
/api/wiki/[qid]	GET	—	{ title, extract, url, thumbnail }, Cache-Control: max-age=86400 ; 404 {"reason":"no-frwiki"} si QID sans article frwiki

Règles :

• Le scoring est recalculé côté serveur : score = round(5000 × e^(−d/r_eff)) avec r_eff = max(r_difficulté, sqrt(aire_commune_km2 / π)) quand le champ optionnel aire_commune_km2 est renseigné (A1 — équité Guyane : communes immenses), sinon r_difficulté seul (50/15/5/1 km). Pénalité −10 %/indice, bonus temps ≤ +20 % plafonné à 5000. radiusEffKm (0,1 km) est renvoyé pour transparence.
• Distance : haversine.
• Le client ne reçoit la vérité (coordonnées, commune, wikidata_id) qu'après la soumission du marqueur.
• exclude : liste d'ids déjà joués (mode Défi 5 rounds, stateless — pas de session serveur nécessaire, pas de leaderboard).

6. Décisions annexes

• Adapter : adapter-node (auto-hébergement sobre derrière nginx/caddy).
• PWA : manifest + service worker minimal (cache app shell, photos en stale-while-revalidate).
• i18n : dictionnaires maison fr / gcf (créole), store Svelte, lang persistée en localStorage.
• Photos : en mode jeu, proxy serveur /api/photo/[id] (C4 — l'URL Wikimedia Commons contient le nom du fichier, souvent un spoiler, et les EXIF peuvent embarquer du GPS) : le serveur fetch l'URL Commons du corpus, retraite avec sharp (rotation auto, suppression de toutes les métadonnées par défaut, WebP, largeurs 400/800/1200), cache mémoire 24 h + Cache-Control: immutable. PhotoPanel utilise <img src srcset sizes>. L'Explorer (/api/lieux) garde les URLs Commons directes (mode sans enjeu) et le service worker met en cache les deux origines.
• A11y / calm tech : prefers-reduced-motion respecté (pas de vol de marqueur), timer informatif non anxiogène, navigation clavier (carte : flèches déplacent le marqueur, Entrée valide).
• Licence code : MIT (le dépôt historique était AGPL — la refonte est un nouveau module app/ sous MIT comme exigé par le prompt ; le LICENSE racine reste l'historique, un app/LICENSE MIT est ajouté).

7. Correctifs d'audit (2026-07-17)

• C4 — URLs photo spoiler : voir §6 « Photos » et §5. Deux fuites colmatées : le nom de fichier Commons dans photo.url (remplacé par le proxy opaque /api/photo/<uuid>) et la corrélation id round ↔ id catalogue (/api/lieux n'expose plus d'id ; l'Explorer utilise des indices éphémères côté client).
• A1 — Radius de score en Guyane : voir §5 « Règles ». aire_commune_km2 (champ optionnel du schéma) élargit le rayon effectif : sqrt(aire/π). Test de référence : Saint-Laurent-du-Maroni (4320,8 km², EXPERT), guess à 40 km → radiusEffKm 37,1, score ≈ 1700 (au lieu de ≈ 0). Le code tolère l'absence du champ.
• A2 — Pas de fuite de région : la caméra initiale de GameMap est globale (center: [-58, 0], zoom: 3.6 — vue d'ensemble des 4 régions, aucun indice sur le lieu). Les 4 boutons région sont la devinette en deux temps : étape 1 = sauter vers la région supposée, étape 2 = poser le marqueur. Les deux étapes sont combinées par la distance seule : mauvaise région → distance énorme → score ≈ 0. Aucune donnée serveur ne révèle la région avant le guess (/api/round ne l'inclut pas).
• A3 — Chaîne Wikipedia : voir §3. Cache-Control: max-age=86400 ; cas intermédiaire QID sans frwiki → 404 {"reason":"no-frwiki"} → variante Cas B dédiée côté front ; fallback de langue fr uniquement, documenté dans le code.

8. Phase 2 (2026-07-17) — ADR-001 v1 et ADR-002

• ADR-001 v1 — Défi par lien à seed (/defi/<seed>) : src/lib/server/tirage.ts (hash cyrb53 → PRNG mulberry32, Fisher-Yates déterministe, contraintes ≥1 MONUMENT / ≥1 LIEU / ≥2 régions par échanges déterministes — zéro Math.random, déterminisme inter-machines). GET /api/defi/[seed] → 5 rounds sanitisés identiques pour tous (no-store, seed alphanumérique 4–40). Accueil : « Créer un lien de défi » (seed 8 chars sans ambiguïté). Bilan : « Copier le lien du défi ». La comparaison des scores reste humaine (image canvas) — zéro compte, zéro état serveur, zéro leaderboard. La v2 temps réel (PlaySocketJS) reste conditionnée au gate de traction de l'ADR (≥30 parties/sem. ×4 sem. + ≥5 demandes explicites).
• ADR-002 — Carte SVG légère hors-jeu : pipeline app/scripts/build-carte-regions.mjs (geo.api.gouv.fr → mapshaper 7 % → src/lib/map/regions-geo.json, 91,8 KB gz ≤ 150 KB) ; composant CarteRegions.svelte from scratch (SVG, projection équirectangulaire par inset, 2×2 responsive, <button> par région avec aria-label FR/créole, SSR sans JS, prop marqueurs pour le récap guess→réel, attribution © OSM/données publiques). Utilisée sur l'accueil (sélection de région) et les bilans défi — MapLibre reste strictement aux écrans de jeu (devinette, résultat, explorer). Attribution : contours © geo.api.gouv.fr / données publiques.

9. Correctif UX résultat (2026-07-17)

• Carte résultat façon GeoGuessr : à la révélation, le marqueur du joueur reste à sa position (corail) et la position réelle apparaît (vert), reliées par une ligne pointillée avec étiquette de distance au milieu (distanceKm) ; la carte cadre les deux points (fitBounds, instantané si prefers-reduced-motion). Remplace l'ancien « vol » du marqueur vers la position réelle, qui détruisait la comparaison visuelle. Prop distanceKm ajoutée à GameMap (alimentée par la réponse serveur, jamais calculée côté client).

10. ADR-003 — Mode street « An lari a » via Mapillary (2026-07-18)

5e mode de jeu : le joueur voit une photo street-level navigable (visionneuse Mapillary) au lieu d'une photo statique, et devine la commune. Mécanique carte + guess + score inchangée.

• Pourquoi Mapillary : seule source de street-level imagery couvrant correctement les 4 régions (bonne couverture Gwada/Martinique/Réunion, littoral guyanais) ; images CC BY-SA 4.0, lib mapillary-js MIT, API gratuite (token client requis, rate-limité par app). Exception documentée à « zéro service tiers » (Mapillary = plateforme Meta), limitée à ce mode ; alternative souveraine future = Panoramax (reco R4 audit passe 2), couverture DOM encore insuffisante à cette date.
• Corpus curé, pas de tirage aléatoire dans l'API : app/src/lib/server/data/street.json (20 lieux, 5/région), produit par app/scripts/curate-street.mjs (bbox < 0,01° ou grille de recherches par rayon autour de la mairie — le centroïde geo.api tombe souvent hors du centre-ville ; tri qualité/récence, préférence 360°), revérifié par app/scripts/validate-street.mjs (image existe, computed_geometry < 100 m, crédit auteur, sitelink frwiki). La vérité terrain (coordonnees) est figée dans le corpus (dérive possible de computed_geometry côté Mapillary).
• Phase éducative par commune : wikidata_id = QID de la commune (un coin de rue n'a pas vocation à avoir sa page) → WikiFiche réutilisé tel quel, aucune variante Cas B nouvelle. aire_commune_km2 renseigné (équité Guyane, A1).
• Anti-triche : /api/round?mode=street + sanitizeRoundStreet() — seuls id, nom, nom_creole, categorie, difficulte, mapillaryId, credit, indices partent ; coords/commune/région/wikidata_id jamais avant le guess. Limitation assumée : l'image_key est publique (la visionneuse appelle Mapillary depuis le navigateur) → un joueur techniquement équipé peut retrouver la position via l'API Mapillary (même propriété que GeoGuessr/Street View ; acceptable en solo sans leaderboard). La visionneuse n'affiche pas de carte (mapillary-js n'en a pas par défaut), donc aucun spoiler visuel.
• Visionneuse : StreetPanel.svelte, lazy load façon MapLibre (import('mapillary-js') + CSS — chunk séparé ~1 MB, 0 occurrence dans le bundle initial), component.cover: false, moveTo() avec état d'erreur (image retirée → message + round suivant possible). Token PUBLIC_MAPILLARY_TOKEN via $env/dynamic/public (pattern PUBLIC_TILES_URL) : token client, conçu par Mapillary pour être exposé côté navigateur.
• Réutilisation sans modification : GameMap, ResultPanel, WikiFiche, scoring (scoreGuess/skipResult acceptent Lieu | StreetLieu), timer, indices, bouton « Passer ». RoundPlace.photo devient optionnel (mapillaryId/credit ajoutés) ; lookup unifié getLieuById (2 corpus) pour /api/guess, getLieuPhotoById conservé pour le défi et le proxy photo.
• Hors scope v1 : street dans /defi/[seed] et /explorer, cache SW des tuiles Mapillary (les requêtes graph.mapillary.com/FBCDN passent en direct).