veza/docs/VEZA_PROJECT_DOCUMENTATION.md

# Veza — Documentation Complète du Projet

> **Plateforme de streaming musical éthique**
> Version du document : 2026-03-16 | Statut : Production-Ready (v1.0.0-rc1)

---

## Table des matières

1. [Vision et Mission](#1-vision-et-mission)
2. [Pourquoi Veza existe](#2-pourquoi-veza-existe)
3. [Principes fondateurs](#3-principes-fondateurs)
4. [Fonctionnalités de la plateforme](#4-fonctionnalités-de-la-plateforme)
5. [Architecture technique](#5-architecture-technique)
6. [Stack technologique](#6-stack-technologique)
7. [Backend API (Go)](#7-backend-api-go)
8. [Serveur de streaming (Rust)](#8-serveur-de-streaming-rust)
9. [Frontend (React/TypeScript)](#9-frontend-reacttypescript)
10. [Infrastructure et déploiement](#10-infrastructure-et-déploiement)
11. [Sécurité](#11-sécurité)
12. [Modèle économique](#12-modèle-économique)
13. [Parcours utilisateur](#13-parcours-utilisateur)
14. [Conformité et vie privée](#14-conformité-et-vie-privée)
15. [Performance et scalabilité](#15-performance-et-scalabilité)
16. [Historique des versions](#16-historique-des-versions)
17. [Roadmap](#17-roadmap)
18. [Équipe et processus de développement](#18-équipe-et-processus-de-développement)
19. [Glossaire](#19-glossaire)

---

## 1. Vision et Mission

**Veza** est une plateforme de streaming musical conçue pour remettre l'artiste au centre de l'écosystème musical numérique.

### Mission

> Créer une plateforme de streaming musical transparente, équitable et respectueuse — où les créateurs sont rémunérés justement, les utilisateurs ne sont pas manipulés, et la technologie sert la musique plutôt que l'inverse.

### Vision

Dans un paysage dominé par des plateformes qui optimisent l'engagement au détriment des créateurs et des auditeurs, Veza propose une alternative fondée sur trois piliers :

| Pilier | Engagement |
|--------|------------|
| **Équité créateur** | Commission marketplace de 15% (vs 30% industrie), paiements hebdomadaires, analytics détaillés |
| **Respect utilisateur** | Zéro dark pattern, pas de tracking comportemental, flux chronologique |
| **Transparence technologique** | Pas d'algorithme opaque, découverte par tags/genres déclaratifs, métriques de popularité privées |

---

## 2. Pourquoi Veza existe

### Le problème

Les plateformes de streaming actuelles souffrent de défauts structurels :

- **Rémunération dérisoire des artistes** — Les petits créateurs reçoivent des fractions de centimes par écoute, avec des paiements trimestriels.
- **Algorithmes opaques** — Les systèmes de recommandation favorisent les artistes déjà populaires, créant un effet de concentration.
- **Dark patterns UX** — Notifications manipulatrices, FOMO artificiel, friction à la désinscription.
- **Exploitation des données comportementales** — Le comportement des utilisateurs est traqué, analysé et monétisé pour maximiser le temps d'écoute.
- **Gamification addictive** — Streaks, badges, leaderboards transforment l'écoute musicale en jeu compulsif.

### La solution Veza

| Problème | Approche Veza |
|----------|---------------|
| Rémunération insuffisante | Commission de 15%, paiements hebdomadaires (seuil $50) |
| Algorithmes opaques | Feed chronologique, découverte par tags/genres déclaratifs |
| Dark patterns | Aucun FOMO, notifications respectueuses, quiet hours |
| Tracking comportemental | Zéro données comportementales pour le ranking |
| Gamification | Aucun XP, streak, leaderboard, badge |
| Métriques publiques | Likes et play counts visibles uniquement par le créateur |

---

## 3. Principes fondateurs

Ces principes sont inscrits dans le code source et ne peuvent être contournés :

### 3.1 Ce que Veza ne fera JAMAIS

1. **Pas d'IA/ML pour les recommandations** — Pas de TensorFlow, PyTorch, ou scikit-learn. La découverte est humaine.
2. **Pas de blockchain/Web3** — Pas de NFT, smart contracts, ou wallets crypto.
3. **Pas de gamification** — Pas d'XP, de streaks, de leaderboards, de badges ou de niveaux.
4. **Pas de métriques de popularité publiques** — Les compteurs de likes et d'écoutes sont privés (visibles uniquement par le créateur dans ses analytics).
5. **Pas de dark patterns UX** — Pas de FOMO, pas de notifications push manipulatrices, pas de friction à la désinscription.
6. **Pas de données comportementales pour le ranking** — Le feed est chronologique. La découverte est par tags et genres déclarés par l'artiste.

### 3.2 Ce que Veza garantit

- **Transparence totale** sur le fonctionnement de la plateforme
- **Portabilité des données** — Export complet à tout moment (RGPD)
- **Suppression réelle** — Les données sont effectivement supprimées, pas masquées
- **Accessibilité** — Interface WCAG AA compliant, navigation clavier complète
- **Internationalisation** — Disponible en français, anglais et espagnol

---

## 4. Fonctionnalités de la plateforme

### 4.1 Pour les auditeurs

| Fonctionnalité | Description |
|----------------|-------------|
| **Écoute en streaming** | HLS adaptatif (qualité auto-ajustée selon la bande passante) |
| **Recherche unifiée** | Recherche full-text sur les tracks, artistes et playlists (Elasticsearch + fallback PostgreSQL) |
| **Découverte éthique** | Navigation par genres, tags, moods — pas d'algorithme comportemental |
| **Playlists** | Création, édition, collaboration, partage public, import/export (JSON, CSV, M3U) |
| **Playlists collaboratives** | Inviter d'autres utilisateurs à contribuer avec des rôles (viewer, editor, admin) |
| **File d'attente** | Gestion de queue avec drag-and-drop, sessions partagées |
| **Feed chronologique** | Flux des artistes suivis, strictement chronologique |
| **Profils utilisateur** | Avatars, bio, liens, historique d'écoute (privé) |
| **Notifications** | In-app, email digest, préférences granulaires, quiet hours |
| **Chat** | Messagerie temps réel, réactions emoji, mentions, threads |
| **Co-écoute** | Sessions synchronisées d'écoute entre amis |
| **Social** | Follow/unfollow, groupes communautaires, posts |
| **Lecteur avancé** | Vitesse de lecture (0.5x-2x), crossfade, normalisation audio, PiP |
| **PWA** | Application installable, mode offline partiel, contrôles lockscreen |
| **Multi-langue** | Interface en FR, EN, ES avec détection automatique |

### 4.2 Pour les créateurs

| Fonctionnalité | Description |
|----------------|-------------|
| **Upload** | Upload simple ou par chunks (reprise possible), multi-format |
| **Analytics privés** | Écoutes, sources de trafic, données géographiques (anonymisées), devices |
| **Analytics avancés** | Heatmaps d'écoute par track, comparaison de périodes, alertes métriques |
| **Marketplace** | Vente de beats, samples, kits avec système de licences (Basic, Premium, Exclusive) |
| **Distribution** | Distribution vers Spotify, Apple Music, Deezer via partenaire |
| **Formation** | Création et vente de cours avec vidéos HLS, modules, certificats |
| **Live streaming** | Diffusion live via OBS (RTMP), chat intégré, co-hosting |
| **Stems** | Upload et partage de stems individuels pour remixage |
| **Versioning** | Historique de versions des tracks avec restauration |
| **Cloud storage** | Stockage cloud avec dossiers, versioning et partage |
| **Gestion d'équipement** | Inventaire de gear avec photos, documents, historique de réparations |
| **Payouts** | Paiements automatiques hebdomadaires via Stripe Connect |
| **KYC** | Vérification d'identité vendeur via Stripe Identity |

### 4.3 Pour les administrateurs

| Fonctionnalité | Description |
|----------------|-------------|
| **Dashboard admin** | Métriques plateforme, gestion utilisateurs, gestion contenu |
| **Modération** | File de rapports, détection de spam, fingerprinting audio (ACRCloud) |
| **Strikes & appels** | Système de sanctions avec possibilité d'appel |
| **Feature flags** | Activation/désactivation de fonctionnalités en temps réel |
| **Annonces** | Annonces plateforme visibles par tous les utilisateurs |
| **Mode maintenance** | Activation du mode maintenance avec message personnalisé |
| **Audit logs** | Historique complet de toutes les actions admin |
| **Gestion paiements** | Vue d'ensemble des paiements, remboursements |

### 4.4 Pour les développeurs

| Fonctionnalité | Description |
|----------------|-------------|
| **API publique** | API REST documentée (OpenAPI 3.0 / Swagger UI) |
| **Clés API** | Génération de clés avec scopes et rate limits par clé |
| **Webhooks** | Notifications d'événements vers des endpoints externes |

---

## 5. Architecture technique

### 5.1 Vue d'ensemble

```
┌─────────────────────────────────────────────────────────────────┐
│                        CLIENTS                                   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐    │
│  │ Web App  │  │ PWA      │  │ API      │  │ OBS (RTMP)   │    │
│  │ (React)  │  │ (Mobile) │  │ Externe  │  │ Live Stream  │    │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └──────┬───────┘    │
└───────┼──────────────┼──────────────┼──────────────┼────────────┘
        │              │              │              │
        ▼              ▼              ▼              ▼
┌───────────────────────────────────────────────────────────────┐
│                     COUCHE API                                 │
│  ┌─────────────────────────────┐  ┌─────────────────────────┐ │
│  │     Backend API (Go/Gin)    │  │  Stream Server (Rust)   │ │
│  │                             │  │                         │ │
│  │  • REST API (/api/v1/...)   │  │  • HLS Streaming        │ │
│  │  • WebSocket (chat, notif)  │  │  • Transcodage audio    │ │
│  │  • Auth (JWT RS256)         │  │  • WebSocket (sync)     │ │
│  │  • Rate limiting            │  │  • Adaptive bitrate     │ │
│  │  • CSRF protection          │  │  • Co-écoute            │ │
│  │  Port: 8080                 │  │  Port: 18082            │ │
│  └──────────┬──────────────────┘  └────────────┬────────────┘ │
└─────────────┼──────────────────────────────────┼──────────────┘
              │                                  │
              ▼                                  ▼
┌───────────────────────────────────────────────────────────────┐
│                    COUCHE DONNÉES                              │
│                                                                │
│  ┌──────────────┐  ┌────────┐  ┌───────────────┐             │
│  │ PostgreSQL   │  │ Redis  │  │ Elasticsearch │             │
│  │              │  │        │  │  (optionnel)  │             │
│  │ • 91 tables  │  │ • Cache│  │               │             │
│  │ • 144 migr.  │  │ • Sess.│  │ • Full-text   │             │
│  │ • ACID       │  │ • Rate │  │ • Autocomplete│             │
│  │              │  │ • CSRF │  │ • Facettes    │             │
│  └──────────────┘  └────────┘  └───────────────┘             │
│                                                                │
│  ┌──────────────┐  ┌────────────────┐  ┌───────────────────┐ │
│  │ RabbitMQ     │  │ MinIO / S3     │  │ Nginx-RTMP       │ │
│  │              │  │                │  │                   │ │
│  │ • Jobs async │  │ • Fichiers     │  │ • Ingest RTMP     │ │
│  │ • Events     │  │   audio        │  │ • Output HLS      │ │
│  │ • Notif.     │  │ • Images       │  │ • Live streams    │ │
│  │              │  │ • Vidéos cours │  │                   │ │
│  └──────────────┘  └────────────────┘  └───────────────────┘ │
│                                                                │
│  ┌──────────────┐  ┌────────────────┐                         │
│  │ Prometheus   │  │ ClamAV         │                         │
│  │ + Grafana    │  │                │                         │
│  │              │  │ • Antivirus    │                         │
│  │ • Métriques  │  │ • Scan uploads │                         │
│  │ • Alerting   │  │                │                         │
│  └──────────────┘  └────────────────┘                         │
└───────────────────────────────────────────────────────────────┘
```

### 5.2 Architecture hexagonale (Backend Go)

Le backend suit une architecture hexagonale stricte avec séparation claire des responsabilités :

```
internal/
├── models/          # Entités du domaine (structs Go)
│                    # Aucune dépendance externe
│
├── repositories/    # Interfaces d'accès aux données + implémentations PostgreSQL
│                    # Seule couche qui parle à la base de données
│
├── services/        # Logique métier pure
│                    # Accepte context.Context comme 1er paramètre
│                    # Dépend des interfaces repository, jamais des implémentations
│
├── handlers/        # Contrôleurs HTTP (framework Gin)
│                    # Validation des entrées, appel des services, formatage des réponses
│
├── middleware/       # Middlewares transversaux
│                    # Auth, CORS, rate limiting, logging, CSRF, audit
│
└── api/             # Déclaration des routes
                     # Associe URLs → handlers + middlewares
```

### 5.3 Flux de données

```
Client HTTP Request
    │
    ▼
[Middleware Chain]
    │ CORS → Rate Limit → Auth → CSRF → Audit → Cache Headers
    │
    ▼
[Handler]
    │ Parse request → Validate input → Call service
    │
    ▼
[Service]
    │ Business logic → Call repository → Return result
    │
    ▼
[Repository]
    │ SQL query → Map to model → Return
    │
    ▼
[Handler]
    │ Format response → Set headers → Return JSON
    │
    ▼
Client HTTP Response
```

---

## 6. Stack technologique

### 6.1 Technologies principales

| Composant | Technologie | Version | Justification |
|-----------|-------------|---------|---------------|
| **Backend API** | Go + Gin | 1.24 | Performance, typage fort, concurrence native |
| **Stream Server** | Rust + Axum + Tokio | 1.35 | Performance maximale, safety mémoire, zero-cost abstractions |
| **Frontend** | React + TypeScript + Vite | 18 / 5+ / 7 | Écosystème mature, typage strict, build rapide |
| **Base de données** | PostgreSQL | 16 | Fiabilité, ACID, full-text search natif |
| **Cache** | Redis | 7 | Rapidité, pub/sub, structures de données riches |
| **Recherche** | Elasticsearch | 8 | Full-text search performant avec tolérance phonétique |
| **Message Queue** | RabbitMQ | 3 | Fiabilité, routing flexible, acknowledgment |
| **Object Storage** | MinIO (dev) / S3 (prod) | — | Standard S3, coût maîtrisé |
| **Paiements** | Hyperswitch + Stripe Connect | — | Multi-PSP, indépendance fournisseur |
| **Live Streaming** | Nginx-RTMP + HLS | — | Standard industrie, compatible OBS |
| **Antivirus** | ClamAV | 1.4 | Scan des uploads, protection contre les malwares |
| **CI/CD** | GitHub Actions | — | Intégration native GitHub, parallelisation |
| **Conteneurs** | Docker + docker-compose | — | Reproductibilité, isolation |
| **Monitoring** | Prometheus + Grafana | — | Métriques temps réel, alerting |

### 6.2 Dépendances Frontend clés

| Bibliothèque | Rôle |
|--------------|------|
| `@tanstack/react-query` | Gestion de l'état serveur (cache, revalidation, déduplication) |
| `zustand` | État client léger et persistant (auth, player, UI) |
| `axios` | Client HTTP avec intercepteurs (refresh token, CSRF, retry) |
| `react-router-dom` | Routing avec lazy loading |
| `i18next` | Internationalisation (3 langues) |
| `react-hook-form` + `zod` | Formulaires typés avec validation runtime |
| `hls.js` | Lecture HLS dans le navigateur |
| `framer-motion` | Animations fluides |
| `recharts` | Graphiques pour les analytics |
| `@radix-ui` | Primitives UI accessibles |
| `@dnd-kit` | Drag-and-drop (playlists) |
| `lucide-react` | Icônes |

### 6.3 Dépendances Stream Server clés (Rust)

| Crate | Rôle |
|-------|------|
| `axum` + `tokio` | Framework web async haute performance |
| `symphonia` | Décodage audio multi-format |
| `hound` | Lecture/écriture WAV |
| `minimp3` | Décodage MP3 |
| `rustfft` + `dasp` | Traitement du signal audio |
| `sqlx` | Accès DB type-safe async |
| `deadpool-redis` | Pool de connexions Redis |
| `lapin` | Client RabbitMQ |
| `metrics` + `tracing` | Observabilité (Prometheus + logs structurés) |

---

## 7. Backend API (Go)

### 7.1 Surface API

Le backend expose **120+ endpoints REST** organisés en **26 groupes de routes**, tous préfixés par `/api/v1/` :

| Groupe | Endpoints | Description |
|--------|-----------|-------------|
| **Auth** | 20+ | Inscription, connexion, 2FA, OAuth, WebAuthn, sessions |
| **Tracks** | 40+ | Upload, métadonnées, likes, reposts, commentaires, stems, HLS |
| **Users** | 25+ | Profils, follow, block, avatar, export RGPD, présence |
| **Playlists** | 20+ | CRUD, collaboration, partage, analytics, export multi-format |
| **Search** | 2 | Recherche unifiée + autocomplete |
| **Marketplace** | 30+ | Produits, commandes, licences, reviews, wishlist, panier |
| **Subscriptions** | 8 | Plans, abonnement, facturation, annulation |
| **Analytics** | 20+ | Statistiques créateur, heatmaps, comparaisons, alertes |
| **Social** | 15+ | Feed, posts, groupes, likes, commentaires |
| **Distribution** | 6 | Soumission aux plateformes, suivi, royalties |
| **Education** | 20+ | Cours, leçons, inscriptions, certificats |
| **Live** | 8 | Streams live, clé RTMP, callbacks |
| **Chat** | 12 | Conversations, membres, messagerie temps réel |
| **Notifications** | 7 | In-app, préférences, push web |
| **Cloud** | 15+ | Fichiers, dossiers, versioning, partage |
| **Modération** | 10+ | Reports, spam, fingerprints, strikes, appels |
| **Admin** | 15+ | Utilisateurs, contenu, paiements, feature flags |
| **Developer** | 3 | Clés API, gestion |
| **Discover** | 6 | Genres, tags, playlists éditoriales |
| **Feed** | 1 | Feed chronologique |
| **Co-listening** | 3 | Sessions synchronisées |
| **Queue** | 8 | File d'attente de lecture |
| **Gear** | 12 | Inventaire d'équipement |
| **Core** | 15+ | Health, metrics, uploads, audit, CSRF |

### 7.2 Formats de réponse

**Réponse standard :**
```json
{
  "data": { ... },
  "message": "Track created successfully"
}
```

**Pagination :**
```json
{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "total_pages": 8
  }
}
```

**Erreur :**
```json
{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Track with ID 123 not found",
    "context": { "track_id": "123" }
  }
}
```

### 7.3 Entités de base de données

**91 entités** réparties en domaines :

| Domaine | Entités principales |
|---------|-------------------|
| **Utilisateurs** | User, Session, RefreshToken, MFAConfig, WebAuthnCredential, FederatedIdentity, UserSettings, UserPresence |
| **Audio** | Track, TrackVersion, TrackStem, TrackPlay, TrackLike, TrackRepost, TrackComment, HLSStream, WaveformData |
| **Playlists** | Playlist, PlaylistTrack, PlaylistCollaborator, PlaylistFollow, PlaylistShareLink |
| **Marketplace** | Product, Order, OrderItem, License, Review, SellerStripeAccount, SellerTransfer, Royalty |
| **Abonnements** | SubscriptionPlan, Subscription |
| **Social** | Room, ChatMessage, MessageReaction, Post, Group |
| **Analytics** | PlaybackAnalytics, DailyTrackStats, CreatorAnalytics, AdvancedAnalytics |
| **Modération** | Report, Strike, Appeal, ModerationAnalytics |
| **Éducation** | Course, Lesson, CourseEnrollment, Certificate |
| **Cloud** | UserFile, UserFolder, CloudFileVersion, CloudFileShare, StorageQuota |
| **Administration** | AuditLog, FeatureFlag, Announcement, APIKey |
| **Distribution** | DistributionPlatform, Distribution |
| **Live** | LiveStream |
| **Équipement** | Gear, GearImage, GearDocument, GearRepair |

---

## 8. Serveur de streaming (Rust)

### 8.1 Rôle

Le serveur de streaming est un composant haute performance dédié à :
- La **diffusion audio** en streaming adaptatif (HLS)
- Le **transcodage** des fichiers audio (upload → multiples qualités)
- La **synchronisation temps réel** pour la co-écoute
- Le **cache** intelligent des segments audio

### 8.2 Codecs supportés

| Codec | Bitrate | Latence | Usage |
|-------|---------|---------|-------|
| **Opus** | 6-512 kbps | 2.5ms | Live, co-écoute (ultra-basse latence) |
| **AAC** | 32-320 kbps | 20ms | iOS/Safari, compatibilité universelle |
| **MP3** | 32-320 kbps | 26ms | Compatibilité legacy |
| **FLAC** | 700 kbps-1.4 Mbps | 40ms | Qualité lossless (premium) |

### 8.3 Pipeline de transcodage

```
Upload audio (WAV/MP3/FLAC/...)
    │
    ▼
[Décodage] → PCM samples (via Symphonia)
    │
    ▼
[Traitement] → Normalisation, effets, EQ
    │
    ▼
[Encodage multi-qualité]
    ├── Opus 128kbps (standard)
    ├── AAC 256kbps (haute qualité)
    ├── MP3 320kbps (compatibilité)
    └── FLAC (lossless, premium)
    │
    ▼
[Segmentation HLS] → Segments .ts + playlist .m3u8
    │
    ▼
[Cache LRU] → Segments fréquemment demandés en mémoire
```

### 8.4 Architecture de concurrence

- **Runtime async** : Tokio (multi-thread, work-stealing)
- **Pool de workers** : 1 worker par core CPU pour le transcodage
- **Connexions concurrentes** : DashMap (lock-free concurrent HashMap)
- **WebSocket** : Gestion simultanée de milliers de connexions
- **Rate limiting** : Token bucket (governor crate)

---

## 9. Frontend (React/TypeScript)

### 9.1 Design System SUMI

Le frontend utilise **SUMI v2.0**, un design system propriétaire conçu pour l'éthique et l'accessibilité :

**Palette de couleurs :**
- **Fonds** : Void (#0c0c0f) → Raised (#1a1a1f) → Overlay (#222228)
- **Texte** : Primary (#f0ede8) → Secondary (#a8a4a0) → Tertiary (#706c68)
- **Accent** : Bleu (#7c9dd6) — Actions principales
- **Vermillion** : Rouge (#d4634a) — Erreurs, actions destructives
- **Sage** : Vert (#7a9e6c) — Succès, confirmations
- **Gold** : Jaune (#c9a84c) — Avertissements

**Typographie :**
- Titres : Space Grotesk
- Corps : Inter
- Code : JetBrains Mono
- Éditorial : Noto Serif JP

**Accessibilité :**
- Conforme WCAG AA
- Labels ARIA sur tous les composants interactifs
- Navigation clavier complète (Tab, Enter, Escape)
- Focus visible sur tous les éléments interactifs

### 9.2 Modules fonctionnels

Le frontend est organisé en **37 modules fonctionnels** indépendants dans `/src/features/` :

```
features/
├── auth/          # Login, register, 2FA, sessions, email verification
├── player/        # Lecteur audio global, contrôles, queue, waveform
├── tracks/        # Pages de tracks, cards, commentaires, upload
├── playlists/     # Gestion playlists, collaboration, export
├── search/        # Recherche unifiée, autocomplete
├── dashboard/     # Page d'accueil, stats, activité récente
├── discover/      # Navigation par genres/tags/moods
├── library/       # Bibliothèque personnelle
├── notifications/ # Centre de notifications
├── chat/          # Messagerie temps réel
├── profile/       # Profil utilisateur
├── settings/      # Préférences, thème, langue, confidentialité
├── marketplace/   # Vente/achat de beats et samples
├── seller/        # Dashboard vendeur
├── checkout/      # Flux de paiement
├── analytics/     # Analytics créateur
├── distribution/  # Distribution externe
├── education/     # Cours et formations
├── live/          # Live streaming
├── social/        # Follow, like, feed
├── cloud/         # Stockage cloud
├── admin/         # Administration plateforme
├── developer/     # Dashboard développeur, webhooks
├── subscription/  # Gestion abonnement premium
├── ...            # Et plus encore
```

### 9.3 Gestion d'état

| Couche | Technologie | Usage |
|--------|-------------|-------|
| **État serveur** | React Query (TanStack) | Tracks, playlists, profils, notifications — cache, revalidation, déduplication |
| **État client** | Zustand (persist) | Auth, player, UI (sidebar, thème, langue) |
| **État formulaires** | React Hook Form + Zod | Validation runtime typée |
| **Temps réel** | WebSocket + Broadcast Channel | Synchronisation cross-tabs, chat, notifications |

### 9.4 Lecteur audio

Le lecteur audio est un composant central de l'application :

- **HLS adaptatif** via hls.js (qualité auto-ajustée)
- **Contrôles** : play/pause, seek, volume, mute, next/previous
- **Fonctionnalités avancées** : vitesse de lecture (0.5x-2x), crossfade, normalisation audio
- **Media Session API** : Contrôles lockscreen (mobile)
- **WakeLock** : Empêche la mise en veille pendant la lecture
- **Picture-in-Picture** : Mini-lecteur flottant
- **Queue partagée** : Sessions de queue synchronisées entre utilisateurs
- **Raccourcis clavier** : Espace (play), flèches (seek), V (volume), > (suivant)

---

## 10. Infrastructure et déploiement

### 10.1 Services Docker

| Service | Image | Mémoire | Port | Rôle |
|---------|-------|---------|------|------|
| **PostgreSQL** | postgres:16 | 256 MB | 5432 | Base de données principale |
| **Redis** | redis:7-alpine | 64 MB | 6379 | Cache, sessions, rate limit |
| **RabbitMQ** | rabbitmq:3-management | 512 MB | 5672/15672 | Message queue + dashboard |
| **ClamAV** | clamav/clamav:1.4 | 512 MB | 3310 | Antivirus scan des uploads |
| **MinIO** | minio/minio | 256 MB | 9000/9001 | Object storage (dev) |
| **Nginx-RTMP** | custom | 128 MB | 1935/8088 | Ingest RTMP + HLS live |
| **Backend API** | go:1.24 | variable | 8080 | API REST |
| **Stream Server** | rust:latest | variable | 18082 | Streaming audio |

### 10.2 Environnements

| Environnement | Description | Commande |
|---------------|-------------|----------|
| **Local** | Tous les services via Docker | `make dev` |
| **Dev** | Backend Docker + frontend Vite local | `make dev-backend-api` |
| **Staging** | Validation pré-production (Lighthouse, k6, RGPD) | CI/CD auto |
| **Production** | SSL, limites ressources, health checks | `docker-compose.prod.yml` |

### 10.3 Health Checks

| Service | Endpoint | Méthode |
|---------|----------|---------|
| Backend API | `GET /api/v1/health` | HTTP 200 |
| Backend API (deep) | `GET /api/v1/health/deep` | Vérifie toute l'infra |
| Stream Server | `GET /health` | HTTP 200 |
| PostgreSQL | `pg_isready` | CLI |
| Redis | `redis-cli ping` | CLI |
| RabbitMQ | `rabbitmq-diagnostics ping` | CLI |

### 10.4 Monitoring

- **Prometheus** : Collecte des métriques depuis `/metrics` (protégé par token bearer)
- **Grafana** : Dashboards de visualisation et alerting
- **Sentry** : Tracking d'erreurs (frontend et backend)
- **Logs structurés JSON** : `level`, `time`, `msg`, `request_id`, `user_id`

---

## 11. Sécurité

### 11.1 Authentification multi-couches

| Méthode | Description |
|---------|-------------|
| **JWT RS256** | Tokens signés avec clé RSA (rotation de clés supportée) |
| **2FA TOTP** | Authentification à deux facteurs via app (Google Authenticator, Authy) |
| **WebAuthn/Passkeys** | Authentification sans mot de passe (FIDO2) |
| **OAuth** | Connexion via Google, GitHub, Discord, Spotify |
| **Codes de récupération** | Codes backup pour la 2FA |

### 11.2 Protections actives

| Protection | Détail |
|------------|--------|
| **Rate limiting** | Par IP (global), par utilisateur, par endpoint, par clé API |
| **CSRF** | Tokens double-submit cookie, validation sur les requêtes mutatives |
| **CORS** | Whitelist d'origines en production |
| **CSP** | Content Security Policy stricte |
| **Account lockout** | 5 tentatives → verrouillage 30 min |
| **Password history** | Empêche la réutilisation des derniers mots de passe |
| **Token blacklist** | Révocation immédiate des JWT via Redis |
| **ClamAV** | Scan antivirus de tous les fichiers uploadés |
| **Audit logging** | Journalisation de toutes les actions sensibles |
| **Signed URLs** | URLs S3 signées avec expiration pour les fichiers privés |

### 11.3 Audit de sécurité

Le projet a subi un **pentest complet** (v0.12.6) :
- **36 findings identifiés** sur 36 fichiers
- **36/36 findings remédiés**
- Conformité **ASVS Level 2** (OWASP Application Security Verification Standard)
- Suppression de modules fantômes et patterns non-éthiques

---

## 12. Modèle économique

### 12.1 Sources de revenus

```
┌─────────────────────────────────────────────────────────────┐
│                   SOURCES DE REVENUS                         │
│                                                              │
│  ┌─────────────────┐  ┌──────────────────┐                  │
│  │  MARKETPLACE     │  │  ABONNEMENTS     │                  │
│  │                  │  │                   │                  │
│  │  Commission 15%  │  │  Creator $5.99/mo │                  │
│  │  sur chaque      │  │  Premium $9.99/mo │                  │
│  │  vente            │  │                   │                  │
│  └─────────────────┘  └──────────────────┘                  │
│                                                              │
│  ┌─────────────────┐  ┌──────────────────┐                  │
│  │  DISTRIBUTION    │  │  FORMATIONS       │                  │
│  │                  │  │                   │                  │
│  │  Commission sur  │  │  Commission sur   │                  │
│  │  les royalties   │  │  les ventes de    │                  │
│  │  externes        │  │  cours            │                  │
│  └─────────────────┘  └──────────────────┘                  │
└─────────────────────────────────────────────────────────────┘
```

### 12.2 Plans d'abonnement

| Plan | Prix | Fonctionnalités |
|------|------|----------------|
| **Free** | $0 | Écoute en streaming, playlists, recherche, feed, chat |
| **Creator** | $5.99/mois | Upload illimité, analytics avancés, marketplace, distribution |
| **Premium** | $9.99/mois | Qualité FLAC, téléchargements, pas de pub, remise 10% marketplace |

- Essai gratuit de 14 jours pour Creator et Premium
- Facturation via Stripe (mensuelle ou annuelle)
- Annulation en un clic, sans friction

### 12.3 Marketplace

| Aspect | Détail |
|--------|--------|
| **Produits** | Beats, samples, kits, presets |
| **Licences** | Basic, Premium, Exclusive (prix croissant) |
| **Commission** | 15% (vs 30% standard industrie) |
| **Paiements vendeurs** | Hebdomadaires automatiques (seuil $50) ou manuels (seuil $100) |
| **Processeur** | Hyperswitch (Stripe + PayPal) |
| **KYC** | Vérification d'identité obligatoire pour les vendeurs (Stripe Identity) |

### 12.4 Comparaison avec la concurrence

| Aspect | Veza | Spotify | SoundCloud | Bandcamp |
|--------|------|---------|------------|----------|
| Commission marketplace | **15%** | N/A | 45% | 15% |
| Fréquence paiements | **Hebdo** | Mensuel | Mensuel | Instantané |
| Métriques publiques | **Non** | Oui | Oui | Partiel |
| Dark patterns | **Aucun** | Oui | Oui | Limité |
| Algorithme comportemental | **Non** | Oui | Oui | Non |
| Export données | **Complet** | Limité | Limité | Limité |
| Open API | **Oui** | Oui | Oui | Non |

---

## 13. Parcours utilisateur

### 13.1 Auditeur

```
1. Inscription
   ├── Email + mot de passe
   ├── Vérification email
   └── (optionnel) Activation 2FA

2. Découverte
   ├── Explorer par genres / tags / moods
   ├── Recherche unifiée
   └── Feed chronologique des artistes suivis

3. Écoute
   ├── Clic sur un track → streaming HLS
   ├── Player bar : artwork, titre, artiste, progress, contrôles
   ├── Queue : ajouter, réordonner, sessions partagées
   └── Raccourcis clavier pour toutes les actions

4. Organisation
   ├── Créer des playlists
   ├── Inviter des collaborateurs
   ├── Partager des playlists publiques
   └── Exporter (JSON, CSV, M3U)

5. Social
   ├── Suivre des artistes
   ├── Rejoindre des groupes
   ├── Commenter des tracks
   └── Chat avec d'autres utilisateurs

6. Marketplace
   ├── Acheter des beats / samples / kits
   ├── Choisir une licence (Basic / Premium / Exclusive)
   └── Télécharger les produits achetés
```

### 13.2 Créateur

```
1. Passer au plan Creator ($5.99/mois)

2. Upload
   ├── Upload de tracks (drag-and-drop ou parcourir)
   ├── Métadonnées : titre, genre, tags, description, lyrics
   ├── Transcodage automatique multi-qualité
   └── Upload de stems pour remix

3. Analytics (privés)
   ├── Nombre d'écoutes, sources de trafic
   ├── Données géographiques (anonymisées)
   ├── Heatmaps d'écoute
   ├── Comparaison de périodes
   └── Alertes métriques personnalisées

4. Marketplace (vente)
   ├── Créer des produits (beats, samples, kits)
   ├── Définir les prix par licence
   ├── Suivre les ventes et revenus
   └── Recevoir les paiements (hebdomadaires)

5. Distribution
   ├── Soumettre sur Spotify, Apple Music, Deezer
   ├── Suivre le statut de distribution
   └── Voir les royalties externes

6. Live Streaming
   ├── Configurer OBS avec la clé RTMP
   ├── Lancer un live
   └── Interagir avec le chat en direct

7. Formation
   ├── Créer des cours avec modules vidéo
   ├── Suivre les inscriptions
   └── Délivrer des certificats
```

---

## 14. Conformité et vie privée

### 14.1 RGPD (Règlement Général sur la Protection des Données)

| Droit | Implémentation |
|-------|----------------|
| **Droit d'accès** | `GET /users/me/export` — Export JSON de toutes les données |
| **Droit à la portabilité** | `POST /users/me/export` — Export ZIP asynchrone complet |
| **Droit à l'effacement** | `DELETE /users/me` — Suppression du compte avec période de grâce de 30 jours |
| **Droit d'opposition** | Préférences de notifications granulaires, opt-out marketing |
| **Minimisation des données** | Seules les données nécessaires sont collectées |

### 14.2 CCPA (California Consumer Privacy Act)

- Endpoint dédié : `POST /users/me/privacy/opt-out`
- Opt-out du partage/vente de données personnelles (Veza ne vend pas de données, mais le mécanisme est prévu)

### 14.3 Politique de confidentialité des données

- **Géolocalisation** : Anonymisée au niveau pays (pas de ville ni d'IP stockée)
- **Analytics** : Agrégées à minimum 10 utilisateurs (pas de profiling individuel)
- **Données comportementales** : NON utilisées pour le ranking ou les recommandations
- **Cookies** : Uniquement fonctionnels (auth, CSRF) — aucun cookie de tracking tiers
- **Chiffrement** : Tokens OAuth chiffrés AES-256-GCM, passwords hashés bcrypt

---

## 15. Performance et scalabilité

### 15.1 Objectifs de performance

| Métrique | Cible |
|----------|-------|
| Temps de réponse API (p95) | < 100ms |
| Lighthouse Performance | >= 85 |
| Lighthouse Accessibility | >= 90 |
| Time to First Byte (TTFB) | < 200ms |
| First Contentful Paint (FCP) | < 1.5s |
| Largest Contentful Paint (LCP) | < 2.5s |
| Utilisateurs concurrents (charge) | 1000+ (validé par k6) |

### 15.2 Stratégies de performance

| Stratégie | Détail |
|-----------|--------|
| **Cache Redis** | Résultats fréquents cachés avec invalidation intelligente |
| **CDN** | Assets statiques servis via CDN avec cache longue durée |
| **Code splitting** | Routes lazy-loaded, vendor chunks séparés |
| **HLS adaptatif** | Qualité audio ajustée automatiquement selon la bande passante |
| **Cache LRU audio** | Segments audio fréquents en mémoire sur le stream server |
| **Index DB** | Index PostgreSQL optimisés (144 migrations incluant les index de performance) |
| **Pool de connexions** | Connexions DB/Redis poolées et réutilisées |
| **Compression** | gzip/brotli/zstd sur les réponses HTTP |

### 15.3 Scalabilité horizontale

```
                    Load Balancer
                    ┌───────────┐
                    │  Nginx /  │
                    │  HAProxy  │
                    └─────┬─────┘
              ┌───────────┼───────────┐
              ▼           ▼           ▼
         ┌─────────┐ ┌─────────┐ ┌─────────┐
         │ API #1  │ │ API #2  │ │ API #3  │    ← Stateless, scale horizontal
         └────┬────┘ └────┬────┘ └────┬────┘
              │           │           │
              ▼           ▼           ▼
         ┌─────────────────────────────────┐
         │       PostgreSQL (primary)       │
         │     + Read Replicas (optionnel) │
         └─────────────────────────────────┘
              │
         ┌────┴────┐
         │  Redis  │  ← Sessions, cache, rate limit (distribué)
         └─────────┘
```

---

## 16. Historique des versions

### Phase P3.5 — Consolidation & Sécurité (v0.9.x)

| Version | Nom | Contenu principal |
|---------|-----|-------------------|
| v0.9.1 | Migration JWT RS256 | Rotation de clés, migration HS256 → RS256 |
| v0.9.2 | Sécurité Infrastructure | Rate limiting, CSP headers, protection /metrics |
| v0.9.3 | Standardisation Toolchain | Node 20, Rust stable, Makefile unifié |
| v0.9.4 | Quality Gates CI/CD | Coverage enforcement, linting, build validation |
| v0.9.5 | Nettoyage Code | Suppression AI/ML, blockchain, gamification |
| v0.9.6-9.7 | Chat complet | Réactions, mentions, fichiers, threads, groupes |
| v0.9.8-9.9 | Dette technique | Error handling, context propagation, goroutines |

### Phase P4R — Social & Live (v0.10.x)

| Version | Nom | Contenu principal |
|---------|-----|-------------------|
| v0.10.0 | Système Follow | Follow/unfollow, feed chronologique |
| v0.10.1 | Découverte Éthique | Tags, genres, pas de ranking comportemental |
| v0.10.2 | Recherche Elasticsearch | Full-text search, tolérance phonétique |
| v0.10.3 | Interactions Sociales | Commentaires, likes (privés), reposts, notifications |
| v0.10.4 | Playlists Collaboratives | Collaboration, import/export, playlists éditoriales |
| v0.10.5 | Notifications | In-app, email digest, préférences, quiet hours |
| v0.10.6 | Live Streaming | RTMP ingest, HLS distribution, chat live |
| v0.10.7 | Collaboration Temps Réel | Co-écoute, stems, rooms collaboratives |
| v0.10.8 | Portabilité Données | Export ZIP, suppression compte, grâce 30 jours |

### Phase P5R — Analytics & Modération (v0.11.x)

| Version | Nom | Contenu principal |
|---------|-----|-------------------|
| v0.11.0 | Analytics Créateur | Écoutes privées, géo anonymisée, sources |
| v0.11.1 | Analytics Avancés | Heatmaps, comparaison périodes, alertes |
| v0.11.2 | Modération | Reports, spam déterministe, fingerprinting ACRCloud |
| v0.11.3 | Admin Plateforme | Dashboard admin, gestion users/content/paiements |

### Phase P6R — Premium & Infrastructure (v0.12.x)

| Version | Nom | Contenu principal |
|---------|-----|-------------------|
| v0.12.0 | Marketplace | Produits, licences, checkout Hyperswitch |
| v0.12.1 | Abonnements | Free/Creator/Premium, Stripe, trial 14j |
| v0.12.2 | Distribution | Spotify/Apple/Deezer via API partenaire |
| v0.12.3 | Formation | Cours vidéo HLS, modules, certificats |
| v0.12.4 | Performance | CDN, Redis cache, query optimization, k6 |
| v0.12.5 | PWA | Service Worker offline, manifest, Media Session |
| v0.12.6 | Pentest | 36 findings fixés, ASVS Level 2 |

### Phase P7 — Conformité & Polish (v0.13.x)

| Version | Nom | Contenu principal |
|---------|-----|-------------------|
| v0.12.7 | i18n | FR/EN/ES, 532+ clés par langue |
| v0.12.8 | API Publique | OpenAPI/Swagger, clés API avec scopes |
| v0.12.9 | Tests Éthiques | Bias checks, artistes émergents visibles |
| v0.13.0 | Features Complètes | SMS 2FA, CAPTCHA Turnstile, password history |
| v0.13.1 | Audio Avancé | Gapless, crossfade, normalisation |
| v0.13.2 | Design System | SUMI consolidé, design tokens, Storybook |
| v0.13.3 | Sécurité Polish | WebAuthn/Passkeys, IP geolocation |
| v0.13.4 | Audio Polish | PiP, Chromecast, visualizers |
| v0.13.5 | Marketplace Polish | KYC Stripe Identity, E2E testing |

### Phase Validation (v0.14.x → v1.0.0)

| Version | Nom | Contenu principal |
|---------|-----|-------------------|
| v0.14.0 | Staging Validation | Lighthouse, k6 load test, flux RGPD |
| v1.0.0-rc1 | Release Candidate | GO/NO-GO checklist, dark pattern audit, privacy policy |
| **v1.0.0** | **Release Stable** | **Prêt pour le lancement public** |

---

## 17. Roadmap

### Statut actuel

- **39 versions implémentées** (v0.9.1 → v1.0.0-rc1)
- **v1.0.0-rc1 tagué et testé** — en attente de validation business finale
- Le code est **production-ready**

### Prochaines étapes

1. **v1.0.0 — Lancement public**
   - Validation finale du GO/NO-GO checklist
   - Déploiement en production
   - Monitoring de stabilité 48h sur staging

2. **Post-lancement (v1.x)**
   - Retours utilisateurs et itérations
   - Expansion géographique (nouvelles langues)
   - Partenariats avec des labels indépendants
   - Application mobile native (si demande validée)

---

## 18. Équipe et processus de développement

### 18.1 Organisation du code

Le projet est un **monorepo** organisé comme suit :

```
veza/
├── apps/web/                    # Frontend React/TypeScript
├── veza-backend-api/            # Backend Go (API principale)
├── veza-stream-server/          # Serveur de streaming Rust
├── veza-common/                 # Utilitaires partagés
├── ORIGIN/                      # Spécifications (read-only)
├── docs/                        # Documentation technique
├── make/                        # Modules Makefile
├── docker-compose.yml           # Orchestration Docker
└── .github/workflows/           # CI/CD GitHub Actions
```

### 18.2 Processus de développement

| Étape | Détail |
|-------|--------|
| **Spécification** | Fichiers ORIGIN/ (read-only, source de vérité) |
| **Planification** | Roadmap versionnée dans VEZA_VERSIONS_ROADMAP.md |
| **Branching** | Feature branches (`feat/v{VERSION}-{nom}`) |
| **Développement** | Architecture hexagonale, TDD, code review |
| **Tests** | Unitaires (Go, TS, Rust) + E2E (Playwright) + Load (k6) |
| **CI/CD** | GitHub Actions : lint, test, build, coverage |
| **Déploiement** | Docker-compose, staging validation, production |

### 18.3 Qualité du code

| Métrique | Valeur |
|----------|--------|
| **Backend Go** | ~160,000 lignes, TypeScript strict |
| **Frontend** | ~37,000 lignes, TypeScript strict |
| **Migrations SQL** | 144 fichiers |
| **Coverage Go** | >= 70% (enforced CI) |
| **Coverage Rust** | >= 50% (enforced CI) |
| **Linting** | golangci-lint (Go), ESLint (TS), cargo clippy (Rust) |

### 18.4 Commandes de développement

```bash
make dev                # Démarre l'environnement complet
make test               # Lance tous les tests
make lint               # Linting strict
make build              # Build complet
make migrate-up         # Applique les migrations
make doctor             # Vérifie les dépendances
make infra-up-dev       # Lance l'infrastructure (Postgres, Redis, etc.)
```

---

## 19. Glossaire

| Terme | Définition |
|-------|------------|
| **ASVS** | Application Security Verification Standard — standard OWASP pour la vérification de sécurité des applications |
| **Dark pattern** | Technique de design UX qui manipule l'utilisateur pour qu'il agisse contre son intérêt |
| **Feed chronologique** | Flux d'actualités ordonné par date de publication (sans algorithme de ranking) |
| **HLS** | HTTP Live Streaming — protocole de streaming adaptatif développé par Apple |
| **Hyperswitch** | Routeur de paiement open-source permettant de connecter plusieurs processeurs (Stripe, PayPal) |
| **KYC** | Know Your Customer — vérification d'identité obligatoire pour les vendeurs |
| **Marketplace** | Place de marché intégrée pour la vente de beats, samples, kits et cours |
| **ORIGIN** | Dossier de spécifications read-only qui définit les règles immuables du projet |
| **Pentest** | Test de pénétration — audit de sécurité simulant des attaques |
| **PWA** | Progressive Web App — application web installable avec fonctionnalités offline |
| **RGPD** | Règlement Général sur la Protection des Données (règlement européen) |
| **RTMP** | Real-Time Messaging Protocol — protocole pour le live streaming (ingest depuis OBS) |
| **SUMI** | Design system propriétaire de Veza (couleurs, typographie, composants) |
| **Stem** | Piste audio isolée (voix, batterie, basse, etc.) permettant le remixage |
| **Stripe Connect** | Plateforme de paiement pour les marketplaces (paiements aux vendeurs) |

---

## Chiffres clés

| Métrique | Valeur |
|----------|--------|
| Lignes de code total | ~200,000+ |
| Endpoints API | 120+ |
| Entités base de données | 91 |
| Services backend | 130+ |
| Middlewares | 20+ |
| Modules frontend | 37 |
| Migrations SQL | 144 |
| Versions implémentées | 39 |
| Langues supportées | 3 (FR, EN, ES) |
| Findings pentest remédiés | 36/36 |
| Codecs audio supportés | 4 (Opus, AAC, MP3, FLAC) |

---

*Document généré le 2026-03-16. Pour toute question technique, consultez le code source et les fichiers ORIGIN/ du repository.*