# Context Map RoadWave

## Vue d'ensemble

RoadWave est organisé selon les principes du **Domain-Driven Design (DDD)** avec **7 bounded contexts** clairs. Cette architecture modulaire permet une meilleure séparation des préoccupations, facilite la maintenance et l'évolution du système.

## Architecture des domaines

```mermaid
graph TB
    subgraph "Core Domain"
        SHARED[_shared<br/>Authentification, RGPD, Erreurs]
    end

    subgraph "Supporting Subdomains"
        RECO[recommendation<br/>Jauges & Algorithme]
        CONTENT[content<br/>Audio-guides & Live]
        MODERATION[moderation<br/>Signalements & Sanctions]
    end

    subgraph "Generic Subdomains"
        ADS[advertising<br/>Publicités]
        PREMIUM[premium<br/>Abonnements]
        MONETIZATION[monetization<br/>Monétisation créateurs]
    end

    %% Dépendances principales
    RECO --> SHARED
    RECO --> CONTENT
    CONTENT --> SHARED
    ADS --> SHARED
    ADS --> RECO
    PREMIUM --> SHARED
    PREMIUM --> CONTENT
    MONETIZATION --> SHARED
    MONETIZATION --> CONTENT
    MONETIZATION --> ADS
    MONETIZATION --> PREMIUM
    MODERATION --> SHARED
    MODERATION --> CONTENT

    %% Relations anti-corruption
    ADS -.-|bloqué par| PREMIUM
    MODERATION -.->|peut démonétiser| MONETIZATION
```

## Bounded Contexts

### Core Domain

#### 🔐 [_shared](/_shared/)
**Responsabilité** : Fonctionnalités transversales essentielles

- Authentification et inscription via Zitadel
- Conformité RGPD (consentements, suppression données)
- Gestion cohérente des erreurs
- Entités centrales : `USERS`, `CONTENTS`, `SUBSCRIPTIONS`, `LISTENING_HISTORY`

**Utilisé par** : Tous les autres domaines

---

### Supporting Subdomains

#### 🎯 [recommendation](/recommendation/)
**Responsabilité** : Recommandation géolocalisée de contenus

- Jauges de centres d'intérêt (scores dynamiques 0-100)
- Algorithme de scoring (distance + affinité)
- Adaptation selon interactions utilisateur
- Entités : `USER_INTERESTS`, `INTEREST_CATEGORIES`

**Dépend de** : `_shared`, `content`

**Ubiquitous Language** : Interest Gauge, Recommendation Score, Geographic Priority, Interest Decay

---

#### 🎙️ [content](/content/)
**Responsabilité** : Création et diffusion de contenus audio

