diff --git a/CLAUDE.md b/CLAUDE.md index 003acd8..47dca97 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -288,7 +288,7 @@ Zitadel handles authentication ([ADR-008](docs/adr/008-authentification.md)): ## Performance Targets -See [TECHNICAL.md](TECHNICAL.md) for detailed metrics: +See [TECHNICAL.md](docs/TECHNICAL.md) for detailed metrics: - API latency p99: < 100ms - Audio start time: < 3s - Target availability: 99.9% diff --git a/TECHNICAL.md b/TECHNICAL.md deleted file mode 100644 index c8649e6..0000000 --- a/TECHNICAL.md +++ /dev/null @@ -1,228 +0,0 @@ -# RoadWave - Architecture Technique - -> Les décisions techniques sont documentées dans [docs/adr/](docs/adr/) - -## Stack Technologique - -| Composant | Technologie | ADR | -|-----------|-------------|-----| -| **Backend** | Go + Fiber | [ADR-001](docs/adr/001-langage-backend.md) | -| **Architecture Backend** | Monolithe Modulaire | [ADR-010](docs/adr/010-architecture-backend.md) | -| **Authentification** | Zitadel (self-hosted OVH) | [ADR-008](docs/adr/008-authentification.md) | -| **Streaming** | HLS | [ADR-002](docs/adr/002-protocole-streaming.md) | -| **Codec** | Opus | [ADR-003](docs/adr/003-codec-audio.md) | -| **CDN** | NGINX Cache (OVH VPS) | [ADR-004](docs/adr/004-cdn.md) | -| **Storage** | OVH Object Storage | [ADR-004](docs/adr/004-cdn.md) | -| **Hébergement MVP** | OVH VPS Essential | [ADR-015](docs/adr/015-hebergement.md) | -| **Organisation** | Monorepo | [ADR-014](docs/adr/014-organisation-monorepo.md) | -| **Base de données** | PostgreSQL + PostGIS | [ADR-005](docs/adr/005-base-de-donnees.md) | -| **ORM/Accès données** | sqlc | [ADR-011](docs/adr/011-orm-acces-donnees.md) | -| **Cache** | Redis Cluster | [ADR-021](docs/adr/021-solution-cache.md) | -| **Chiffrement** | TLS 1.3 | [ADR-006](docs/adr/006-chiffrement.md) | -| **Live** | WebRTC | [ADR-002](docs/adr/002-protocole-streaming.md) | -| **Frontend Mobile** | Flutter | [ADR-012](docs/adr/012-frontend-mobile.md) | -| **Tests** | Testify + Godog (Gherkin) | [ADR-013](docs/adr/013-strategie-tests.md), [ADR-007](docs/adr/007-tests-bdd.md) | -| **Paiements** | Mangopay | [ADR-009](docs/adr/009-solution-paiement.md) | -| **Emailing** | Brevo | [ADR-016](docs/adr/016-service-emailing.md) | -| **Géolocalisation IP** | IP2Location (fallback) | [ADR-019](docs/adr/019-geolocalisation-ip.md) | -| **Librairies Mobile** | Flutter packages | [ADR-020](docs/adr/020-librairies-flutter.md) | -| **CI/CD** | GitHub Actions (monorepo) | [ADR-022](docs/adr/022-strategie-cicd-monorepo.md) | -| **Modération** | Architecture modération | [ADR-023](docs/adr/023-architecture-moderation.md) | -| **Monitoring** | Prometheus + Grafana | [ADR-024](docs/adr/024-monitoring-observabilite.md) | -| **Secrets** | Vault + sealed secrets | [ADR-025](docs/adr/025-securite-secrets.md) | -| **Notifications géo** | Push + geofencing | [ADR-017](docs/adr/017-notifications-geolocalisees.md) | -| **Notifications push** | FCM + APNS | [ADR-018](docs/adr/018-notifications-push.md) | - ---- - -## Streaming Audio - -### Protocole : HLS (HTTP Live Streaming) - -- Fonctionne à travers firewalls et réseaux mobiles instables -- Cache CDN natif (réduction des coûts) -- Bitrate adaptatif automatique (tunnels, zones rurales) -- Support natif iOS/Android - -### Codec : Opus - -Optimisé pour la voix en environnement bruyant (voiture). - -| Qualité | Bitrate | Usage | -|---------|---------|-------| -| Basse | 24 kbps | 2G/Edge | -| Standard | 48 kbps | 3G | -| Haute | 64 kbps | 4G/5G | - -Fallback AAC-LC pour appareils legacy. - -### Buffering Adaptatif - -| Réseau | Buffer min | Buffer cible | Buffer max | -|--------|------------|--------------|------------| -| WiFi | 5s | 30s | 120s | -| 4G/5G | 10s | 45s | 120s | -| 3G | 30s | 90s | 300s | - ---- - -## Sécurité - -### Chiffrement - -- **TLS 1.3** sur tous les endpoints (overhead ~1-2%) -- **DTLS-SRTP** pour WebRTC (radio live) -- Pas de DRM initialement (ajout si licences l'exigent) - -### Authentification - -- **Zitadel self-hosted sur OVH France** (Gravelines) pour IAM -- Souveraineté totale : 100% données en France (cohérent avec ADR-004) -- JWT validation locale (zitadel-go SDK) -- OAuth2 PKCE pour mobile (iOS/Android) -- MFA et passkeys disponibles -- Rate limiting par IP et par utilisateur (Nginx + Zitadel) -- PostgreSQL schema partagé avec RoadWave (séparation logique) - ---- - -## Base de Données - -### PostgreSQL + PostGIS - -```sql --- Requête géolocalisée typique -SELECT id, ST_Distance(location::geography, ST_MakePoint($lon, $lat)::geography) as distance -FROM contents -WHERE ST_DWithin(location::geography, ST_MakePoint($lon, $lat)::geography, 50000) -ORDER BY distance -LIMIT 20; -``` - -### Redis Geospatial (Cache) - -``` -GEOADD contents:geo longitude latitude content_id -GEORADIUS contents:geo user_lon user_lat 50 km WITHDIST COUNT 20 ASC -``` - -TTL cache : 5 minutes (le contenu ne bouge pas). - ---- - -## Architecture Services - -```mermaid -flowchart TB - subgraph clients["Clients"] - mobile["Mobile Apps
iOS/Android
Flutter"] - carplay["CarPlay /
Android Auto"] - end - - subgraph ovh["OVH VPS Essential (Gravelines, France)"] - nginx["NGINX Cache
+ Let's Encrypt
TLS 1.3, Rate Limiting"] - api["API Gateway
Go + Fiber :8080"] - - subgraph services["Backend Services (Monolithe Modulaire)"] - auth["Auth Service
JWT validation"] - user["User Service
Profils, Jauges"] - content["Content/Geo Service
Recommandations
PostGIS queries"] - streaming["Streaming Service
HLS generation"] - payment["Payment Service
Mangopay integration"] - notif["Notification Service
FCM/APNS"] - end - - zitadel["Zitadel IdP
OAuth2 PKCE
:8081"] - ip2loc["IP2Location DB
SQLite ~50MB
Mode dégradé"] - - subgraph data["Données"] - pgbouncer["PgBouncer
Connection pooling
:6432"] - postgres["PostgreSQL 16
+ PostGIS 3.4
Schémas:
- roadwave
- zitadel"] - redis["Redis 7 Cluster
Cache + Geospatial
GEORADIUS"] - end - end - - subgraph external["Services Externes"] - storage["OVH Object Storage
Fichiers audio HLS"] - mangopay["Mangopay
Paiements, KYC"] - brevo["Brevo
Emails transactionnels"] - fcm["FCM / APNS
Push notifications"] - end - - mobile --> nginx - carplay --> nginx - nginx --> api - api --> auth - api --> user - api --> content - api --> streaming - api --> payment - api --> notif - api --> ip2loc - - auth --> zitadel - user --> pgbouncer - user --> redis - content --> pgbouncer - content --> redis - streaming --> storage - payment --> mangopay - notif --> fcm - - zitadel --> pgbouncer - pgbouncer --> postgres - - brevo -.email.-> mobile - fcm -.push.-> mobile - - style ovh fill:#e3f2fd - style external fill:#fff3e0 - style clients fill:#f3e5f5 - style data fill:#e8f5e9 -``` - -**Souveraineté** : 100% données en France (RGPD compliant) - ---- - -## Scaling 10M Utilisateurs - -### Stratégie par phase - -| Phase | Utilisateurs | Infra | Coût estimé | -|-------|--------------|-------|-------------| -| MVP | 0-20K | OVH VPS Essential + PostgreSQL + Zitadel + NGINX Cache | ~14€/mois | -| Growth | 20K-500K | Scaleway Instances (multi-replicas), OVH Object Storage | 150-500€/mois | -| Scale | 500K+ | Multi-région, Kubernetes managé, NGINX origin shield | 2-10K€/mois | - -### Métriques cibles - -| Métrique | Objectif | -|----------|----------| -| Latence API p99 | < 100ms | -| Temps de démarrage audio | < 3s | -| Disponibilité | 99.9% | -| Connexions/serveur | 100K+ | - ---- - -## Points de vigilance - -1. **Buffering mobile** : Pré-chargement agressif avant tunnels (détection GPS) -2. **Handoff réseau** : Buffer suffisant pour survivre aux changements de cellule -3. **Mode offline** : Téléchargement complet sur WiFi -4. **Bande passante** : 48 kbps Opus = ~20 MB/heure (faible consommation data) - ---- - -## Pourquoi pas UDP brut ? - -| UDP | HLS/TCP | -|-----|---------| -| Latence minimale | Latence acceptable (5-30s) | -| Problèmes NAT/firewall | Passe partout | -| Perte de paquets = artefacts | Retransmission automatique | -| Pas de cache CDN | Cache CDN = économies | -| Complexité++ | Standard de l'industrie | - -Pour du contenu non-interactif (podcasts, audio-guides), la latence HLS est acceptable. WebRTC réservé à la radio live uniquement. diff --git a/docs/index.md b/docs/README.md similarity index 100% rename from docs/index.md rename to docs/README.md diff --git a/docs/REFACTOR-DDD.md b/docs/REFACTOR-DDD.md deleted file mode 100644 index 9cf176f..0000000 --- a/docs/REFACTOR-DDD.md +++ /dev/null @@ -1,370 +0,0 @@ -# Plan de refactorisation : Organisation DDD de la documentation - -## 🎯 Objectif - -Réorganiser la documentation du projet selon les principes du **Domain-Driven Design (DDD)** pour améliorer la cohésion, la maintenabilité et l'alignement avec l'architecture modulaire du backend. - -## 📊 Situation actuelle - -### Structure actuelle - -``` -docs/ -├── regles-metier/ # 19 fichiers numérotés 01-19 + ANNEXE -├── diagrammes/ # Organisés par type (flux, états, séquences, entités) -│ ├── flux/ -│ ├── etats/ -│ ├── sequence/ -│ └── entites/ -├── adr/ # Architecture Decision Records -├── legal/ # Documentation légale -└── interfaces/ # Interfaces UI -``` - -### Problèmes identifiés - -1. **Organisation séquentielle** : Numérotation 01-19 ne reflète pas les domaines métier -2. **Diagrammes dispersés** : Séparés des règles métier qu'ils illustrent -3. **Navigation complexe** : Difficile de trouver toute la doc d'un domaine -4. **Pas d'alignement code** : Structure docs ≠ structure `backend/internal/` -5. **Onboarding difficile** : Nouveau dev doit parcourir 19 fichiers linéairement -6. **Maintenance** : Règles métier, entités et diagrammes d'un même domaine sont éparpillés - -## 🎨 Architecture cible (DDD) - -### Nouvelle structure - -``` -docs/ -├── domains/ # 🆕 Organisation par domaine -│ ├── README.md # Context Map + Index domaines -│ │ -│ ├── _shared/ # Core Domain -│ │ ├── README.md -│ │ ├── rules/ -│ │ │ ├── authentification.md -│ │ │ ├── rgpd.md -│ │ │ └── gestion-erreurs.md -│ │ ├── entities/ -│ │ │ └── modele-global.md -│ │ └── ubiquitous-language.md -│ │ -│ ├── recommendation/ # Bounded Context -│ │ ├── README.md -│ │ ├── rules/ -│ │ │ ├── centres-interet-jauges.md -│ │ │ ├── algorithme-recommandation.md -│ │ │ └── interactions-navigation.md -│ │ ├── entities/ -│ │ │ └── modele-recommandation.md -│ │ ├── sequences/ -│ │ │ └── scoring-recommandation.md -│ │ └── features/ -│ │ └── *.feature -│ │ -│ ├── content/ # Bounded Context -│ │ ├── README.md -│ │ ├── rules/ -│ │ │ ├── creation-publication.md -│ │ │ ├── audio-guides.md -│ │ │ ├── radio-live.md -│ │ │ ├── contenus-geolocalises.md -│ │ │ └── detection-contenu-protege.md -│ │ ├── entities/ -│ │ │ ├── modele-audio-guides.md -│ │ │ └── modele-radio-live.md -│ │ └── flows/ -│ │ -│ ├── advertising/ # Bounded Context -│ │ ├── README.md -│ │ ├── rules/ -│ │ │ └── publicites.md -│ │ ├── entities/ -│ │ │ └── modele-publicites.md -│ │ ├── sequences/ -│ │ ├── states/ -│ │ └── flows/ -│ │ -│ ├── premium/ # Bounded Context -│ │ ├── README.md -│ │ ├── rules/ -│ │ │ ├── premium.md -│ │ │ ├── mode-offline.md -│ │ │ └── abonnements-notifications.md -│ │ ├── entities/ -│ │ │ └── modele-premium.md -│ │ └── sequences/ -│ │ -│ ├── monetization/ # Bounded Context -│ │ ├── README.md -│ │ ├── rules/ -│ │ │ └── monetisation-createurs.md -│ │ ├── entities/ -│ │ │ └── modele-monetisation.md -│ │ └── flows/ -│ │ -│ └── moderation/ # Bounded Context -│ ├── README.md -│ ├── rules/ -│ │ ├── moderation-flows.md -│ │ ├── moderation-communautaire.md -│ │ └── autres-comportements.md -│ ├── entities/ -│ │ └── modele-moderation.md -│ ├── sequences/ -│ │ └── processus-appel-moderation.md -│ ├── states/ -│ │ └── signalement-lifecycle.md -│ ├── flows/ -│ │ └── moderation-signalement.md -│ └── features/ -│ -├── adr/ # Inchangé -├── legal/ # Inchangé -├── interfaces/ # Inchangé -└── technical.md # Inchangé -``` - -## 📋 Mapping des domaines - -### 7 Bounded Contexts identifiés - -| Domaine | Règles métier | Entités | Diagrammes | Responsabilité | -|---------|--------------|---------|------------|----------------| -| **_shared** | 01, 02, 10 | USERS, CONTENTS, SUBSCRIPTIONS, LISTENING_HISTORY | - | Authentification, RGPD, Gestion erreurs | -| **recommendation** | 03, 04, 05 | USER_INTERESTS, INTEREST_CATEGORIES | scoring-recommandation.md | Jauges, Algorithme, Navigation | -| **content** | 06, 07, 11, 12, 13 | AUDIO_GUIDES, LIVE_STREAMS, GUIDE_SEQUENCES, LIVE_RECORDINGS | - | Création, Audio-guides, Live, Détection droits | -| **advertising** | 16 | AD_CAMPAIGNS, AD_METRICS, AD_IMPRESSIONS | - | Campagnes, Ciblage, Métriques | -| **premium** | 08, 09, 17 | PREMIUM_SUBSCRIPTIONS, ACTIVE_STREAMS, OFFLINE_DOWNLOADS | - | Abonnements, Offline, Notifications | -| **monetization** | 18 | CREATOR_MONETIZATION, REVENUES, PAYOUTS | - | KYC, Revenus, Versements | -| **moderation** | 14, 15, 19 | REPORTS, SANCTIONS, APPEALS, STRIKES, BADGES | processus-appel-moderation.md, signalement-lifecycle.md, moderation-signalement.md | Signalements, Sanctions, Badges | - -## 🗺️ Plan de migration détaillé - -### Phase 1 : Créer la structure cible - -```bash -# Créer l'arborescence -mkdir -p docs/domains/{_shared,recommendation,content,advertising,premium,monetization,moderation}/{rules,entities,sequences,states,flows,features} -``` - -### Phase 2 : Déplacer les règles métier - -| Fichier actuel | Destination | -|----------------|-------------| -| `01-authentification-inscription.md` | `domains/_shared/rules/authentification.md` | -| `02-conformite-rgpd.md` | `domains/_shared/rules/rgpd.md` | -| `03-centres-interet-jauges.md` | `domains/recommendation/rules/centres-interet-jauges.md` | -| `04-algorithme-recommandation.md` | `domains/recommendation/rules/algorithme-recommandation.md` | -| `05-interactions-navigation.md` | `domains/recommendation/rules/interactions-navigation.md` | -| `06-audio-guides-multi-sequences.md` | `domains/content/rules/audio-guides.md` | -| `07-contenus-geolocalises-voiture.md` | `domains/content/rules/contenus-geolocalises.md` | -| `08-mode-offline.md` | `domains/premium/rules/mode-offline.md` | -| `09-abonnements-notifications.md` | `domains/premium/rules/abonnements-notifications.md` | -| `10-gestion-erreurs.md` | `domains/_shared/rules/gestion-erreurs.md` | -| `11-creation-publication-contenu.md` | `domains/content/rules/creation-publication.md` | -| `12-radio-live.md` | `domains/content/rules/radio-live.md` | -| `13-detection-contenu-protege.md` | `domains/content/rules/detection-contenu-protege.md` | -| `14-moderation-flows.md` | `domains/moderation/rules/moderation-flows.md` | -| `15-moderation-communautaire.md` | `domains/moderation/rules/moderation-communautaire.md` | -| `16-publicites.md` | `domains/advertising/rules/publicites.md` | -| `17-premium.md` | `domains/premium/rules/premium.md` | -| `18-monetisation-createurs.md` | `domains/monetization/rules/monetisation-createurs.md` | -| `19-autres-comportements.md` | `domains/moderation/rules/autres-comportements.md` | -| `ANNEXE-POST-MVP.md` | `domains/_shared/rules/ANNEXE-POST-MVP.md` | - -### Phase 3 : Déplacer les diagrammes d'entités - -| Fichier actuel | Destination | -|----------------|-------------| -| `diagrammes/entites/modele-global.md` | `domains/_shared/entities/modele-global.md` | -| `diagrammes/entites/modele-recommandation.md` | `domains/recommendation/entities/modele-recommandation.md` | -| `diagrammes/entites/modele-audio-guides.md` | `domains/content/entities/modele-audio-guides.md` | -| `diagrammes/entites/modele-radio-live.md` | `domains/content/entities/modele-radio-live.md` | -| `diagrammes/entites/modele-publicites.md` | `domains/advertising/entities/modele-publicites.md` | -| `diagrammes/entites/modele-premium.md` | `domains/premium/entities/modele-premium.md` | -| `diagrammes/entites/modele-monetisation.md` | `domains/monetization/entities/modele-monetisation.md` | -| `diagrammes/entites/modele-moderation.md` | `domains/moderation/entities/modele-moderation.md` | - -### Phase 4 : Déplacer les autres diagrammes - -| Fichier actuel | Destination | -|----------------|-------------| -| `diagrammes/flux/moderation-signalement.md` | `domains/moderation/flows/moderation-signalement.md` | -| `diagrammes/etats/signalement-lifecycle.md` | `domains/moderation/states/signalement-lifecycle.md` | -| `diagrammes/sequence/processus-appel-moderation.md` | `domains/moderation/sequences/processus-appel-moderation.md` | - -### Phase 5 : Créer les README.md de domaine - -Créer un README.md dans chaque domaine avec le template suivant : - -```markdown -# Domaine : [Nom] - -## Vue d'ensemble -[Description du bounded context] - -## Responsabilités -- Responsabilité 1 -- Responsabilité 2 - -## Règles métier -- [Règle 1](rules/xxx.md) - -## Modèle de données -- [Diagramme entités](entities/modele-xxx.md) - -## Diagrammes -- [Flux](flows/xxx.md) -- [États](states/xxx.md) -- [Séquences](sequences/xxx.md) - -## Tests BDD -- [Feature 1](features/xxx.feature) - -## Dépendances -- ✅ Dépend de : `_shared` -- ⚠️ Interactions avec : `moderation` - -## Ubiquitous Language -**Termes métier spécifiques au domaine** -``` - -### Phase 6 : Déplacer les features Gherkin - -```bash -# Les features actuellement dans /features/ root -mv features/api/recommendation/* domains/recommendation/features/ -mv features/moderation/* domains/moderation/features/ -# etc. -``` - -### Phase 7 : Créer le Context Map - -Créer `docs/domains/README.md` avec la cartographie des domaines : - -```markdown -# Context Map RoadWave - -## Vue d'ensemble des domaines - -[Diagramme Mermaid des relations entre bounded contexts] - -## Bounded Contexts - -### Core Domain -- **_shared** : Authentification, RGPD, Gestion erreurs - -### Supporting Subdomains -- **recommendation** : Jauges, Algorithme, Scoring -- **content** : Création, Audio-guides, Live -- **moderation** : Signalements, Sanctions, Badges - -### Generic Subdomains -- **advertising** : Campagnes publicitaires -- **premium** : Abonnements, Offline -- **monetization** : Revenus créateurs -``` - -### Phase 8 : Mettre à jour mkdocs.yml - -Réorganiser la navigation MkDocs pour refléter la nouvelle structure par domaine. - -### Phase 9 : Mettre à jour les liens internes - -Corriger tous les liens relatifs dans les fichiers markdown pour pointer vers les nouvelles locations. - -### Phase 10 : Nettoyer l'ancienne structure - -```bash -# Une fois tout migré et testé -rm -rf docs/regles-metier/ -rm -rf docs/diagrammes/ -``` - -## ✅ Avantages attendus - -1. **Cohésion forte** : Toute la doc d'un domaine au même endroit -2. **Couplage faible** : Domaines indépendants, dépendances explicites -3. **Navigabilité améliorée** : README par domaine = entrée claire -4. **Alignement code/docs** : Miroir de `backend/internal/` -5. **Onboarding facilité** : Nouveau dev explore domaine par domaine -6. **Maintenance simplifiée** : Modifier un domaine sans toucher aux autres -7. **Scalabilité** : Facile d'ajouter un nouveau domaine -8. **Tests BDD intégrés** : Features au plus près des règles métier - -## ⚠️ Risques et précautions - -### Risques identifiés - -1. **Liens cassés** : Nombreux liens internes à corriger -2. **Confusion temporaire** : Équipe doit s'adapter à la nouvelle structure -3. **MkDocs rebuild** : Navigation complète à refaire -4. **Features Gherkin** : Potentiellement beaucoup de fichiers à déplacer - -### Précautions - -1. ✅ **Créer ce plan d'abord** : Validation avant exécution -2. ✅ **Branch dédiée** : `refactor/ddd-documentation` -3. ✅ **Commits atomiques** : Un commit par phase -4. ✅ **Tests continus** : Vérifier MkDocs build après chaque phase -5. ✅ **Backup** : Garder ancienne structure jusqu'à validation complète -6. ✅ **Script automatisé** : Créer script pour les déplacements et corrections de liens - -## 📝 Checklist d'exécution - -- [ ] Valider ce plan avec l'équipe -- [ ] Créer branch `refactor/ddd-documentation` -- [ ] Phase 1 : Créer arborescence -- [ ] Phase 2 : Déplacer règles métier -- [ ] Phase 3 : Déplacer diagrammes entités -- [ ] Phase 4 : Déplacer autres diagrammes -- [ ] Phase 5 : Créer README.md domaines -- [ ] Phase 6 : Déplacer features Gherkin -- [ ] Phase 7 : Créer Context Map -- [ ] Phase 8 : Mettre à jour mkdocs.yml -- [ ] Phase 9 : Corriger liens internes -- [ ] Phase 10 : Nettoyer ancienne structure -- [ ] Tester build MkDocs -- [ ] Valider avec équipe -- [ ] Merger dans main - -## 🚀 Script d'automatisation suggéré - -```bash -#!/bin/bash -# scripts/refactor-ddd.sh - -# Phase 1 : Créer structure -echo "Phase 1: Création structure..." -mkdir -p docs/domains/{_shared,recommendation,content,advertising,premium,monetization,moderation}/{rules,entities,sequences,states,flows,features} - -# Phase 2 : Déplacer règles métier -echo "Phase 2: Migration règles métier..." -git mv docs/regles-metier/01-authentification-inscription.md docs/domains/_shared/rules/authentification.md -# ... etc pour tous les fichiers - -# Phase 3-4 : Déplacer diagrammes -echo "Phase 3-4: Migration diagrammes..." -git mv docs/diagrammes/entites/modele-global.md docs/domains/_shared/entities/modele-global.md -# ... etc - -# Phase 9 : Corriger liens (sed ou script Python) -echo "Phase 9: Correction liens..." -find docs/domains -name "*.md" -exec sed -i 's|../../regles-metier/|../rules/|g' {} \; -# ... etc - -echo "Migration terminée!" -``` - -## 📚 Références DDD - -- [Domain-Driven Design - Eric Evans](https://www.domainlanguage.com/ddd/) -- [Bounded Context - Martin Fowler](https://martinfowler.com/bliki/BoundedContext.html) -- [Context Mapping](https://github.com/ddd-crew/context-mapping) - ---- - -**Date de création** : 2026-02-07 -**Statut** : 🟡 En attente de validation -**Auteur** : Documentation refactoring initiative diff --git a/docs/technical.md b/docs/TECHNICAL.md similarity index 76% rename from docs/technical.md rename to docs/TECHNICAL.md index 45b6fed..a54412c 100644 --- a/docs/technical.md +++ b/docs/TECHNICAL.md @@ -31,7 +31,7 @@ | **Monitoring** | Prometheus + Grafana | [ADR-024](adr/024-monitoring-observabilite.md) | | **Secrets** | Vault + sealed secrets | [ADR-025](adr/025-securite-secrets.md) | | **Notifications géo** | Push + geofencing | [ADR-017](adr/017-notifications-geolocalisees.md) | -| **Notifications push** | FCM + APNS | [ADR-018](adr/017-notifications-geolocalisees.md) | +| **Notifications push** | FCM + APNS | [ADR-018](adr/018-notifications-push.md) | --- @@ -113,77 +113,72 @@ TTL cache : 5 minutes (le contenu ne bouge pas). ## Architecture Services ```mermaid -flowchart LR - subgraph clients["📱 Clients"] - direction TB +flowchart TB + subgraph clients["Clients"] mobile["Mobile Apps
iOS/Android
Flutter"] carplay["CarPlay /
Android Auto"] end - subgraph ovh["🇫🇷 OVH VPS Essential (Gravelines, France)"] - direction TB + subgraph ovh["OVH VPS Essential (Gravelines, France)"] + nginx["NGINX Cache
+ Let's Encrypt
TLS 1.3, Rate Limiting"] + api["API Gateway
Go + Fiber :8080"] - nginx["🌐 NGINX
Cache + TLS 1.3
Rate Limiting"] - api["🚪 API Gateway
Go + Fiber
:8080"] - - subgraph services["Backend (Monolithe Modulaire)"] - direction LR - auth["🔐 Auth"] - user["👤 User"] - content["🎙️ Content/Geo"] - streaming["📡 Streaming"] - payment["💳 Payment"] - notif["🔔 Notif"] + subgraph services["Backend Services (Monolithe Modulaire)"] + auth["Auth Service
JWT validation"] + user["User Service
Profils, Jauges"] + content["Content/Geo Service
Recommandations
PostGIS queries"] + streaming["Streaming Service
HLS generation"] + payment["Payment Service
Mangopay integration"] + notif["Notification Service
FCM/APNS"] end - zitadel["🔑 Zitadel
OAuth2 PKCE
:8081"] - ip2loc["🌍 IP2Location
SQLite 50MB"] + zitadel["Zitadel IdP
OAuth2 PKCE
:8081"] + ip2loc["IP2Location DB
SQLite ~50MB
Mode dégradé"] - subgraph data["💾 Données"] - direction TB - pgbouncer["PgBouncer
:6432"] - postgres["PostgreSQL 16
+ PostGIS 3.4"] - redis["Redis 7
Cache + Geo"] + subgraph data["Données"] + pgbouncer["PgBouncer
Connection pooling
:6432"] + postgres["PostgreSQL 16
+ PostGIS 3.4
Schémas:
- roadwave
- zitadel"] + redis["Redis 7 Cluster
Cache + Geospatial
GEORADIUS"] end end - subgraph external["☁️ Services Externes"] - direction TB - storage["OVH Object Storage
(Fichiers HLS)"] - mangopay["Mangopay
(Paiements/KYC)"] - brevo["Brevo
(Emails)"] - fcm["FCM/APNS
(Push)"] + subgraph external["Services Externes"] + storage["OVH Object Storage
Fichiers audio HLS"] + mangopay["Mangopay
Paiements, KYC"] + brevo["Brevo
Emails transactionnels"] + fcm["FCM / APNS
Push notifications"] end - %% Flux clients - clients --> nginx + mobile --> nginx + carplay --> nginx nginx --> api - - %% API vers services - api --> services + api --> auth + api --> user + api --> content + api --> streaming + api --> payment + api --> notif api --> ip2loc - %% Services vers infra auth --> zitadel - user --> data - content --> data + user --> pgbouncer + user --> redis + content --> pgbouncer + content --> redis streaming --> storage payment --> mangopay notif --> fcm - %% Infra interne zitadel --> pgbouncer pgbouncer --> postgres - %% Retours vers clients - brevo -.email.-> clients - fcm -.push.-> clients + brevo -.email.-> mobile + fcm -.push.-> mobile - style ovh fill:#e3f2fd,stroke:#1976d2,stroke-width:2px - style external fill:#fff3e0,stroke:#f57c00,stroke-width:2px - style clients fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px - style data fill:#e8f5e9,stroke:#388e3c,stroke-width:2px - style services fill:#fff,stroke:#666,stroke-width:1px + style ovh fill:#e3f2fd + style external fill:#fff3e0 + style clients fill:#f3e5f5 + style data fill:#e8f5e9 ``` **Souveraineté** : 100% données en France (RGPD compliant) diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 0000000..fe8347d --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,124 @@ +# Architecture Decision Records (ADR) + +> Documentation des décisions architecturales importantes du projet RoadWave + +## Vue d'ensemble + +Les Architecture Decision Records (ADR) documentent les décisions techniques importantes prises au cours du développement de RoadWave. Chaque ADR suit un format standardisé : contexte, décision, alternatives considérées et conséquences. + +## Index des ADR + +### Core Architecture + +| ADR | Titre | Statut | Date | +|-----|-------|--------|------| +| [ADR-001](001-langage-backend.md) | Langage Backend | ✅ Accepté | 2025-01-17 | +| [ADR-010](010-architecture-backend.md) | Architecture Backend | ✅ Accepté | 2025-01-25 | +| [ADR-011](011-orm-acces-donnees.md) | ORM et Accès Données | ✅ Accepté | 2025-01-26 | +| [ADR-012](012-frontend-mobile.md) | Frontend Mobile | ✅ Accepté | 2025-01-26 | +| [ADR-014](014-organisation-monorepo.md) | Organisation en Monorepo | ✅ Accepté | 2025-01-28 | + +### Data & Infrastructure + +| ADR | Titre | Statut | Date | +|-----|-------|--------|------| +| [ADR-005](005-base-de-donnees.md) | Base de données | ✅ Accepté | 2025-01-20 | +| [ADR-021](021-solution-cache.md) | Solution de Cache | ✅ Accepté | 2025-02-01 | +| [ADR-015](015-hebergement.md) | Hébergement | ✅ Accepté | 2025-01-28 | +| [ADR-019](019-geolocalisation-ip.md) | Géolocalisation par IP | ✅ Accepté | 2025-01-30 | + +### Streaming & Content + +| ADR | Titre | Statut | Date | +|-----|-------|--------|------| +| [ADR-002](002-protocole-streaming.md) | Protocole Streaming | ✅ Accepté | 2025-01-18 | +| [ADR-003](003-codec-audio.md) | Codec Audio | ✅ Accepté | 2025-01-19 | +| [ADR-004](004-cdn.md) | CDN | ✅ Accepté | 2025-01-20 | + +### Security & Auth + +| ADR | Titre | Statut | Date | +|-----|-------|--------|------| +| [ADR-006](006-chiffrement.md) | Chiffrement | ✅ Accepté | 2025-01-21 | +| [ADR-008](008-authentification.md) | Authentification | ✅ Accepté | 2025-01-24 | +| [ADR-025](025-securite-secrets.md) | Sécurité & Secrets | ✅ Accepté | 2025-02-04 | + +### Testing & Quality + +| ADR | Titre | Statut | Date | +|-----|-------|--------|------| +| [ADR-007](007-tests-bdd.md) | Tests BDD | ✅ Accepté | 2025-01-22 | +| [ADR-013](013-strategie-tests.md) | Stratégie Tests | ✅ Accepté | 2025-01-27 | +| [ADR-022](022-strategie-cicd-monorepo.md) | CI/CD Monorepo | ✅ Accepté | 2025-02-02 | + +### Features & Operations + +| ADR | Titre | Statut | Date | +|-----|-------|--------|------| +| [ADR-009](009-solution-paiement.md) | Solution Paiement | ✅ Accepté | 2025-01-24 | +| [ADR-016](016-service-emailing.md) | Service Emailing | ✅ Accepté | 2025-01-29 | +| [ADR-017](017-notifications-geolocalisees.md) | Notifications Géolocalisées | ✅ Accepté | 2025-01-30 | +| [ADR-018](018-librairies-go.md) | Librairies Go | ✅ Accepté | 2025-01-30 | +| [ADR-020](020-librairies-flutter.md) | Librairies Flutter | ✅ Accepté | 2025-01-31 | +| [ADR-023](023-architecture-moderation.md) | Architecture Modération | ✅ Accepté | 2025-02-03 | +| [ADR-024](024-monitoring-observabilite.md) | Monitoring & Observabilité | ✅ Accepté | 2025-02-03 | + +## Vue d'ensemble technique consolidée + +Pour une vue d'ensemble de l'architecture et de la stack technique, consultez [docs/TECHNICAL.md](../TECHNICAL.md). + +## Légende des statuts + +- ✅ **Accepté** : Décision validée et appliquée +- 🟡 **Proposé** : En discussion +- ⏸️ **Suspendu** : Temporairement en attente +- ❌ **Rejeté** : Décision rejetée (conservée pour historique) +- 🔄 **Révisé** : Décision modifiée, voir ADR plus récent + +## Créer un nouvel ADR + +Pour documenter une nouvelle décision architecturale : + +1. Créer un fichier `XXX-titre-court.md` (numérotation séquentielle) +2. Utiliser le template suivant : + +```markdown +# ADR-XXX : Titre de la décision + +**Statut** : Proposé/Accepté/Rejeté +**Date** : YYYY-MM-DD + +## Contexte + +Pourquoi cette décision est nécessaire ? Quel problème résout-elle ? + +## Décision + +Quelle solution avons-nous choisie ? + +## Alternatives considérées + +Quelles autres options ont été évaluées ? + +## Conséquences + +### Positives +- Avantage 1 +- Avantage 2 + +### Négatives +- Limitation 1 +- Compromis accepté + +## Références + +- Liens vers documentation externe +- Benchmarks +- Articles de référence +``` + +3. Ajouter l'ADR dans ce fichier README.md et dans `mkdocs.yml` + +--- + +**Dernière mise à jour** : 2026-02-07 diff --git a/docs/domains/README.md b/docs/domains/README.md index f1418b0..c45d652 100644 --- a/docs/domains/README.md +++ b/docs/domains/README.md @@ -203,10 +203,10 @@ domains// ## Navigation - *(structure legacy, déprécié)* -- [🏛️ ADR (Architecture Decision Records)](../adr/) +- [🏛️ ADR (Architecture Decision Records)](../adr/README.md) - [⚖️ Documentation légale](../legal/README.md) - [🖥️ Interfaces UI](../interfaces/README.md) -- [🔧 Documentation technique](../technical.md) +- [🔧 Documentation technique](../TECHNICAL.md) ## Ubiquitous Language Global diff --git a/docs/domains/_shared/rules/gestion-erreurs.md b/docs/domains/_shared/rules/gestion-erreurs.md index cb5ddcc..961bba7 100644 --- a/docs/domains/_shared/rules/gestion-erreurs.md +++ b/docs/domains/_shared/rules/gestion-erreurs.md @@ -56,7 +56,7 @@ ### 12.3 Perte de réseau -**Buffer adaptatif** (cf. TECHNICAL.md) : +**Buffer adaptatif** (cf. [TECHNICAL.md](../../../TECHNICAL.md)) : | Réseau | Buffer min | Buffer cible | Buffer max | |--------|------------|--------------|------------| diff --git a/mkdocs.yml b/mkdocs.yml index 939e21b..c460b14 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -59,9 +59,10 @@ markdown_extensions: - def_list nav: - - Accueil: index.md - - Architecture Technique: technical.md + - Accueil: README.md + - Architecture Technique: TECHNICAL.md - Architecture Decision Records (ADR): + - 'Vue d''ensemble': adr/README.md - 'ADR-001: Langage Backend': adr/001-langage-backend.md - 'ADR-002: Protocole Streaming': adr/002-protocole-streaming.md - 'ADR-003: Codec Audio': adr/003-codec-audio.md