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

docs: résoudre incohérences #13 et #14 (emails + K8s)

Browse Source 
Résolution de 2 incohérences MODERATE (reste 1/9) :

#13 - Emails techniques uniquement (ADR-018)
- Périmètre strict : auth, sécurité, modération, RGPD uniquement
- Pas de notifications sociales/marketing/newsletters
- Projection coûts : 93 emails/jour en MVP → gratuit
- Condensé : 112 → 75 lignes

#14 - Kubernetes roadmap clarifiée (ADR-001, ADR-017)
- ADR-001 : K8s = bonus scalabilité future, pas raison principale
- Go choisi pour simplicité, écosystème, performance
- ADR-017 : Roadmap 3 phases avec triggers métriques
  - MVP (0-20K) : VPS + Docker Compose (~14€)
  - Croissance (20-100K) : Scaleway managé (~100€)
  - Scale (100K+) : Kubernetes (~500€)
- Condensé : 137 → 65 lignes

INCONSISTENCIES-ANALYSIS.md :
- 8/9 MODERATE traités (6 résolus, 1 annulé, 1 documenté)
- 1 MODERATE restant : #15 (Unlike Manuel)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
jpgiannetti
2026-02-01 12:19:13 +01:00
parent 37c62206ad
commit b6b926b233
4 changed files with 139 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

140
docs/INCONSISTENCIES-ANALYSIS.md
View File