- Audio-guides multi-séquences géolocalisés
- Radio live et enregistrements
- Contenus géolocalisés pour voiture/piéton
- Détection de contenu protégé (droits d'auteur)
- Entités : `AUDIO_GUIDES`, `LIVE_STREAMS`, `GUIDE_SEQUENCES`, `LIVE_RECORDINGS`

**Dépend de** : `_shared`

**Interagit avec** : `moderation` (modération), `monetization` (revenus)

**Ubiquitous Language** : Audio Guide, Guide Sequence, Live Stream, Geofence, Content Fingerprint

---

#### 🛡️ [moderation](/moderation/)
**Responsabilité** : Modération et sécurité de la plateforme

- Workflow de traitement des signalements
- Système de strikes et sanctions
- Processus d'appel
- Badges de confiance créateurs
- Modération communautaire
- Entités : `REPORTS`, `SANCTIONS`, `APPEALS`, `STRIKES`, `BADGES`

**Dépend de** : `_shared`, `content`

**Peut affecter** : `monetization` (démonétisation)

**Ubiquitous Language** : Report, Strike, Sanction, Appeal, Trust Badge, Community Moderation

---

### Generic Subdomains

#### 📢 [advertising](/advertising/)
**Responsabilité** : Publicités audio géociblées

- Campagnes publicitaires
- Ciblage géographique et par intérêts
- Métriques (impressions, CPM)
- Insertion dynamique dans flux audio
- Entités : `AD_CAMPAIGNS`, `AD_METRICS`, `AD_IMPRESSIONS`

**Dépend de** : `_shared`, `recommendation` (ciblage)

**Bloqué par** : `premium` (pas de pub pour abonnés)

**Ubiquitous Language** : Ad Campaign, Ad Impression, CPM, Ad Targeting, Skip Rate

---

#### 💎 [premium](/premium/)
**Responsabilité** : Abonnements et fonctionnalités premium

- Abonnements payants (mensuel/annuel)
- Mode offline (téléchargement, synchro)
- Notifications personnalisées
- Avantages : sans pub, qualité audio supérieure
- Entités : `PREMIUM_SUBSCRIPTIONS`, `ACTIVE_STREAMS`, `OFFLINE_DOWNLOADS`

**Dépend de** : `_shared`, `content`

**Bloque** : `advertising` (désactivation pubs)

**Ubiquitous Language** : Premium Subscription, Offline Download, Sync Queue, Premium Tier, Auto-Renewal

---

#### 💰 [monetization](/monetization/)
**Responsabilité** : Monétisation des créateurs

- KYC (vérification identité)
- Calcul des revenus (pub + abonnements)
- Versements mensuels via Mangopay
- Tableaux de bord revenus
- Entités : `CREATOR_MONETIZATION`, `REVENUES`, `PAYOUTS`

**Dépend de** : `_shared`, `content`, `advertising`, `premium`

**Affecté par** : `moderation` (démonétisation en cas de sanction)

**Ubiquitous Language** : Revenue Share, KYC Verification, Payout, Minimum Threshold

---

## Relations entre domaines

### Upstream/Downstream

| Upstream (Fournisseur) | Downstream (Consommateur) | Type de relation |
|------------------------|---------------------------|------------------|
| `_shared` | Tous | **Kernel partagé** |
| `content` | `recommendation` | **Customer/Supplier** |
| `recommendation` | `advertising` | **Customer/Supplier** |
| `premium` | `advertising` | **Anti-Corruption Layer** |

### Événements de domaine

Les domaines communiquent via des événements métier :

- **UserRegistered** (`_shared` → tous) : Nouvel utilisateur
- **ContentPublished** (`content` → `recommendation`, `moderation`) : Nouveau contenu
- **InterestGaugeUpdated** (`recommendation` → `advertising`) : Mise à jour jauges
- **UserBanned** (`moderation` → `monetization`) : Bannissement utilisateur
- **SubscriptionActivated** (`premium` → `advertising`) : Activation premium

## Structure de la documentation

Chaque domaine suit cette organisation :

```
domains/<domain>/
├── README.md              # Vue d'ensemble du domaine
├── rules/                 # Règles métier (*.md)
├── entities/              # Diagrammes entités (*.md)
├── sequences/             # Diagrammes séquences (*.md)
├── states/                # Diagrammes états (*.md)
├── flows/                 # Diagrammes flux (*.md)
└── features/              # Tests BDD Gherkin (*.feature)
```

## Navigation

-  *(structure legacy, déprécié)*
- [🏛️ ADR (Architecture Decision Records)](../adr/README.md)
- [⚖️ Documentation légale](../legal/README.md)
- [🖥️ Interfaces UI](../interfaces/README.md)
- [🔧 Documentation technique](../TECHNICAL.md)

## Ubiquitous Language Global

**Termes transversaux utilisés dans tous les domaines** :

- **User** : Utilisateur (auditeur, créateur, ou les deux)
- **Content** : Contenu audio diffusé sur la plateforme
- **Creator** : Utilisateur créant du contenu
- **Geolocation** : Position GPS de l'utilisateur
- **Stream** : Flux de lecture audio
- **Subscription** : Abonnement (à un créateur ou à premium)
- **Interest** : Centre d'intérêt (automobile, voyage, musique, etc.)

## Principes d'architecture

1. **Bounded Contexts clairs** : Chaque domaine a des limites bien définies
2. **Autonomie des domaines** : Chaque domaine peut évoluer indépendamment
3. **Communication asynchrone** : Préférence pour les événements vs appels directs
4. **Anti-Corruption Layer** : Protection contre les changements externes
5. **Alignment code/docs** : Structure docs ↔ structure `backend/internal/`

## Alignement avec le code backend

```
backend/internal/         docs/domains/
├── auth/         ←→     _shared/
├── user/         ←→     _shared/
├── content/      ←→     content/
├── geo/          ←→     recommendation/
├── streaming/    ←→     content/
├── moderation/   ←→     moderation/
├── payment/      ←→     monetization/
└── analytics/    ←→     recommendation/
```

---

**Dernière mise à jour** : 2026-02-07
**Statut** : ✅ Active
**Auteur** : Documentation DDD initiative