jpgiannetti/roadwave
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(docs): réorganiser structure documentation

Browse Source 
- Déplacer TECHNICAL.md vers docs/ pour cohérence
- Renommer docs/index.md en docs/README.md (convention GitHub)
- Créer docs/adr/README.md comme index des ADR
- Supprimer docs/REFACTOR-DDD.md (plan appliqué)
- Supprimer docs/technical.md (doublon)
- Mettre à jour tous les liens internes
- Mettre à jour mkdocs.yml pour nouvelle structure

Structure finale :
- README.md : vue d'ensemble projet (GitHub)
- docs/README.md : page d'accueil documentation (MkDocs)
- docs/TECHNICAL.md : architecture technique
- docs/adr/README.md : index des 25 ADR
This commit is contained in:
jpgiannetti
2026-02-07 19:56:40 +01:00
parent 2c0522158c
commit cf7a46be27
9 changed files with 173 additions and 651 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
CLAUDE.md
View File

@@ -288,7 +288,7 @@ Zitadel handles authentication ([ADR-008](docs/adr/008-authentification.md)):
## Performance Targets ## Performance Targets
See [TECHNICAL.md](TECHNICAL.md) for detailed metrics: See [TECHNICAL.md](docs/TECHNICAL.md) for detailed metrics:
- API latency p99: < 100ms - API latency p99: < 100ms
- Audio start time: < 3s - Audio start time: < 3s
- Target availability: 99.9% - Target availability: 99.9%

228
TECHNICAL.md
View File