@@ -16,7 +16,7 @@ Cette analyse a identifié **15 incohérences** entre les décisions d'architect
|----------|--------|---------|--------|-----------------| |----------|--------|---------|--------|-----------------|
| 🔴 **CRITICAL** | 2 | 14% | ✅ **RÉSOLU** | ~~avant implémentation~~ | | 🔴 **CRITICAL** | 2 | 14% | ✅ **RÉSOLU** | ~~avant implémentation~~ |
| 🟠 **HIGH** | 2 | 14% | ✅ **RÉSOLU** (2 résolus, 1 annulé) | ~~Résolution Sprint 1-2~~ | | 🟠 **HIGH** | 2 | 14% | ✅ **RÉSOLU** (2 résolus, 1 annulé) | ~~Résolution Sprint 1-2~~ |
| 🟡 **MODERATE** | 9 | 64% | ⏳ **3 restants** (4 résolus, 1 annulé, 1 documenté) | Résolution Sprint 3-5 | | 🟡 **MODERATE** | 9 | 64% | ⏳ **1 restant** (6 résolus, 1 annulé, 1 documenté) | Résolution Sprint 3-5 |
| 🟢 **LOW** | 1 | 7% | ⏳ En cours | À clarifier lors du développement | | 🟢 **LOW** | 1 | 7% | ⏳ En cours | À clarifier lors du développement |
### Impact par Domaine ### Impact par Domaine
@@ -629,69 +629,118 @@ on:
### #13 : Coûts Email (Transition Free → Paid) ### #13 : Coûts Email (Transition Free → Paid)
**Statut** : ✅ **RÉSOLU** (Périmètre réduit : emails techniques uniquement)
| Élément | Détail | | Élément | Détail |
|---------|--------| |---------|--------|
| **ADR concernés** | ADR-018 (Email, lignes 49-52), ADR-017 (Hébergement) | | **ADR concernés** | ADR-018 (mis à jour) |
| **Règle métier** | N/A (économique) | | **Règle métier** | N/A (économique) |
| **Conflit** | ADR cite "gratuit" mais limite 9000 emails/mois → plan transition manquant | | **Conflit initial** | ~~ADR citait "gratuit" mais volume estimé dépassait 9000 emails/mois~~ |
| **Impact** | Coût surprise lors de la croissance | | **Impact initial** | ~~Coût surprise lors de la croissance~~ |
**ADR-018 spécifie** : **Décision** : **Limiter aux emails techniques uniquement** (pas de notifications, alertes marketing, newsletters)
- Brevo gratuit : 300 emails/jour = 9000/mois
- Phase MVP : 0-10K utilisateurs
**Calcul réaliste** : **Périmètre strict** :
- ✅ Authentification (vérification email, reset password, changement email)
- ✅ Sécurité (alertes connexion inhabituelle)
- ✅ Modération (strikes, suspensions)
- ✅ RGPD (confirmation suppression, export données)
- ❌ **Pas de notifications sociales** (écoutes, likes, commentaires)
- ❌ **Pas d'alertes marketing** (recommandations, nouvelles sorties)
- ❌ **Pas de newsletters/promotions**
- ❌ **Pas d'emails paiements créateurs** (Mangopay envoie déjà ses propres emails)
**Calcul révisé** (emails techniques uniquement) :
``` ```
Emails par utilisateur/mois: Emails par utilisateur/mois (régime stable):
- Vérification email: 1 - Vérification email (nouveaux users): 0.1 (10% croissance)
- Reset password: 0.1 (10%) - Reset password: 0.1 (10% des users)
- Notifications (opt-in 30%): 4 - Changement email: 0.05 (5%)
- Paiements créateurs (5%): 1 - Alertes sécurité: 0.02 (2%)
- Modération: 0.01 (1%)
Total: ~2 emails/user/mois (moyenne) Total: ~0.28 emails/user/mois
10K users × 2 = 20K emails/mois → dépassement tier gratuit 10K users × 0.28 = 2800 emails/mois = 93 emails/jour
→ Largement sous le tier gratuit (300/jour) ✅
``` ```
**Coût Brevo** : **Projection de coûts révisée** :
- Free: 0-9K emails
- Lite: 19€/mois (20K emails)
- Business: 49€/mois (50K emails)
**Actions** : | Phase | Utilisateurs | Emails/jour moyen | Coût Brevo |
- [ ] Mettre à jour ADR-018 avec projection coûts |-------|--------------|-------------------|------------|
- [ ] Implémenter alertes (90% quota atteint) | MVP | 0-10K | 93/jour | **Gratuit** ✅ |
- [ ] Plan B : Self-hosted SMTP (Postfix) si budget serré | Growth | 10K-50K | 467/jour | 19€/mois (Lite) |
| Scale | 50K-100K | 933/jour | 49€/mois (Business) |
**Gestion des pics** :
- Rate limiting : 250 emails/heure (batch processing)
- Redis queue pour lisser l'envoi sur 24-48h
- Upgrade temporaire Lite (19€) si pic > 300/jour sur 3+ jours
**Actions complétées** :
- [x] ✅ ADR-018 mis à jour avec périmètre strict et projection coûts
- [x] ✅ Clarification : pas d'emails notifications/marketing/paiements
- [x] ✅ Stratégie gestion pics d'inscription documentée
**Référence** : [ADR-018 - Service d'Emailing Transactionnel](../adr/018-service-emailing.md)
--- ---
### #14 : Kubernetes vs VPS MVP ### #14 : Kubernetes vs VPS MVP
**Statut** : ✅ **RÉSOLU** (Vision clarifiée : K8s est un bonus, pas la raison principale)
| Élément | Détail | | Élément | Détail |
|---------|--------| |---------|--------|
| **ADR concernés** | ADR-017 (Hébergement, ligne 12), ADR-001 (Go, ligne 27) | | **ADR concernés** | ADR-017 (mis à jour), ADR-001 (mis à jour) |
| **Règle métier** | N/A (infrastructure) | | **Règle métier** | N/A (infrastructure) |
| **Conflit** | ADR-001 justifie Go pour "Kubernetes first-class", mais ADR-017 utilise VPS simple | | **Conflit initial** | ~~ADR-001 justifiait Go pour "Kubernetes first-class", mais ADR-017 utilisait VPS simple~~ |
| **Impact** | Sur-architecture : pourquoi choisir Go pour K8s si pas utilisé ? | | **Impact initial** | ~~Ambiguïté : Go choisi pour K8s mais K8s pas utilisé en MVP~~ |
**Analyse** : **Analyse** :
- **ADR-001** : Go choisi notamment pour "excellent support Kubernetes" - **ADR-001 initial** : Mentionnait "Kubernetes first-class" dans tooling natif
- **ADR-017** : MVP sur OVH VPS Essential (single VM, Docker Compose) - **ADR-017 initial** : MVP sur OVH VPS Essential (Docker Compose), K8s à "100K+ users"
- **ADR-012** : Mentionne migration K8s "à 1M+ users" - **Problème perçu** : Incohérence entre choix Go (pour K8s) et infra MVP (pas K8s)
**Question** : Justification K8s prématurée ? **Clarification apportée** :
**Réponse** : **Non, acceptable** si : Go est choisi **principalement** pour :
- Vision long-terme claire (1M users = besoin K8s) 1. ✅ **Simplicité** et time-to-market (MVP 8 semaines vs 12+ Rust)
- Go apporte autres avantages (perf, concurrence, typing) 2. ✅ **Écosystème mature** (PostGIS, WebRTC, Zitadel, BDD tests)
- Coût marginal (Go vs Node.js comparable en complexité MVP) 3. ✅ **Performance concurrentielle** (1M conn/serveur suffisant)
4. ✅ **Typing fort** et tooling natif (pprof, race detector)
**Recommandation** : **Clarifier la vision** dans ADR Kubernetes est un **bonus** pour scalabilité future (Phase 3 : 100K+ users), **pas la raison principale**.
**Actions** : **Solution implémentée** :
- [ ] Mettre à jour ADR-001 : "Go pour scalabilité future (K8s), mais aussi perf/typage"
- [ ] ADR-017 : Ajouter section "Roadmap Infrastructure" (VPS → K8s) **ADR-001** : Note ajoutée clarifiant que :
- K8s n'est **pas utilisé en MVP** (Docker Compose suffit pour 0-20K users)
- Go choisi **principalement** pour simplicité, écosystème, performance
- Support K8s = **bonus** scalabilité future, pas driver du choix
**ADR-017** : Section complète "Roadmap Infrastructure" ajoutée :
| Phase | Users | Infrastructure | Trigger principal |
|-------|-------|----------------|-------------------|
| **MVP** | 0-20K | OVH VPS + Docker Compose | Aucun (démarrage) |
| **Croissance** | 20-100K | Scaleway managé | CPU > 70% OU MRR > 2000€ |
| **Scale** | 100K+ | Scaleway Kubernetes | Auto-scaling OU multi-région |
**Triggers de migration détaillés** :
- Phase 2 : CPU > 70%, latence p99 > 100ms, MRR > 2000€
- Phase 3 : Auto-scaling requis, multi-région, > 5 services backend, DevOps dédié
**Actions complétées** :
- [x] ✅ ADR-001 mis à jour : Note explicite "K8s = bonus, pas raison principale"
- [x] ✅ ADR-017 : Section "Roadmap Infrastructure" complète (3 phases + triggers)
- [x] ✅ Cohérence architecture : Vision long-terme clarifiée sans sur-architecture MVP
**Références** :
- [ADR-001 - Justification Go (K8s bonus)](../adr/001-langage-backend.md#pourquoi-go-plutôt-que-rust-)
- [ADR-017 - Roadmap Infrastructure](../adr/017-hebergement.md#roadmap-infrastructure)
--- ---
@@ -752,9 +801,10 @@ Total: ~2 emails/user/mois (moyenne)
| 9 | ✅ Clarification Points vs Pourcentages (ADR-010 + Règle 03) | Tech Writer | 0.5j | ✅ **Fait** | | 9 | ✅ Clarification Points vs Pourcentages (ADR-010 + Règle 03) | Tech Writer | 0.5j | ✅ **Fait** |
| 10 | ✅ Clarification OAuth2 protocole vs providers (ADR-008 + Règle 01) | Tech Writer | 0.5j | ✅ **Fait** | | 10 | ✅ Clarification OAuth2 protocole vs providers (ADR-008 + Règle 01) | Tech Writer | 0.5j | ✅ **Fait** |
| 11 | ✅ GeoIP Database (ADR-021 + Règle 02) | Tech Writer | 0.5j | ✅ **Fait** | | 11 | ✅ GeoIP Database (ADR-021 + Règle 02) | Tech Writer | 0.5j | ✅ **Fait** |
| 12-15 | Clarifications ADR/Règles (restantes) | Tech Writer | 2.5j | ⏳ Sprint 3-4 | | 12 | ✅ Réorganisation features BDD + CI/CD path filters (ADR-007, ADR-024) | QA Lead | 2j | ✅ **Fait** |
| 16 | Réorganisation features BDD | QA Lead | 2j | ⏳ Sprint 4 | | 13 | ✅ Projection coûts Email (ADR-018, périmètre réduit) | Tech Writer | 0.5j | ✅ **Fait** |
| 17 | Optimisation CI/CD path filters | DevOps | 1j | ⏳ Sprint 5 | | 14 | ✅ Clarification Kubernetes (ADR-001, ADR-017 roadmap) | Tech Writer | 0.5j | ✅ **Fait** |
| 15 | Clarification Unlike Manuel (Règle 03 + ADR-010) | Tech Writer | 0.5j | ⏳ Sprint 3-4 |
--- ---
@@ -764,15 +814,15 @@ Total: ~2 emails/user/mois (moyenne)
|----------|----------------|-------|--------| |----------|----------------|-------|--------|
| Incohérences CRITICAL | 2 | 0 | ✅ **0** (2/2 résolues) | | Incohérences CRITICAL | 2 | 0 | ✅ **0** (2/2 résolues) |
| Incohérences HIGH | 4 | 0 | ✅ **0** (2 résolues, 1 annulée) | | Incohérences HIGH | 4 | 0 | ✅ **0** (2 résolues, 1 annulée) |
| Incohérences MODERATE | 9 | ≤2 | ⏳ **3 restantes** (#7-#12 traités : 4 résolus + 1 annulé + 1 documenté) | | Incohérences MODERATE | 9 | ≤2 | ✅ **1 restante** (#7-#14 traités : 6 résolus + 1 annulé + 1 documenté) |
| ADR à jour | 66% (12/18) | 100% | ✅ **100%** (19/19 - ADR-007 et ADR-016 mis à jour) | | ADR à jour | 66% (12/18) | 100% | ✅ **100%** (19/19 - ADR-018 mis à jour) |
| Coverage documentation | N/A | >90% | ✅ **95%** | | Coverage documentation | N/A | >90% | ✅ **95%** |
**Dernière mise à jour** : 2026-02-01 **Dernière mise à jour** : 2026-02-01
**Détail MODERATE** : **Détail MODERATE** :
- ✅ **Traités (6/9)** : #7 (résolu), #8 (résolu), #9 (résolu), #10 (résolu), #11 (annulé), #12 (documenté) - ✅ **Traités (8/9)** : #7 (résolu), #8 (résolu), #9 (résolu), #10 (résolu), #11 (annulé), #12 (documenté), #13 (résolu), #14 (résolu)
- ⏳ **Restants (3/9)** : #13 (Coûts Email), #14 (Kubernetes vs VPS), #15 (Unlike Manuel) - ⏳ **Restant (1/9)** : #15 (Unlike Manuel)
--- ---

4
docs/adr/001-langage-backend.md
View File

@@ -47,8 +47,10 @@ Rust offre meilleures performances absolues (2M conn/serveur vs 1M, 0 GC pauses)
4. **Tooling natif** : 4. **Tooling natif** :
- pprof intégré (CPU, mémoire) - pprof intégré (CPU, mémoire)
- race detector systématique - race detector systématique
- Kubernetes first-class
- Cold start ~10ms (vs ~50ms Rust) - Cold start ~10ms (vs ~50ms Rust)
- **Scalabilité future** : Excellent support Kubernetes (migration prévue à 100K+ users, voir [ADR-017](017-hebergement.md#roadmap-infrastructure))
**Note importante** : Kubernetes n'est **pas utilisé en MVP** (Docker Compose sur VPS suffit pour 0-20K users). Go est choisi **principalement** pour sa **simplicité**, son **écosystème mature** et ses **performances concurrentielles**. Le support K8s est un **bonus** pour la scalabilité future, pas la raison principale du choix.
### Quand Rust aurait du sens ### Quand Rust aurait du sens

18
docs/adr/017-hebergement.md
View File

@@ -43,13 +43,19 @@ OVH Object Storage (~1.20€/100GB)
└── Fichiers audio source └── Fichiers audio source
``` ```
## Évolution prévue ## Roadmap Infrastructure
| Phase | Users | Infrastructure | Coût estimé | | Phase | Users | Infrastructure | Coût | Trigger migration |
|-------|-------|----------------|-------------| |-------|-------|----------------|------|-------------------|
| MVP | 0-20K | OVH VPS Essential | ~14€/mois | | **MVP** | 0-20K | OVH VPS + Docker Compose | ~14€ | Aucun |
| Croissance | 20-100K | Scaleway + PostgreSQL managé | ~100€/mois | | **Croissance** | 20-100K | Scaleway services managés (PostgreSQL, Redis) | ~100€ | CPU > 70% OU MRR > 2000€ |
| Scale | 100K+ | Scaleway Kubernetes | ~500€/mois | | **Scale** | 100K+ | Scaleway Kubernetes (Kapsule) | ~500€ | Auto-scaling OU multi-région |
**Triggers détaillés** :
- **Phase 2** : CPU > 70% (7j), latence p99 > 100ms, backups > 1h/semaine, MRR > 2000€
- **Phase 3** : Auto-scaling horizontal requis, multi-région Europe, DevOps dédié, > 5 services
**Note** : Migrations déclenchées par métriques réelles, pas calendrier fixe.
## Conséquences ## Conséquences

45
docs/adr/018-service-emailing.md
View File

@@ -5,11 +5,22 @@
## Contexte ## Contexte
RoadWave nécessite un service d'envoi d'emails transactionnels pour notifications utilisateurs, modération (strikes, suspensions), authentification (Zitadel), conformité RGPD et communications créateurs. RoadWave nécessite un service d'envoi d'emails **techniques uniquement** (pas de notifications sociales, alertes marketing, promotions).
**Volume estimé MVP** : 2000-5000 emails/mois. **Périmètre strict** :
- ✅ **Authentification** : Vérification email (inscription), réinitialisation mot de passe, changement email
- ✅ **Sécurité** : Alertes connexion inhabituelle, changement password
- ✅ **Modération** : Strikes, suspensions, bannissements
- ✅ **RGPD** : Confirmation suppression compte, export données
- ❌ **Pas de notifications sociales** (écoutes, likes, commentaires, nouveaux abonnés)
- ❌ **Pas d'alertes marketing** (nouvelles sorties, recommandations personnalisées)
- ❌ **Pas de newsletters/promotions**
**Contraintes** : Souveraineté préférée (France/UE), RGPD natif, coût maîtrisé, API simple pour Go, capacité SMS future (post-MVP). **Justification** : Gérer un service d'emailing complet (notifications, newsletters, segmentation) est un produit à part entière (délivrabilité, spam, désabonnements, conformité). RoadWave se concentre sur le strict minimum technique pour réduire la complexité et les coûts.
**Volume estimé MVP** : 2800-3500 emails/mois (~93-116 emails/jour en régime stable).
**Contraintes** : Souveraineté préférée (France/UE), RGPD natif, coût maîtrisé, API simple pour Go.
## Décision ## Décision
@@ -42,21 +53,23 @@ Backend Go → Brevo API REST → Utilisateurs
└── [Post-MVP] SMS └── [Post-MVP] SMS
``` ```
## Estimation coûts ## Projection de coûts
| Phase | Utilisateurs | Emails/mois | Coût Brevo | | Phase | Users | Emails/jour | Coût Brevo |
|-------|--------------|-------------|------------| |-------|-------|-------------|------------|
| MVP | 0-10K | ~5K/jour | **Gratuit** (< 300/jour) | | **MVP** | 0-10K | ~93/jour | **Gratuit** ✅ (< 300/jour) |
| Growth | 10K-50K | ~10K/mois | Gratuit ou 19€/mois | | **Growth** | 10K-50K | ~467/jour | 19€/mois (Lite) |
| Scale | 50K-100K | ~100K/mois | 49€/mois | | **Scale** | 50K-100K | ~933/jour | 49€/mois (Business) |
**SMS** (post-MVP) : ~0.04€/SMS France, soit ~400€/mois pour 10K inscriptions/mois. **Calcul** : ~0.28 emails/user/mois (vérification, reset password, sécurité, modération)
**Gestion pics** : Rate limiting 250 emails/h, Redis queue, upgrade temporaire si > 300/jour sur 3+ jours
## Conséquences ## Conséquences
- Coût 0 en MVP (9000 emails/mois gratuits) - Coût MVP : 0€ (93 emails/jour << 300/jour gratuit)
- SMS intégré pour vérification anti-spam (post-MVP) - Rate limiting requis en cas de pic inscription (> 300/jour)
- API REST simple, pas de SDK Go officiel - Configuration DNS (SPF, DKIM, DMARC) pour délivrabilité
- Limites quotidiennes strictes (300/jour en gratuit) - Wrapper Go custom (pas de SDK officiel)
- Migration possible vers Scaleway TEM si volume >100K emails/mois (coût optimisé) - **Aucun email** pour interactions sociales (à communiquer dans UX)
- Configuration DNS requise (SPF, DKIM, DMARC) - **Aucun email** pour paiements créateurs (Mangopay gère, dashboard in-app suffit)