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
2. Pourquoi Veza existe
3. Principes fondateurs
4. Fonctionnalités de la plateforme
5. Architecture technique
6. Stack technologique
7. Backend API (Go)
8. Serveur de streaming (Rust)
9. Frontend (React/TypeScript)
10. Infrastructure et déploiement
11. Sécurité
12. Modèle économique
13. Parcours utilisateur
14. Conformité et vie privée
15. Performance et scalabilité
16. Historique des versions
17. Roadmap
18. Équipe et processus de développement
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 :

{
  "data": { ... },
  "message": "Track created successfully"
}

Pagination :

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

Erreur :

{
  "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

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.