227 lines
9.6 KiB
Markdown
227 lines
9.6 KiB
Markdown
|
# 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
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# 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
|