@@ -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<br/>iOS/Android<br/>Flutter"]
carplay["CarPlay /<br/>Android Auto"]
end
subgraph ovh["OVH VPS Essential (Gravelines, France)"]
nginx["NGINX Cache<br/>+ Let's Encrypt<br/>TLS 1.3, Rate Limiting"]
api["API Gateway<br/>Go + Fiber :8080"]
subgraph services["Backend Services (Monolithe Modulaire)"]
auth["Auth Service<br/>JWT validation"]
user["User Service<br/>Profils, Jauges"]
content["Content/Geo Service<br/>Recommandations<br/>PostGIS queries"]
streaming["Streaming Service<br/>HLS generation"]
payment["Payment Service<br/>Mangopay integration"]
notif["Notification Service<br/>FCM/APNS"]
end
zitadel["Zitadel IdP<br/>OAuth2 PKCE<br/>:8081"]
ip2loc["IP2Location DB<br/>SQLite ~50MB<br/>Mode dégradé"]
subgraph data["Données"]
pgbouncer["PgBouncer<br/>Connection pooling<br/>:6432"]
postgres["PostgreSQL 16<br/>+ PostGIS 3.4<br/>Schémas:<br/>- roadwave<br/>- zitadel"]
redis["Redis 7 Cluster<br/>Cache + Geospatial<br/>GEORADIUS"]
end
end
subgraph external["Services Externes"]
storage["OVH Object Storage<br/>Fichiers audio HLS"]
mangopay["Mangopay<br/>Paiements, KYC"]
brevo["Brevo<br/>Emails transactionnels"]
fcm["FCM / APNS<br/>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.

0
docs/index.md → docs/README.md
View File

370
docs/REFACTOR-DDD.md
View File

@@ -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

89
docs/technical.md → docs/TECHNICAL.md
View File

@@ -31,7 +31,7 @@
| **Monitoring** | Prometheus + Grafana | [ADR-024](adr/024-monitoring-observabilite.md) | | **Monitoring** | Prometheus + Grafana | [ADR-024](adr/024-monitoring-observabilite.md) |
| **Secrets** | Vault + sealed secrets | [ADR-025](adr/025-securite-secrets.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 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 ## Architecture Services
```mermaid ```mermaid
flowchart LR flowchart TB
subgraph clients["📱 Clients"] subgraph clients["Clients"]
direction TB
mobile["Mobile Apps<br/>iOS/Android<br/>Flutter"] mobile["Mobile Apps<br/>iOS/Android<br/>Flutter"]
carplay["CarPlay /<br/>Android Auto"] carplay["CarPlay /<br/>Android Auto"]
end end
subgraph ovh["🇫🇷 OVH VPS Essential (Gravelines, France)"] subgraph ovh["OVH VPS Essential (Gravelines, France)"]
direction TB nginx["NGINX Cache<br/>+ Let's Encrypt<br/>TLS 1.3, Rate Limiting"]
api["API Gateway<br/>Go + Fiber :8080"]
nginx["🌐 NGINX<br/>Cache + TLS 1.3<br/>Rate Limiting"] subgraph services["Backend Services (Monolithe Modulaire)"]
api["🚪 API Gateway<br/>Go + Fiber<br/>:8080"] auth["Auth Service<br/>JWT validation"]
user["User Service<br/>Profils, Jauges"]
subgraph services["Backend (Monolithe Modulaire)"] content["Content/Geo Service<br/>Recommandations<br/>PostGIS queries"]
direction LR streaming["Streaming Service<br/>HLS generation"]
auth["🔐 Auth"] payment["Payment Service<br/>Mangopay integration"]
user["👤 User"] notif["Notification Service<br/>FCM/APNS"]
content["🎙️ Content/Geo"]
streaming["📡 Streaming"]
payment["💳 Payment"]
notif["🔔 Notif"]
end end
zitadel["🔑 Zitadel<br/>OAuth2 PKCE<br/>:8081"] zitadel["Zitadel IdP<br/>OAuth2 PKCE<br/>:8081"]
ip2loc["🌍 IP2Location<br/>SQLite 50MB"] ip2loc["IP2Location DB<br/>SQLite ~50MB<br/>Mode dégradé"]
subgraph data["💾 Données"] subgraph data["Données"]
direction TB pgbouncer["PgBouncer<br/>Connection pooling<br/>:6432"]
pgbouncer["PgBouncer<br/>:6432"] postgres["PostgreSQL 16<br/>+ PostGIS 3.4<br/>Schémas:<br/>- roadwave<br/>- zitadel"]
postgres["PostgreSQL 16<br/>+ PostGIS 3.4"] redis["Redis 7 Cluster<br/>Cache + Geospatial<br/>GEORADIUS"]
redis["Redis 7<br/>Cache + Geo"]
end end
end end
subgraph external["☁️ Services Externes"] subgraph external["Services Externes"]
direction TB storage["OVH Object Storage<br/>Fichiers audio HLS"]
storage["OVH Object Storage<br/>(Fichiers HLS)"] mangopay["Mangopay<br/>Paiements, KYC"]
mangopay["Mangopay<br/>(Paiements/KYC)"] brevo["Brevo<br/>Emails transactionnels"]
brevo["Brevo<br/>(Emails)"] fcm["FCM / APNS<br/>Push notifications"]
fcm["FCM/APNS<br/>(Push)"]
end end
%% Flux clients mobile --> nginx
clients --> nginx carplay --> nginx
nginx --> api nginx --> api
api --> auth
%% API vers services api --> user
api --> services api --> content
api --> streaming
api --> payment
api --> notif
api --> ip2loc api --> ip2loc
%% Services vers infra
auth --> zitadel auth --> zitadel
user --> data user --> pgbouncer
content --> data user --> redis
content --> pgbouncer
content --> redis
streaming --> storage streaming --> storage
payment --> mangopay payment --> mangopay
notif --> fcm notif --> fcm
%% Infra interne
zitadel --> pgbouncer zitadel --> pgbouncer
pgbouncer --> postgres pgbouncer --> postgres
%% Retours vers clients brevo -.email.-> mobile
brevo -.email.-> clients fcm -.push.-> mobile
fcm -.push.-> clients
style ovh fill:#e3f2fd,stroke:#1976d2,stroke-width:2px style ovh fill:#e3f2fd
style external fill:#fff3e0,stroke:#f57c00,stroke-width:2px style external fill:#fff3e0
style clients fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px style clients fill:#f3e5f5
style data fill:#e8f5e9,stroke:#388e3c,stroke-width:2px style data fill:#e8f5e9
style services fill:#fff,stroke:#666,stroke-width:1px
``` ```
**Souveraineté** : 100% données en France (RGPD compliant) **Souveraineté** : 100% données en France (RGPD compliant)

124
docs/adr/README.md Normal file
View File

@@ -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

4
docs/domains/README.md
View File

@@ -203,10 +203,10 @@ domains/<domain>/
## Navigation ## Navigation
- *(structure legacy, déprécié)* - *(structure legacy, déprécié)*
- [🏛️ ADR (Architecture Decision Records)](../adr/) - [🏛️ ADR (Architecture Decision Records)](../adr/README.md)
- [⚖️ Documentation légale](../legal/README.md) - [⚖️ Documentation légale](../legal/README.md)
- [🖥️ Interfaces UI](../interfaces/README.md) - [🖥️ Interfaces UI](../interfaces/README.md)
- [🔧 Documentation technique](../technical.md) - [🔧 Documentation technique](../TECHNICAL.md)
## Ubiquitous Language Global ## Ubiquitous Language Global

2
docs/domains/_shared/rules/gestion-erreurs.md
View File

@@ -56,7 +56,7 @@
### 12.3 Perte de réseau ### 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 | | Réseau | Buffer min | Buffer cible | Buffer max |
|--------|------------|--------------|------------| |--------|------------|--------------|------------|

5
mkdocs.yml
View File

@@ -59,9 +59,10 @@ markdown_extensions:
- def_list - def_list
nav: nav:
- Accueil: index.md - Accueil: README.md
- Architecture Technique: technical.md - Architecture Technique: TECHNICAL.md
- Architecture Decision Records (ADR): - Architecture Decision Records (ADR):
- 'Vue d''ensemble': adr/README.md
- 'ADR-001: Langage Backend': adr/001-langage-backend.md - 'ADR-001: Langage Backend': adr/001-langage-backend.md
- 'ADR-002: Protocole Streaming': adr/002-protocole-streaming.md - 'ADR-002: Protocole Streaming': adr/002-protocole-streaming.md
- 'ADR-003: Codec Audio': adr/003-codec-audio.md - 'ADR-003: Codec Audio': adr/003-codec-audio.md