roadwave/INCONSISTENCIES.md

Incohérences et Manques - RoadWave

Statut : Document de travail Dernière mise à jour : 2026-02-01 Score de santé documentaire : 75% (après corrections récentes)

Ce document liste les incohérences et manques critiques identifiés dans la documentation technique (ADR + Règles Métier) du projet RoadWave.

---

✅ Incohérences récemment corrigées

• ✅ Références ADR dans CLAUDE.md : Décalage -2 corrigé (commit c3abdd7)
• ✅ Geofencing MVP vs Phase 2 : ADR-020 clarifié avec séparation Phase 1/Phase 2 (commit 69a7bd8)
• ✅ Formule algorithme recommandation : Section détaillée ajoutée dans Règle 04 avec exemple concret (commit cf26d8a)
• ✅ Référence cassée ADR-002 : Section 5.2 → Section 5.1 corrigée (commit 18c8901)

---

✅ Incohérences acceptées pour MVP

Souveraineté données : Firebase vs Self-hosted

Conflit initial :

• ADR-008 : "100% self-hosted, souveraineté France"
• ADR-015 : "OVH France, aucune dépendance US"
• MAIS ADR-017 : Firebase Cloud Messaging = Google Cloud

Décision : ✅ Accepté pour MVP (2026-02-01)

• Cible MVP : terminaux Android équipés (environnement contrôlé)
• Firebase FCM gratuit et fiable pour phase initiale
• Incohérence documentée dans ADR-017 avec mitigation

Mitigation technique :

• Abstraction layer NotificationProvider pour faciliter migration future
• Exit path vers solution custom < 1 sprint si besoin
• DPA Google à valider avant production publique

Phase 2 : Réévaluation lors du scaling (≥20K users) pour solution self-hosted (Novu).

---

🎉 Incohérences critiques P0 : TOUTES RÉSOLUES !

⚠️ Manques critiques

1. Architecture de modération non documentée

État actuel :

• Règle 14-15 : décrivent les flux métier
• AUCUN ADR ne couvre l'architecture technique

Manque :

• Comment l'IA pré-filtre fonctionne (Whisper + NLP) ?
• Quelle architecture de queue (PostgreSQL, Redis, RabbitMQ) ?
• Stack technique des modérateurs (dashboard) ?
• API endpoints pour signalement ?
• Workflow de traitement (automatique vs manuel) ?

Impact : 3-4 semaines de surprise en développement, pas de consensus technique.

Action recommandée : Créer ADR-023 : Architecture de Modération

Contenu suggéré :
- Architecture queue signalements (PostgreSQL LISTEN/NOTIFY)
- Intégration Whisper API (transcription audio)
- ML pré-filtrage (OpenAI Moderation API ou modèle local)
- Dashboard modérateurs (interface web)
- Workflow et SLA (24h critique, 72h standard)
- Métriques et observabilité

---

2. Monitoring et Ops absents

État actuel :

• ADR-015 : mentionne OVH VPS
• AUCUN ADR sur monitoring, alerting, incident response

Manque :

• Stack de monitoring (Grafana + Prometheus ?)
• Alerting (PagerDuty, Slack, email ?)
• Incident runbooks (crash, data loss, breach)
• Backup/Disaster Recovery strategy
• SLO/SLA définition (99.9% availability = combien downtime ?)
• Performance metrics (p99 latency, throughput)

Impact : Équipe ops sera perdue le jour du lancement production.

Action recommandée : Créer ADR-024 : Monitoring, Observabilité et Incident Response

Contenu suggéré :
- Stack monitoring (Prometheus + Grafana self-hosted)
- Alerting rules (latency p99 > 100ms, error rate > 1%)
- Incident response workflow (on-call rotation, escalation)
- Runbook templates (database down, API crash, high load)
- Backup strategy (PostgreSQL WAL-E, 7 jours retention)
- Disaster Recovery (RTO/RPO : 1h / 15min)

---

3. Gestion des secrets non documentée

État actuel :

• Aucun ADR ne couvre la gestion des secrets

Manque :

• Où stocker secrets production (Mangopay credentials, DB password, JWT signing key) ?
• Solution : Vault self-hosted ? Kubernetes secrets ? Variables d'environnement ?
• Rotation des secrets (fréquence, automatisation) ?
• Field-level encryption PII (GPS coordinates, emails, phone numbers) ?
• OWASP Top 10 checklist (injection, CSRF, XSS) ?

Impact : Secrets en plaintext dans env vars = faille de sécurité critique.

Action recommandée : Créer ADR-025 : Sécurité - Secrets et Encryption

