Projet Surf - App de prévision surf et conditions côtières 100% européenne

Conception de l'architecture et choix structurants

Avant d'écrire la moindre ligne de code, j'ai posé les décisions d'architecture qui allaient conditionner tout le projet.

J'ai découpé le projet en cinq dépôts spécialisés plutôt qu'un monolithe : un moteur de scoring en Python/FastAPI, une couche API en Java/Spring Boot, une application mobile Angular/Ionic, un backoffice Angular, et un dépôt d'orchestration Docker Compose. Ce découpage n'est pas qu'organisationnel : il matérialise une frontière de sécurité.

J'ai également tranché tôt sur le modèle produit : pas de compte utilisateur, aucune donnée personnelle collectée, et une stack reposant uniquement sur des fournisseurs européens (hébergement Scaleway Paris, IA Mistral, données Open-Meteo, SHOM et Puertos del Estado).

Modélisation des spots : le schéma Spot JSON V2

Chaque spot de surf est décrit par un fichier JSON structuré, avec des blocs geometry et conditions qui portent l'ensemble de la logique de calibration.

Ces fichiers sont versionnés dans Git et embarqués directement dans l'image Docker du moteur : Spring Boot n'effectue aucune lecture de fichier JSON, il fonctionne à 100% sur base de données. Seul FastAPI a légitimement accès aux paramètres de calibration.

• 319 spots seedés en base PostgreSQL, avec un identifiant public découplé des identifiants OpenStreetMap ;
• une colonne city renseignée sur 317 spots sur 319 ;
• un principe strict : aucune donnée n'est inventée, un champ sans source confirmée reste à null, avec une traçabilité de la provenance via verification.sources.

Construction du moteur de scoring déterministe

C'est le cœur différenciant du projet : un système de notation à deux étages plutôt qu'une estimation par modèle de langage.

Cette moyenne pondérée est ensuite multipliée par trois portes multiplicatives : direction de houle, vitesse de vent absolue, hauteur de houle absolue. Un spot hors fenêtre de direction ou avec un vent trop fort voit son score s'effondrer, même si les autres critères sont favorables.

J'ai conçu les endpoints critiques pour qu'ils soient autonomes : POST /engine/briefing charge lui-même les SpotParams du spot concerné. Spring Boot ne transmet que {spot_id, level, lang}, jamais de paramètre de calibration.

Le même moteur a ensuite été étendu à la prévision portuaire (GET /engine/port-forecast), en réutilisant les services Open-Meteo et marée existants sans toucher à la logique de scoring surf.

Couche API et persistance avec Spring Boot

La couche API expose les données publiques (spots, ports, prévisions, briefs) sans jamais exposer la logique de calibration.

• recherche de spots et de ports symétrique, avec une réponse structurée {results, hasMore, total} plutôt qu'un tableau plat ;
• cache Redis multi-niveaux : verdicts 6h, météo 6h, prévisions 1h, briefs 2h, prévisions portuaires 1h ;

J'ai également résolu un problème de routing lié aux identifiants OpenStreetMap contenant des caractères « / », qui cassaient le @PathVariable de Spring Boot : ajout d'un champ osmId dédié pour découpler les slugs publics des identifiants bruts.

Application mobile Angular / Ionic

Le brief de session affiche les données au format que j'estimais le plus lisible pour un surfeur : un texte neutre généré par Mistral, deux panneaux d'histogrammes de houle (0h–12h / 13h–24h, tous les 2h), des panneaux de tendance de vent avec une rose des vents en SVG, et les heures de marée haute/basse.

• prévisions à 7 jours avec hauteur de houle en donnée principale, température de l'eau, vent, période et marées en détail ;
• recherche débouncée à 300ms sur les pages surf, spots et ports, affichant nom, ville et région ;

Backoffice administrateur

Pour piloter la monétisation, j'ai développé un backoffice Angular dédié à la gestion des campagnes publicitaires.

Le système de ciblage repose sur trois niveaux de portée (global, pays, région, spot) combinés à des portées météo (ville, région, département), avec un CRUD complet et une gestion des priorités.

Pipeline de données V2 : recherche multi-source et IA

Calibrer 320 spots à la main n'était pas réaliste. J'ai construit un pipeline en plusieurs étapes documentées (11 documents de spécification) : recherche web multi-source, normalisation par LLM, validation, puis génération d'un contexte enrichi (aiContext) pour chaque spot.

• 167 spots vérifiés en France, 81 en Espagne, 84 à 85 au Portugal ;
• aiContext généré via l'API Anthropic (Claude Sonnet 5), de manière idempotente avec sauvegarde incrémentale spot par spot ;
• scripts de calibration idempotents, avec mode --dry-run, sauvegarde automatique avant toute modification, et préfixe default: pour tracer les valeurs calculées plutôt que sourcées.

Fiabilisation et résolution d'incidents

Comme sur tout projet multi-services, une part importante du travail a consisté à diagnostiquer et corriger des comportements inattendus, souvent aux frontières entre services.

• fenêtre de marée Stormglass devant démarrer 3h en avance
• échecs de désérialisation Redis sur les DTOs ;
• alignement des fuseaux horaires UTC/local renvoyé par Open-Meteo ;
• limite de 10 entrées pour les configurations plus larges (offre free trial pour commencer);
• routing Spring Boot cassé par des identifiants OSM contenant des « / ».

Ces incidents ont été traités méthodiquement : reproduire, isoler le service en cause, corriger à la source plutôt que de contourner, puis documenter la règle pour éviter la récidive.

Infrastructure et déploiement

L'ensemble des services tourne en local via Docker Compose, avec un pipeline GitHub Actions qui construit et publie les images vers le registre de conteneurs Scaleway.

Le choix de Scaleway Paris n'est pas anodin : il s'inscrit dans la logique de souveraineté numérique du projet, aux côtés de Mistral AI pour la génération des briefs et d'Open-Meteo/SHOM/Puertos del Estado pour les données météo et marée. L'objectif est qu'aucune donnée du projet ne transite par une infrastructure non-européenne.

État actuel et suite du projet

L'application fonctionne aujourd'hui de bout en bout en local, avec les cinq dépôts intégrés via Docker Compose.

Plusieurs chantiers sont volontairement mis de côté à ce stade de développement :

• provisioning des services managés Scaleway (PostgreSQL, Redis, Object Storage) ;
• build iOS/Android via Capacitor et soumission aux stores ;