Initial commit : docs (specs, data-model, architecture, roadmap)

claude.md

@@ -0,0 +1,202 @@
+# 🧠 Claude Project Context — Sargasse-Sentry
+
+## 🎯 Objectif du Projet
+
+Construire une plateforme de renseignement maritime capable de transformer des données satellites complexes en une information simple, fiable et immédiatement exploitable par des utilisateurs non techniques.
+
+Le projet doit privilégier :
+- la robustesse
+- la lisibilité
+- la performance
+- la maintenabilité long terme
+
+Toute décision technique doit être orientée vers ces objectifs.
+
+---
+
+## ⚙️ Stack Technique (NON NÉGOCIABLE)
+
+- Backend : Symfony 7.4 LTS (PHP 8.4+)
+- Database : PostgreSQL + PostGIS
+- Queue : Symfony Messenger + Redis
+- Cartographie : Mapbox GL JS
+- Cache : Redis + HTTP Cache
+- Traitement : PHP prioritaire, Python uniquement si nécessaire
+
+---
+
+## 🧱 Principes d’Architecture
+
+### 1. Séparation stricte des responsabilités
+
+- Observation ≠ Prédiction ≠ Score
+- Ne jamais mélanger ces concepts dans une même entité ou table
+
+---
+
+### 2. Aucune logique métier dans les contrôleurs
+
+- Utiliser des services
+- Utiliser des handlers Messenger pour les traitements lourds
+
+---
+
+### 3. Pipeline asynchrone obligatoire
+
+- Toute ingestion ou traitement doit passer par Messenger
+- Aucun traitement bloquant en requête HTTP
+
+---
+
+### 4. Données immuables
+
+- Une observation ne doit jamais être modifiée
+- Une prédiction est versionnée (modelVersion)
+
+---
+
+### 5. Optimisation géospatiale native
+
+- Utiliser PostGIS pour :
+  - distance
+  - intersection
+  - simplification
+- Ne jamais recalculer côté PHP si PostGIS peut le faire
+
+---
+
+## 📊 Conventions de Données
+
+### Géométrie
+
+- SRID : 4326 obligatoire
+- Utiliser MULTIPOLYGON même pour un seul polygone
+- Simplifier avant stockage
+
+---
+
+### Dates
+
+- Toujours en UTC
+- Utiliser DateTimeImmutable
+
+---
+
+### Identifiants
+
+- UUID pour toutes les entités critiques
+
+---
+
+## 🧠 Modélisation
+
+Claude DOIT créer des entités distinctes :
+
+- SargassumObservation
+- SargassumForecast
+- CoastalPoint
+- ImpactScore
+- DataIngestionJob
+
+Aucune fusion ou simplification n’est autorisée.
+
+---
+
+## 🌊 Pipeline
+
+Claude DOIT implémenter :
+
+1. Ingestion Sentinel
+2. Calcul AFAI
+3. Vectorisation
+4. Simulation de dérive par points
+5. Génération de prédictions multiples
+
+---
+
+## ⚠️ Contraintes critiques
+
+### 1. Performance
+
+- Interdiction d’envoyer du GeoJSON brut en production
+- Utilisation obligatoire de vector tiles
+
+---
+
+### 2. Cache
+
+- Toute donnée calculée doit être cachée
+- Aucun recalcul inutile
+
+---
+
+### 3. Résilience
+
+- Retry automatique sur ingestion
+- Gestion des erreurs obligatoire
+
+---
+
+## 🎯 UX Constraints
+
+Claude doit considérer que :
+
+- L’utilisateur ne comprend pas les données satellites
+- L’information doit être lisible en moins de 3 secondes
+
+Donc :
+
+- Toujours fournir un score simple
+- Toujours fournir une tendance
+- Toujours fournir un horizon temporel
+
+---
+
+## 🔁 Évolutivité
+
+Le système doit être conçu pour :
+
+- ajouter de nouvelles sources de données
+- améliorer le modèle de dérive
+- intégrer du machine learning
+
+Sans refonte complète.
+
+---
+
+## 🚫 Interdictions
+
+- Pas de logique métier dans les contrôleurs
+- Pas de calcul géospatial lourd en PHP si PostGIS peut le faire
+- Pas de dépendance inutile
+- Pas de complexité prématurée (microservices non nécessaires au MVP)
+
+---
+
+## ✅ Attentes vis-à-vis de Claude
+
+Claude doit :
+
+- générer du code propre, structuré, testable
+- respecter strictement les conventions
+- documenter les choix techniques
+- proposer des améliorations si pertinentes
+
+Claude ne doit PAS :
+
+- simplifier les modèles de données
+- ignorer les contraintes de performance
+- court-circuiter Messenger
+
+---
+
+## 🧭 Philosophie
+
+Ce projet n’est pas une simple application cartographique.
+
+C’est un système de renseignement environnemental.
+
+Chaque décision doit renforcer :
+- la précision
+- la fiabilité
+- la compréhension utilisateur