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)

Stream Server (Rust)

Frontend (React)

Patterns architecturaux

1. Microservices avec communication asynchrone

2. Event-driven architecture

Événements principaux via RabbitMQ :

3. Sécurité en profondeur

4. Observabilité

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) {#stack-complete-backend-docker-web-local}
make dev

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

# Infrastructure seule (DB, Redis, RabbitMQ, MinIO) {#infrastructure-seule-db-redis-rabbitmq-minio}
docker-compose up -d

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

# Build production {#build-production}
make build

# Migrations base de données {#migrations-base-de-donnees}
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