talas-group/03_APPS_&_SERVICES/ARCHITECTURE_VEZA.md

Architecture Technique Veza

Document de référence — architecture globale de la plateforme Veza. Source : code dans /home/senke/git/talas/veza/

Vue d'ensemble

Veza est une plateforme musicale communautaire composée de 3 services principaux communiquant via REST, WebSocket et RabbitMQ, le tout orchestré par Docker Compose.

┌─────────────────────────────────────────────────────────────┐
│                        FRONTEND                              │
│              React 18 · TypeScript · Tailwind                │
│              Vite · Zustand · TanStack Query                 │
│                    (apps/web/)                                │
└──────────┬──────────────┬───────────────┬────────────────────┘
           │ REST /api/v1 │ WS /chat/ws   │ WS /stream
           ▼              ▼               ▼
┌──────────────────┐ ┌────────────────────────────────────────┐
│  BACKEND API     │ │         STREAM SERVER                   │
│  Go · Gin · GORM │ │         Rust · Axum                     │
│  (veza-backend-  │ │         (veza-stream-server/)            │
│   api/)          │ │                                          │
│                  │ │  • Streaming audio (HLS adaptatif)       │
│  • 500+ endpoints│ │  • WebSocket temps réel                  │
│  • Auth JWT RS256│ │  • Transcoding FFmpeg                    │
│  • RBAC complet  │ │  • Métriques Prometheus                  │
│  • CSRF Redis    │ │                                          │
│  • Rate limiting │ └──────────────┬─────────────────────────┘
│  • Audit logging │                │
└──────┬───────────┘                │
       │                            │
       ▼                            ▼
┌──────────────────────────────────────────────────────────────┐
│                     INFRASTRUCTURE                            │
│                                                               │
│  PostgreSQL 16 (:15432)    Redis 7 (:16379)                   │
│  Elasticsearch (:19200)    RabbitMQ 3 (:15672)                │
│  MinIO S3 (:19000)         ClamAV 1.4 (:13310)               │
└──────────────────────────────────────────────────────────────┘

Structure du monorepo

veza/
├── apps/web/                    # Frontend React (SPA + PWA)
├── veza-backend-api/            # API REST Go (Gin + GORM)
├── veza-stream-server/          # Serveur streaming Rust (Axum)
├── veza-common/                 # Code partagé Go/Rust
├── veza-docs/                   # Documentation technique
├── veza-desktop/                # Wrapper Electron (charge apps/web)
├── docker-compose.yml           # Infra développement
├── docker-compose.prod.yml      # Infra production
├── docker-compose.dev.yml       # Services dev uniquement
├── .env.example                 # Template de configuration
├── Makefile                     # Commandes build & dev
└── k8s/                         # Manifests Kubernetes

Ports réseau (isolation pour éviter les conflits)

Service	Port	Protocole
Backend API	18080	HTTP/REST
Stream Server	18082	HTTP/WS
Frontend (dev)	5173	HTTP
PostgreSQL	15432	TCP
Redis	16379	TCP
RabbitMQ AMQP	15672	AMQP
RabbitMQ Management	25672	HTTP
ClamAV	13310	TCP
MinIO S3	19000	HTTP
Elasticsearch	19200	HTTP

Stack technique détaillée

Backend API (Go)

• Framework : Gin
• ORM : GORM v1 (mapping uniquement, migrations en SQL pur)
• Auth : JWT RS256 (fallback HS256), OAuth 2.0, WebAuthn/Passkeys, MFA TOTP
• Sécurité : CSRF Redis, rate limiting multi-niveaux, ClamAV antivirus, audit logging
• Recherche : Elasticsearch (fallback PostgreSQL full-text)
• Stockage : MinIO S3 compatible
• Monitoring : Prometheus, Sentry
• Base : PostgreSQL 16 avec UUIDs, soft deletes

Stream Server (Rust)

• Framework : Axum (async)
• Audio : HLS adaptatif multi-bitrate, FFmpeg transcoding
• Temps réel : WebSocket avec protocole de synchronisation
• Résilience : Circuit breaker, rate limiting, health checks
• Messaging : RabbitMQ pour les jobs de transcoding asynchrones

Frontend (React)

• Build : Vite v7.1.5
• UI : Tailwind CSS v4, Radix UI
• État : Zustand (stores), TanStack Query (data fetching)
• Formulaires : React Hook Form + Zod (validation)
• Routage : React Router v6 (52+ routes)
• i18n : i18next (EN/FR/ES)
• Tests : Vitest, Storybook
• Desktop : Electron wrapper (même codebase)