Contenu suggéré :
- Secrets management (HashiCorp Vault self-hosted vs managed)
- Field-level encryption (AES-256-GCM pour PII sensibles)
- HTTPS/TLS configuration (Let's Encrypt automatique)
- CORS/CSRF protection (middleware Fiber)
- API rate limiting (token bucket, 100 req/min/user)
- OWASP Top 10 mitigation checklist

---

4. Analytics et events tracking flous

État actuel :

• Règle 02:13.7 : "Matomo self-hosted"
• Aucun détail sur les events à tracer

Manque :

• Quels events tracer (play, pause, like, skip, duration, GPS updates) ?
• Schéma JSON des events (format standardisé) ?
• Dashboard principales métriques (DAU, WAU, engagement, churn) ?
• Funnel analytics (signup → première écoute → monétisation) ?
• Retention cohort analysis ?

Impact : Analytics sera chaos, équipe produit ne saura pas quoi mesurer.

Action recommandée : Créer ADR-026 : Analytics et Métriques Produit

Contenu suggéré :
- Events à tracer (JSON Schema pour validation)
- Matomo setup (Docker self-hosted, data retention 90j)
- Dashboard KPI (DAU, WAU, engagement rate, churn by cohort)
- Funnel metrics (signup → content discovery → monetization)
- Privacy-preserving analytics (IP anonymization, no cookies tiers)

---

5. Stratégie de scaling Post-MVP absente

État actuel :

• ADR-015 : "Phase 2 à 20K users = Scaleway managé"
• Aucun détail sur comment scaler

Manque :

• Database sharding strategy (par user_id ? par région géographique ?) ?
• Cache invalidation at scale (comment éviter cache stampede) ?
• Load balancing multi-région (GeoDNS pour latence optimale) ?
• API rate limiting global (par IP, par user, quotas) ?
• CDN multi-région (Cloudflare ? BunnyCDN ?) ?

Impact : Architecture ne tiendra pas à 100K+ users sans refonte complète.

Action recommandée : Créer ADR-027 : Stratégie de Scaling 20K-500K Users

Contenu suggéré :
- Database partitioning (sharding horizontal par région EU)
- Cache strategy (locality-aware, TTL adaptatif, invalidation patterns)
- Load balancing (Nginx + health checks, failover automatique)
- API rate limiting (Redis + token bucket, quotas différenciés free/premium)
- Multi-région CDN (Bunny CDN pour souveraineté EU)

---

📊 Évaluation par domaine

Domaine	Score	Verdict	Manques principaux
Géolocalisation	90%	✅ Excellent	-
Authentification	85%	✅ Bon	Glossaire OAuth2 PKCE
Streaming Audio	80%	✅ Bon	Détails pre-buffering
Mobile & Permissions	80%	✅ Bon	- (corrigé ✅)
Paiements	80%	✅ Bon	Multi-devise taux change
Modération	20%	❌ Insuffisant	ADR-023 requis
Ops & Monitoring	30%	❌ Insuffisant	ADR-024 requis
Sécurité	40%	⚠️ Minimal	ADR-025 requis
Analytics	35%	⚠️ Minimal	ADR-026 recommandé
Scaling	40%	⚠️ Minimal	ADR-027 recommandé
Testing	85%	✅ Bon	-

Score global : 82% (après corrections P0 complètes, était 80%)

---

🎯 Plan d'action prioritaire

P0 - Bloquant implémentation (à faire AVANT coding)

1. ✅ FAIT : Corriger références ADR dans CLAUDE.md
2. ✅ FAIT : Clarifier geofencing Phase 1/Phase 2 dans ADR-020
3. ✅ FAIT : Accepter incohérence Firebase pour MVP (terminaux Android contrôlés)
4. ✅ FAIT : Préciser formule algorithme recommandation (Règle 04)
   • Section "Calcul détaillé score_interets" ajoutée avec exemple concret
   • Domaine jauges : 0-100, score final : 0-1
   • Cas limites documentés
5. ✅ FAIT : Corriger référence cassée ADR-002 (Section 5.2 → 5.1)

🎉 TOUTES LES INCOHÉRENCES P0 SONT RÉSOLUES ! 🎉

P1 - Important design (avant Sprint 3-4)

6. 🔴 TODO : Créer ADR-023 : Architecture de Modération
   • Queue signalements, workflow IA, dashboard modérateurs
7. 🔴 TODO : Créer ADR-024 : Monitoring et Ops
   • Prometheus + Grafana, alerting, runbooks, backup/DR
8. 🔴 TODO : Créer ADR-025 : Secrets et Sécurité
   • Vault, encryption PII, OWASP Top 10 checklist

P2 - Nice-to-have (avant Sprint 6-8)

9. 🟡 TODO : Créer ADR-026 : Analytics et Events
   • JSON Schema events, dashboard KPI, funnel metrics
10. 🟡 TODO : Créer ADR-027 : Stratégie Scaling
    • Sharding DB, cache invalidation, load balancing multi-région
11. 🟡 TODO : Ajouter glossaire dans CLAUDE.md
    • OAuth2 PKCE vs Providers
    • MVP vs Phase 2 vs Post-MVP
    • Cache strategies (hot/cold, TTL)

---

📈 Objectif cible

Score santé documentaire cible : 95% avant démarrage Sprint 3

Actions minimales requises :

• ✅ Corriger 2 incohérences critiques restantes (P0 : items 4-5)
• ✅ Créer 3 ADR manquants (P1 : Modération, Ops, Sécurité)
• 🎯 Atteindre score 95% dans tous les domaines critiques

Deadline recommandée : 2 semaines avant démarrage développement backend/mobile

Statut actuel :

• Incohérences P0 résolues : 5/5 (100%) ✅ COMPLET !
• ADR manquants P1 : 0/3 (0%)
• Score global : 82% → objectif 95%

Phase P0 TERMINÉE : Documentation prête pour démarrage implémentation ! Prochaine phase : Créer 3 ADR manquants P1 (Modération, Ops, Sécurité) pour atteindre 95%.

---

🔄 Maintenance de ce document

Ce document doit être mis à jour à chaque :

• Correction d'incohérence identifiée
• Création d'un nouvel ADR comblant un manque
• Identification d'une nouvelle incohérence

Responsable : Tech Lead / Architecte Fréquence de revue : Hebdomadaire pendant phase documentation, mensuelle ensuite