# 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