Patterns architecturaux

1. Microservices avec communication asynchrone

• Backend API (Go) → logique métier
• Stream Server (Rust) → streaming audio haute performance
• RabbitMQ → distribution d'événements entre services

2. Event-driven architecture

Événements principaux via RabbitMQ :

• user.created → notifications, indexation
• track.uploaded → scan ClamAV → transcoding HLS → indexation Elasticsearch
• payment.completed → mise à jour commande, notification vendeur

3. Sécurité en profondeur

• CSRF tokens (Redis-backed, obligatoire en production)
• JWT RS256 avec rotation de clés
• OAuth 2.0 avec chiffrement des tokens
• ClamAV pour scan antivirus des uploads
• Rate limiting : global (1000 req/s), par IP (100 req/s), par endpoint
• Verrouillage de compte après N tentatives échouées
• Audit logging automatique sur POST/PUT/DELETE
• Headers de sécurité (HSTS, CSP, X-Content-Type-Options)
• CCPA/RGPD : opt-out, export de données, suppression de compte

4. Observabilité

• Logs structurés (JSON en production, texte en dev)
• Métriques Prometheus (endpoints /metrics)
• Sentry pour le tracking d'erreurs
• Health checks (liveness /healthz, readiness /readyz)

Flux de données principaux

Inscription utilisateur

Frontend POST /api/v1/auth/register
  → Backend : validation Zod, hash bcrypt, création User en DB
  → Email de vérification envoyé
  → JWT retourné en cookie HTTP-only
  → Frontend redirige vers /verify-email

Upload de piste audio

Frontend POST /api/v1/tracks (multipart/form-data)
  → Backend : scan ClamAV → stockage S3 → parsing métadonnées FFmpeg
  → Création Track en DB (status: processing)
  → Publication événement track.uploaded sur RabbitMQ

Stream Server (écoute RabbitMQ)
  → Réception track.uploaded
  → Transcoding WAV → MP3 + HLS multi-bitrate
  → Upload segments sur S3
  → Publication transcoding.completed

Backend (écoute événement)
  → Mise à jour Track (status: completed, stream_manifest_url)
  → Indexation Elasticsearch
  → Notification utilisateur

Lecture audio streaming

Frontend WS /stream?track_id=xxx&position=0
  → Stream Server : validation JWT
  → Chargement playlist HLS depuis cache/S3
  → Sélection bitrate adaptatif selon réseau
  → Envoi chunks audio via WebSocket
  → Heartbeat toutes les 30s

Commandes de développement

# Stack complète (backend Docker, web local)
make dev

# Tous les services locaux avec hot reload
make dev-full

# Infrastructure seule (DB, Redis, RabbitMQ, MinIO)
docker-compose up -d

# Services individuels
make dev-web              # Frontend seul
make dev-backend-api      # Backend seul
make dev-stream-server    # Stream server seul

# Build production
make build

# Migrations base de données
cd veza-backend-api && go run ./cmd/migrate_tool/main.go up

Fichiers clés (chemins absolus)

Fichier	Rôle
veza-backend-api/cmd/api/main.go	Point d'entrée backend
veza-backend-api/internal/api/router.go	Enregistrement des routes
veza-backend-api/internal/config/config.go	Configuration
veza-backend-api/internal/models/	68 modèles GORM
veza-backend-api/internal/middleware/	17 middlewares
veza-backend-api/migrations/	115 fichiers SQL
veza-stream-server/src/main.rs	Point d'entrée streaming
veza-stream-server/src/routes/api.rs	Routes Axum
veza-stream-server/src/streaming/	WebSocket, HLS, adaptatif
apps/web/src/main.tsx	Point d'entrée frontend
apps/web/src/router/routeConfig.tsx	Définition des routes
apps/web/src/stores/	Stores Zustand
apps/web/src/services/api/	Clients API
docker-compose.yml	Stack développement
docker-compose.prod.yml	Stack production
.env.example	Template de configuration

Documents liés

• ROUTES_API — Référence complète des endpoints API
• SCHEMA_BASE_DE_DONNEES — Schéma PostgreSQL complet (60+ tables)
• SERVEUR_STREAMING_RUST — Architecture du serveur Rust Axum
• FRONTEND_REACT — Architecture frontend React
• CONFIGURATION_ENVIRONNEMENT — Variables d'environnement et Docker