radarsargasses/claude.md

🧠 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