radarsargasses/docs/architecture.md

ARCHITECTURE — Sargasse-Sentry

Stack technique

Couche	Technologie	Rôle
Backend	Symfony (PHP)	API JSON, crons, pipeline
Frontend	React SPA	Interface utilisateur
Maps	MapLibre GL JS + react-map-gl	Rendu cartographique
Base de données	PostgreSQL + PostGIS	Données géospatiales
Vector tiles	Tippecanoe (génération)	Tiles statiques pré-générées
Cache	Redis	Scores, résultats API
Reverse proxy	Traefik	Routage multi-tenant, SSL
Runtime PHP	FrankenPHP	Remplace php-fpm + nginx
Conteneurisation	Docker	Isolation, déploiement

---

Infrastructure

Hébergement

VPS personnel, architecture multi-tenant Docker + Traefik + FrankenPHP (configuration existante partagée entre projets).

Internet
    └── Traefik (reverse proxy, SSL Let's Encrypt)
            ├── sargasse-sentry.tld → container Symfony/FrankenPHP
            ├── [autres projets]
            └── ...

Containers Sargasse-Sentry :
    ├── frankenphp   (Symfony API + worker cron)
    ├── postgres     (PostgreSQL + PostGIS)
    └── redis        (cache)

CDN (optionnel, sans coût)

Cloudflare free tier peut être activé devant Traefik pour mettre en cache les vector tiles statiques et les réponses HTTP publiques. Aucun coût.

---

Architecture applicative

Backend — Symfony API

Symfony n'expose que du JSON (pas de Twig). Deux responsabilités :

1. API REST — endpoints consommés par le frontend React
2. Pipeline — crons + workers de traitement satellite

Frontend — React SPA

Application React statique servie par FrankenPHP (ou Traefik directement). Consomme l'API Symfony et affiche les vector tiles via MapLibre GL JS.

---

API Endpoints

Spots & scores

GET  /api/spots                          Liste des CoastalPoints
GET  /api/spots/{id}                     Détail d'un CoastalPoint
GET  /api/spots/{id}/score               ImpactScore courant + horizons
GET  /api/spots/{id}/score?at={datetime} Score à un instant donné

Observations & prédictions

GET  /api/observations?bbox={bbox}&date={date}   Observations dans une zone
GET  /api/observations/{id}                       Détail observation
GET  /api/forecasts?observationId={id}            Prédictions d'une observation
GET  /api/forecasts?bbox={bbox}&horizon={h}       Prédictions par zone + horizon

Feedback

POST /api/feedback                       Soumettre un UserFeedback anonyme

Tiles (statiques, hors API)

GET  /tiles/observations/{z}/{x}/{y}.pbf
GET  /tiles/forecasts/{horizon}/{z}/{x}/{y}.pbf

---

Vector Tiles

Stratégie : Tippecanoe + tiles statiques

• Les observations et prédictions sont converties en tiles .pbf après chaque ingestion (via Tippecanoe)
• Les tiles sont stockées sur le filesystem du VPS et servies statiquement
• Pas de rendu dynamique à la volée (Tegola écarté — complexité non justifiée au MVP)
• Cloudflare free tier peut mettre ces tiles en cache si activé

Interdits

• GeoJSON brut exposé en production sur des géométries complexes

---

Caching

Données	Stratégie	TTL suggéré
Scores par spot	Redis	3h (durée du cycle d'ingestion)
Résultats API observations	Redis	3h
Vector tiles statiques	HTTP Cache + Cloudflare	Long (invalidation à chaque ingestion)
Endpoints publics	HTTP Cache	15–30 min

Règle : 1 requête = 1 zone + 1 timestamp, pas de recalcul à la volée.

---

Sécurité

• Rate limiting sur tous les endpoints publics (Symfony RateLimiter)
• Aucune donnée personnelle collectée (UserFeedback = fingerprint anonyme)
• Retry automatique pipeline avec backoff
• Logs structurés sur chaque DataIngestionJob
• Secrets (clés API Sentinel Hub, NOAA) via variables d'environnement Docker

---

Schéma de flux de données

Sentinel Hub API
    └── Cron Symfony (3h)
            └── DataIngestionJob
                    ├── Calcul AFAI → SargassumObservation
                    │       └── Tippecanoe → tiles statiques /tiles/observations/
                    └── Simulation dérive → SargassumForecast (×4 horizons)
                            ├── Calcul ImpactScore par CoastalPoint → Redis
                            └── Tippecanoe → tiles statiques /tiles/forecasts/

NOAA GRIB API
    └── (consommé pendant la simulation de dérive)

React SPA
    ├── MapLibre GL JS → /tiles/...pbf
    └── Symfony API    → /api/spots/{id}/score