From d5bfe4a5580d18bfe6cfa84c31abe2bdc2058218 Mon Sep 17 00:00:00 2001 From: senke Date: Wed, 18 Mar 2026 11:36:36 +0100 Subject: [PATCH] docs: add project documentation, logging config, status script - docs/VEZA_PROJECT_DOCUMENTATION.md - config/logging.toml - status.sh utility script Co-Authored-By: Claude Opus 4.6 (1M context) --- config/logging.toml | 150 ++++ docs/VEZA_PROJECT_DOCUMENTATION.md | 1059 ++++++++++++++++++++++++++++ status.sh | 324 +++++++++ 3 files changed, 1533 insertions(+) create mode 100644 config/logging.toml create mode 100644 docs/VEZA_PROJECT_DOCUMENTATION.md create mode 100755 status.sh diff --git a/config/logging.toml b/config/logging.toml new file mode 100644 index 000000000..c952fa42f --- /dev/null +++ b/config/logging.toml @@ -0,0 +1,150 @@ +# ═══════════════════════════════════════════════════════════════════════════════ +# VEZA — Centralized Logging Configuration +# ═══════════════════════════════════════════════════════════════════════════════ +# +# Single source of truth for ALL service logging. +# Read by: Go backend, Rust stream server, Frontend (via env vars) +# +# Override any value via environment variable: +# LOG_LEVEL=DEBUG LOG_DIR=/tmp/veza-logs make dev +# +# ═══════════════════════════════════════════════════════════════════════════════ + +# ── Global defaults ────────────────────────────────────────────────────────── + +[global] +# Log level: TRACE, DEBUG, INFO, WARN, ERROR (case-insensitive, Go & Rust compatible) +level = "INFO" + +# Base directory for all log files +# Created automatically with 0755 permissions if it doesn't exist. +# Fallback: ./logs (if /var/log/veza is not writable) +dir = "/var/log/veza" + +# Format: "json" (production/staging) or "text" (development) +# Auto-detected from APP_ENV if not set: production/staging → json, else → text +format = "auto" + +# ── File rotation (lumberjack for Go, tracing-appender for Rust) ───────────── + +[rotation] +# Maximum size of a single log file before rotation (megabytes) +max_size_mb = 100 + +# Maximum number of rotated files to retain +max_backups = 10 + +# Maximum age of rotated files before deletion (days) +max_age_days = 30 + +# Compress rotated files with gzip +compress = true + +# Rust rotation strategy: "hourly" or "daily" +# Hourly if max_size_mb ≤ 100, daily otherwise +rust_rotation = "hourly" + +# Maximum rotated files for Rust (tracing-appender) +rust_max_files = 5 + +# ── Go Backend API ─────────────────────────────────────────────────────────── + +[backend] +# Module name — determines log file names: {module}.log, {module}-error.log +module = "backend-api" + +# Additional module loggers (each gets its own .log + -error.log pair) +# These log database queries, redis commands, rabbitmq events separately +modules = ["db", "rabbitmq"] + +# Slow request detection threshold (milliseconds) +# Requests slower than this are logged at WARN level +slow_request_threshold_ms = 1000 + +# Sampling (production only — prevents log spam under high load) +# Initial: first N messages per second are always logged +# Thereafter: 1 in N subsequent messages are logged +sampling_initial = 100 +sampling_thereafter = 100 + +# Async buffered writes +# Buffer size in KB — reduces syscalls by batching writes +buffer_size_kb = 256 + +# Flush interval in milliseconds — maximum delay before buffer is flushed +flush_interval_ms = 100 + +# ── Rust Stream Server ─────────────────────────────────────────────────────── + +[stream] +# Module name — determines log file prefix: {module}.YYYY-MM-DD-HH +module = "stream" + +# Include source file and line number in log entries +include_source = true + +# Include thread IDs in log entries +include_thread_ids = true + +# ── Frontend (React) ──────────────────────────────────────────────────────── + +[frontend] +# Frontend log level (VITE_LOG_LEVEL) +# Defaults: DEBUG in development, WARN in production +level = "auto" + +# Backend endpoint for forwarding frontend errors +# Uses navigator.sendBeacon() for non-blocking delivery +endpoint = "/api/v1/logs/frontend" + +# Enable Sentry error tracking (requires VITE_SENTRY_DSN env var) +sentry_enabled = false + +# ── Log Aggregation (optional — Loki/Grafana) ─────────────────────────────── + +[aggregation] +# Enable centralized log aggregation (Loki-compatible) +enabled = false + +# Aggregation endpoint URL +# endpoint = "http://loki:3100/loki/api/v1/push" + +# Batch size — number of log entries per HTTP push +batch_size = 100 + +# Flush interval (seconds) — maximum delay between pushes +flush_interval_s = 5 + +# HTTP timeout for push requests (seconds) +timeout_s = 10 + +# Static labels applied to all log entries +# labels = "app=veza,env=production" + +# ── File permissions ───────────────────────────────────────────────────────── + +[permissions] +# Directory permissions (octal) +dir_mode = "0755" + +# File permissions (octal) — Go files +file_mode = "0640" + +# ═══════════════════════════════════════════════════════════════════════════════ +# Environment Variable Overrides (highest priority) +# ═══════════════════════════════════════════════════════════════════════════════ +# +# LOG_LEVEL → global.level +# LOG_DIR → global.dir +# LOG_FORMAT → global.format +# SLOW_REQUEST_THRESHOLD_MS → backend.slow_request_threshold_ms +# LOG_AGGREGATION_ENABLED → aggregation.enabled +# LOG_AGGREGATION_ENDPOINT → aggregation.endpoint +# LOG_AGGREGATION_BATCH_SIZE → aggregation.batch_size +# LOG_AGGREGATION_FLUSH_INTERVAL → aggregation.flush_interval_s +# LOG_AGGREGATION_TIMEOUT → aggregation.timeout_s +# LOG_AGGREGATION_LABELS → aggregation.labels +# VITE_LOG_LEVEL → frontend.level +# VITE_SENTRY_DSN → frontend.sentry_enabled (if set) +# +# ═══════════════════════════════════════════════════════════════════════════════ diff --git a/docs/VEZA_PROJECT_DOCUMENTATION.md b/docs/VEZA_PROJECT_DOCUMENTATION.md new file mode 100644 index 000000000..567cf733a --- /dev/null +++ b/docs/VEZA_PROJECT_DOCUMENTATION.md @@ -0,0 +1,1059 @@ +# 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.* diff --git a/status.sh b/status.sh new file mode 100755 index 000000000..5997c00a6 --- /dev/null +++ b/status.sh @@ -0,0 +1,324 @@ +#!/usr/bin/env bash +# ═══════════════════════════════════════════════════════════════════════════════ +# VEZA — Project Status Dashboard +# Usage: ./status.sh (full report) +# ./status.sh --quick (infra + services only, no tests) +# ═══════════════════════════════════════════════════════════════════════════════ +set -uo pipefail + +# ── Colors & symbols ───────────────────────────────────────────────────────── +R=$'\033[0;31m' G=$'\033[0;32m' Y=$'\033[0;33m' B=$'\033[0;34m' +M=$'\033[0;35m' C=$'\033[0;36m' W=$'\033[1;37m' D=$'\033[0;90m' +NC=$'\033[0m' BOLD=$'\033[1m' DIM=$'\033[2m' + +OK="${G}✓${NC}" FAIL="${R}✗${NC}" WARN="${Y}⚠${NC}" SKIP="${D}○${NC}" +SPIN="${C}…${NC}" + +ROOT="$(cd "$(dirname "$0")" && pwd)" +cd "$ROOT" + +QUICK=false +[[ "${1:-}" == "--quick" || "${1:-}" == "-q" ]] && QUICK=true + +# ── Helpers ────────────────────────────────────────────────────────────────── +hr() { echo -e "${D}$(printf '─%.0s' {1..72})${NC}"; } +hdr() { echo -e "\n${BOLD}${C}▸ $1${NC}"; hr; } +ok() { echo -e " ${OK} $1"; } +ko() { echo -e " ${FAIL} $1"; } +wr() { echo -e " ${WARN} $1"; } +sk() { echo -e " ${SKIP} ${D}$1${NC}"; } +kv() { printf " %-24s " "$1"; echo -e "$2"; } + +check_port() { + local port="$1" + if ss -tlnp 2>/dev/null | grep -q ":${port} " || nc -z 127.0.0.1 "$port" 2>/dev/null; then + echo "up" + else + echo "down" + fi +} + +http_check() { + local url="$1" timeout="${2:-3}" + curl -s -o /dev/null -w '%{http_code}' --max-time "$timeout" "$url" 2>/dev/null || echo "000" +} + +# ═══════════════════════════════════════════════════════════════════════════════ +# HEADER +# ═══════════════════════════════════════════════════════════════════════════════ +echo +echo -e "${BOLD}${M} ╔═══════════════════════════════════════════════════════════════╗${NC}" +echo -e "${BOLD}${M} ║ VEZA — Project Status Dashboard ║${NC}" +echo -e "${BOLD}${M} ╚═══════════════════════════════════════════════════════════════╝${NC}" +echo -e " ${D}$(date '+%Y-%m-%d %H:%M:%S') • $(hostname)${NC}" + +# ═══════════════════════════════════════════════════════════════════════════════ +# GIT & VERSION +# ═══════════════════════════════════════════════════════════════════════════════ +hdr "GIT & VERSION" + +branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "?") +commit=$(git rev-parse --short HEAD 2>/dev/null || echo "?") +commit_msg=$(git log -1 --format='%s' 2>/dev/null | head -c 60 || echo "") +tag=$(git describe --tags --abbrev=0 2>/dev/null || echo "none") +ahead=$(git rev-list "${tag}..HEAD" --count 2>/dev/null || echo "?") +dirty=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ') + +kv "Branch:" "${W}${branch}${NC}" +kv "Latest tag:" "${G}${tag}${NC} ${D}(+${ahead} commits)${NC}" +kv "HEAD:" "${commit} — ${DIM}${commit_msg}${NC}" + +if [[ "$dirty" -gt 0 ]]; then + staged=$(git diff --cached --numstat 2>/dev/null | wc -l | tr -d ' ') + unstaged=$(git diff --numstat 2>/dev/null | wc -l | tr -d ' ') + untracked=$(git ls-files --others --exclude-standard 2>/dev/null | wc -l | tr -d ' ') + kv "Working tree:" "${Y}${dirty} changes${NC} ${D}(staged:${staged} modified:${unstaged} untracked:${untracked})${NC}" +else + kv "Working tree:" "${G}clean${NC}" +fi + +# ═══════════════════════════════════════════════════════════════════════════════ +# TOOLCHAIN +# ═══════════════════════════════════════════════════════════════════════════════ +hdr "TOOLCHAIN" + +go_ver=$(go version 2>/dev/null | awk '{print $3}' | sed 's/go//' || echo "not installed") +rust_ver=$(rustc --version 2>/dev/null | awk '{print $2}' || echo "not installed") +node_ver=$(node --version 2>/dev/null | sed 's/v//' || echo "not installed") +npm_ver=$(npm --version 2>/dev/null || echo "?") +docker_ver=$(docker --version 2>/dev/null | awk '{print $3}' | tr -d ',' || echo "not installed") + +kv "Go:" "${go_ver}" +kv "Rust:" "${rust_ver}" +kv "Node:" "${node_ver} ${D}(npm ${npm_ver})${NC}" +kv "Docker:" "${docker_ver}" + +air_ok=$(command -v air >/dev/null 2>&1 && echo "${G}yes${NC}" || echo "${D}no${NC}") +cargo_watch_ok=$(command -v cargo-watch >/dev/null 2>&1 && echo "${G}yes${NC}" || echo "${D}no${NC}") +kv "Hot reload:" "air=${air_ok} cargo-watch=${cargo_watch_ok}" + +# ═══════════════════════════════════════════════════════════════════════════════ +# DOCKER INFRASTRUCTURE +# ═══════════════════════════════════════════════════════════════════════════════ +hdr "DOCKER INFRASTRUCTURE" + +if ! docker info >/dev/null 2>&1; then + ko "Docker daemon is not running" +else + for name in postgres redis rabbitmq clamav minio elasticsearch; do + container="veza_${name}" + status=$(docker inspect -f '{{.State.Status}}' "$container" 2>/dev/null || echo "absent") + health=$(docker inspect -f '{{.State.Health.Status}}' "$container" 2>/dev/null || echo "n/a") + label=$(printf '%-16s' "$name") + + case "$status" in + running) + if [[ "$health" == "healthy" ]]; then + ok "${label} ${G}running${NC} ${G}healthy${NC}" + elif [[ "$health" == "unhealthy" ]]; then + wr "${label} ${G}running${NC} ${R}unhealthy${NC}" + else + ok "${label} ${G}running${NC} ${D}(no healthcheck)${NC}" + fi ;; + exited) ko "${label} ${R}exited${NC}" ;; + *) sk "${label} ${status}" ;; + esac + done +fi + +# ═══════════════════════════════════════════════════════════════════════════════ +# APPLICATION SERVICES +# ═══════════════════════════════════════════════════════════════════════════════ +hdr "APPLICATION SERVICES" + +declare -A SVC_PORTS=( [backend-api]=18080 [stream-server]=18082 [frontend]=5173 ) +declare -A SVC_HEALTH=( [backend-api]="/api/v1/health" [stream-server]="/health" [frontend]="/" ) + +for svc in backend-api stream-server frontend; do + port="${SVC_PORTS[$svc]}" + endpoint="${SVC_HEALTH[$svc]}" + url="http://localhost:${port}${endpoint}" + label=$(printf '%-16s' "$svc") + + state=$(check_port "$port") + if [[ "$state" == "up" ]]; then + code=$(http_check "$url" 3) + if [[ "$code" =~ ^2 ]]; then + ok "${label} ${G}:${port}${NC} HTTP ${G}${code}${NC}" + elif [[ "$code" == "000" ]]; then + wr "${label} ${Y}:${port}${NC} ${Y}port open, no HTTP${NC}" + else + wr "${label} ${G}:${port}${NC} HTTP ${Y}${code}${NC}" + fi + else + ko "${label} ${R}:${port} not listening${NC}" + fi +done + +# Rate limiting probe (only if backend is up) +if [[ "$(check_port 18080)" == "up" ]]; then + got429=false + for _ in $(seq 1 8); do + c=$(curl -s -o /dev/null -w '%{http_code}' --max-time 2 \ + -X POST http://localhost:18080/api/v1/auth/login \ + -H 'Content-Type: application/json' \ + -d '{"email":"probe@test.invalid","password":"x"}' 2>/dev/null) || c="000" + [[ "$c" == "429" ]] && got429=true && break + done + if $got429; then + kv "Rate limiting:" "${Y}ACTIVE${NC} — use ${W}make dev-e2e${NC} for tests" + else + kv "Rate limiting:" "${G}disabled (test mode)${NC}" + fi +fi + +# ═══════════════════════════════════════════════════════════════════════════════ +# DATABASE +# ═══════════════════════════════════════════════════════════════════════════════ +hdr "DATABASE" + +pg_port="${PORT_POSTGRES:-15432}" +if [[ "$(check_port "$pg_port")" == "up" ]]; then + pg_url="postgres://veza:${DB_PASSWORD:-password}@localhost:${pg_port}/veza?sslmode=disable" + + tbl_count=$(psql "$pg_url" -t -c "SELECT count(*) FROM information_schema.tables WHERE table_schema='public'" 2>/dev/null | tr -d ' ' || echo "?") + kv "Tables:" "${tbl_count}" + + mig_count=$(find veza-backend-api/migrations -maxdepth 1 -name '*.sql' ! -name '*_down*' 2>/dev/null | wc -l | tr -d ' ') + latest_mig=$(find veza-backend-api/migrations -maxdepth 1 -name '*.sql' ! -name '*_down*' -printf '%f\n' 2>/dev/null | sort -n | tail -1 || echo "none") + kv "Migrations:" "${mig_count} files — latest: ${D}${latest_mig}${NC}" + + for tbl in users tracks playlists products; do + cnt=$(psql "$pg_url" -t -c "SELECT count(*) FROM ${tbl}" 2>/dev/null | tr -d ' ' || echo "—") + kv " ${tbl}:" "${cnt} rows" + done +else + sk "PostgreSQL not reachable on :${pg_port}" +fi + +# ═══════════════════════════════════════════════════════════════════════════════ +# CODEBASE STATS +# ═══════════════════════════════════════════════════════════════════════════════ +hdr "CODEBASE" + +go_files=$(find veza-backend-api -name '*.go' ! -path '*/vendor/*' 2>/dev/null | wc -l | tr -d ' ') +rs_files=$(find veza-stream-server -name '*.rs' 2>/dev/null | wc -l | tr -d ' ') +ts_files=$(find apps/web/src \( -name '*.ts' -o -name '*.tsx' \) 2>/dev/null | wc -l | tr -d ' ') +e2e_files=$(find tests/e2e -name '*.spec.ts' 2>/dev/null | wc -l | tr -d ' ') +e2e_tests=$(grep -rch "test(" tests/e2e/*.spec.ts 2>/dev/null | awk '{s+=$1}END{print s+0}') + +kv "Go (backend):" "${go_files} files" +kv "Rust (stream):" "${rs_files} files" +kv "TS/TSX (web):" "${ts_files} files" +kv "E2E specs:" "${e2e_files} files — ${W}~${e2e_tests} tests${NC}" + +# ═══════════════════════════════════════════════════════════════════════════════ +# TESTS (skip with --quick) +# ═══════════════════════════════════════════════════════════════════════════════ +if $QUICK; then + hdr "TESTS ${D}(skipped — run without --quick)${NC}" +else + hdr "TESTS" + + # ── Go tests ── + echo -ne " ${SPIN} Running Go tests…\r" + go_out=$(cd veza-backend-api && go test ./internal/handlers/... ./internal/services/... -short -count=1 -timeout 60s 2>&1) || true + go_pass=$(echo "$go_out" | grep -c '^ok' || true) + go_fail=$(echo "$go_out" | grep -c '^FAIL' || true) + go_skip=$(echo "$go_out" | grep -c '\[no test files\]' || true) + printf '\r\033[2K' + if [[ "$go_fail" -eq 0 ]]; then + ok "Go: ${G}${go_pass} passed${NC} ${D}${go_skip} skipped${NC}" + else + ko "Go: ${G}${go_pass} passed${NC} ${R}${go_fail} FAILED${NC} ${D}${go_skip} skipped${NC}" + fi + + # ── Rust tests ── + echo -ne " ${SPIN} Running Rust tests…\r" + rust_out=$(cd veza-stream-server && cargo test --lib -q 2>&1) || true + rust_summary=$(echo "$rust_out" | grep -E 'test result:' | head -1 || echo "") + printf '\r\033[2K' + if echo "$rust_summary" | grep -q "0 failed" 2>/dev/null; then + ok "Rust: ${G}${rust_summary}${NC}" + elif [[ -n "$rust_summary" ]]; then + ko "Rust: ${R}${rust_summary}${NC}" + else + rust_pass=$(echo "$rust_out" | grep -oP '\d+ passed' | head -1 || echo "? passed") + ok "Rust: ${G}${rust_pass}${NC}" + fi + + # ── Frontend unit tests ── + echo -ne " ${SPIN} Running frontend tests…\r" + web_out=$(cd apps/web && npx vitest run --reporter=verbose 2>&1 | tail -30) || true + web_summary=$(echo "$web_out" | grep -iE 'Tests\s+\d|test files' | tail -1 || echo "") + printf '\r\033[2K' + if [[ -n "$web_summary" ]]; then + if echo "$web_summary" | grep -qi "failed"; then + ko "Web: ${web_summary}" + else + ok "Web: ${web_summary}" + fi + else + sk "Web: could not parse results" + fi + + # ── E2E last run ── + last_run="tests/e2e/test-results/.last-run.json" + if [[ -f "$last_run" ]]; then + pw_status=$(python3 -c "import json,sys; d=json.load(open(sys.argv[1])); print(d.get('status','?'))" "$last_run" 2>/dev/null || echo "?") + kv "E2E last run:" "${pw_status}" + else + sk "E2E: no previous run — use ${W}npm run e2e${NC}" + fi +fi + +# ═══════════════════════════════════════════════════════════════════════════════ +# VERSIONS ROADMAP +# ═══════════════════════════════════════════════════════════════════════════════ +hdr "ROADMAP" + +roadmap="VEZA_VERSIONS_ROADMAP.md" +if [[ -f "$roadmap" ]]; then + done_count=$(grep -c '✅ DONE' "$roadmap" || true) + todo_count=$(grep -c '⏳ TODO' "$roadmap" || true) + progress_count=$(grep -cE '🔄|🔨' "$roadmap" || true) + + kv "Done:" "${G}${done_count}${NC} versions" + [[ "$progress_count" -gt 0 ]] && kv "In progress:" "${Y}${progress_count}${NC} versions" + [[ "$todo_count" -gt 0 ]] && kv "Todo:" "${D}${todo_count}${NC} versions" + + # Extract next TODO version name (format: "## vX.Y.Z — Name") + next_line=$(grep -B5 '⏳ TODO' "$roadmap" | grep -oP 'v\d+\.\d+\.\d+\s*[—–-]\s*.*' | head -1 || true) + [[ -n "$next_line" ]] && kv "Next up:" "${W}${next_line}${NC}" +else + sk "Roadmap file not found" +fi + +# ═══════════════════════════════════════════════════════════════════════════════ +# HEALTH SUMMARY +# ═══════════════════════════════════════════════════════════════════════════════ +echo +hr + +total_ok=0; total_ko=0 + +for svc in postgres redis rabbitmq; do + container="veza_${svc}" + s=$(docker inspect -f '{{.State.Status}}' "$container" 2>/dev/null || echo "absent") + h=$(docker inspect -f '{{.State.Health.Status}}' "$container" 2>/dev/null || echo "n/a") + if [[ "$s" == "running" && "$h" == "healthy" ]]; then ((total_ok++)); else ((total_ko++)) || true; fi +done + +for port in 18080 18082 5173; do + if [[ "$(check_port "$port")" == "up" ]]; then ((total_ok++)); else ((total_ko++)) || true; fi +done + +if [[ "$total_ko" -eq 0 ]]; then + echo -e " ${BOLD}${G}ALL SYSTEMS OPERATIONAL${NC} (${total_ok}/6 services up)" +elif [[ "$total_ko" -le 2 ]]; then + echo -e " ${BOLD}${Y}PARTIAL${NC} — ${total_ok} up, ${total_ko} down" +else + echo -e " ${BOLD}${R}DEGRADED${NC} — ${total_ok} up, ${total_ko} down" +fi + +echo