veza/veza-docs/ORIGIN/ORIGIN_MASTER_ARCHITECTURE.md

# ORIGIN_MASTER_ARCHITECTURE.md

## 📋 RÉSUMÉ EXÉCUTIF

Ce document définit l'architecture technique complète et définitive de la plateforme Veza (Talas) pour les 24 prochains mois. Il constitue la source de vérité absolue pour toutes les décisions architecturales et ne peut être modifié sans processus de change management formel. L'architecture cible une plateforme audio collaborative combinant streaming, marketplace, social, et éducation avec une capacité de 100,000+ utilisateurs concurrents.

## 🎯 OBJECTIFS

### Objectif Principal
Définir une architecture microservices scalable, sécurisée et performante capable de supporter 600+ fonctionnalités réparties sur 21 modules métier avec des SLA de 99.9% uptime et <100ms latency.

### Objectifs Secondaires
- Assurer la cohérence architecturale sur 24 mois de développement
- Documenter toutes les décisions architecturales (ADR)
- Établir les standards de communication inter-services
- Définir les patterns de sécurité, performance et observabilité

## 📖 TABLE DES MATIÈRES

1. [Vue d'Ensemble Architecturale](#1-vue-densemble-architecturale)
2. [Architecture des Services](#2-architecture-des-services)
3. [Infrastructure et Déploiement](#3-infrastructure-et-déploiement)
4. [Flux de Données](#4-flux-de-données)
5. [Sécurité](#5-sécurité)
6. [Performance et Scalabilité](#6-performance-et-scalabilité)
7. [Observabilité](#7-observabilité)
8. [Décisions Architecturales (ADR)](#8-décisions-architecturales-adr)
9. [Conventions de Nommage](#9-conventions-de-nommage)
10. [Structure des Répertoires](#10-structure-des-répertoires)

## 🔒 RÈGLES IMMUABLES

Les décisions suivantes sont **ABSOLUES et NON NÉGOCIABLES** pour les 24 prochains mois:

1. **Backend API Principal**: Go 1.23+ uniquement (stabilité, performance, typage fort)
2. **Services Temps Réel**: Rust 1.75+ uniquement (sécurité mémoire, performance critique)
3. **Frontend**: React 18+ avec TypeScript 5.3+ strict mode (pas de JavaScript pur)
4. **Base de Données Principale**: PostgreSQL 15+ (ACID, relations, performance)
5. **Cache**: Redis 7+ (in-memory, pub/sub, sessions)
6. **Communication Services**: gRPC pour inter-service, REST pour clients externes
7. **Message Queue**: RabbitMQ 3.12+ pour événements asynchrones
8. **Container Runtime**: Docker 24+ (standardisation, portabilité)
9. **API Gateway**: Traefik 2.10+ (moderne, cloud-native, labels)
10. **Monitoring**: Prometheus + Grafana + Loki (standard industrie)

## 1. VUE D'ENSEMBLE ARCHITECTURALE

### 1.1 Architecture Globale

```mermaid
graph TB
    subgraph "Frontend Layer"
        WEB[Web App React]
        MOBILE[Mobile Apps RN]
        DESKTOP[Desktop Electron]
    end
    
    subgraph "API Gateway Layer"
        TRAEFIK[Traefik API Gateway]
        LB[Load Balancer]
    end
    
    subgraph "Backend Services"
        API[API Backend Go]
        CHAT[Chat Server Rust]
        STREAM[Stream Server Rust]
        WORKER[Background Workers]
    end
    
    subgraph "Data Layer"
        PG[(PostgreSQL)]
        REDIS[(Redis Cluster)]
        S3[(Object Storage S3)]
        ES[(Elasticsearch)]
    end
    
    subgraph "Message Layer"
        RABBITMQ[RabbitMQ]
        KAFKA[Kafka Optional]
    end
    
    subgraph "External Services"
        STRIPE[Stripe Payments]
        SENDGRID[SendGrid Email]
        CDN[CloudFront CDN]
    end
    
    WEB --> TRAEFIK
    MOBILE --> TRAEFIK
    DESKTOP --> TRAEFIK
    
    TRAEFIK --> API
    TRAEFIK --> CHAT
    TRAEFIK --> STREAM
    
    API --> PG
    API --> REDIS
    API --> S3
    API --> RABBITMQ
    API --> STRIPE
    API --> SENDGRID
    
    CHAT --> PG
    CHAT --> REDIS
    CHAT --> RABBITMQ
    
    STREAM --> PG
    STREAM --> REDIS
    STREAM --> S3
    STREAM --> CDN
    
    WORKER --> RABBITMQ
    WORKER --> PG
    WORKER --> S3
    
    API --> ES
    ES -.-> PG
```

### 1.2 Patterns Architecturaux

#### 1.2.1 Clean Architecture (Hexagonal)
Tous les services suivent le pattern Clean Architecture avec séparation stricte en couches:

```
src/
├── domain/              # Entités métier, règles business (indépendant)
│   ├── entities/        # User, Track, Playlist, etc.
│   ├── value_objects/   # Email, Money, Duration, etc.
│   └── interfaces/      # Ports (abstractions)
├── application/         # Cas d'usage, services applicatifs
│   ├── use_cases/       # CreateUser, UploadTrack, etc.
│   ├── services/        # AuthService, PaymentService, etc.
│   └── dto/            # Data Transfer Objects
├── infrastructure/      # Implémentations techniques
│   ├── persistence/     # Repositories PostgreSQL
│   ├── cache/          # Redis adapters
│   ├── messaging/      # RabbitMQ publishers/consumers
│   ├── storage/        # S3 file storage
│   └── external/       # Stripe, SendGrid, etc.
└── interfaces/          # Adapters externes
    ├── http/           # REST handlers (Gin)
    ├── grpc/           # gRPC handlers (Tonic)
    └── websocket/      # WebSocket handlers (Axum)
```

**Règle de Dépendance**: Les dépendances pointent TOUJOURS vers l'intérieur
- `interfaces` → `application` → `domain`
- `infrastructure` → `application` → `domain`
- `domain` ne dépend de RIEN (pure business logic)

#### 1.2.2 Domain-Driven Design (DDD)

##### Bounded Contexts (21 Domaines)

1. **Authentication & Security** (`auth`)
   - Aggregates: User, Session, MFAConfig
   - Events: UserRegistered, UserLoggedIn, PasswordChanged

2. **User Profiles** (`profiles`)
   - Aggregates: UserProfile, Badge, Achievement
   - Events: ProfileUpdated, BadgeEarned

3. **File Management** (`files`)
   - Aggregates: File, Upload, Metadata
   - Events: FileUploaded, FileProcessed, FileDeleted

4. **Audio Streaming** (`streaming`)
   - Aggregates: Track, Playlist, Queue
   - Events: TrackPlayed, PlaylistCreated, QueueUpdated

5. **Chat & Messaging** (`chat`)
   - Aggregates: Conversation, Message, Room
   - Events: MessageSent, RoomCreated, UserJoinedRoom

6. **Social & Community** (`social`)
   - Aggregates: Follow, Post, Comment, Like
   - Events: UserFollowed, PostCreated, CommentAdded

7. **Marketplace** (`marketplace`)
   - Aggregates: Product, License, Order
   - Events: ProductListed, OrderPlaced, PaymentProcessed

8. **Education** (`education`)
   - Aggregates: Course, Lesson, Enrollment
   - Events: CourseCreated, EnrollmentStarted, LessonCompleted

9. **Hardware Management** (`hardware`)
   - Aggregates: Equipment, Warranty, Maintenance
   - Events: EquipmentAdded, WarrantyExpiring

10. **Cloud Storage** (`cloud`)
    - Aggregates: CloudAccount, SyncJob, Backup
    - Events: BackupCompleted, SyncFailed

11. **Search & Discovery** (`search`)
    - Aggregates: SearchQuery, SearchResult, Recommendation
    - Events: SearchPerformed, RecommendationGenerated

12. **Analytics** (`analytics`)
    - Aggregates: Metric, Report, Dashboard
    - Events: MetricRecorded, ReportGenerated

13. **Administration** (`admin`)
    - Aggregates: AdminUser, ModeratorAction, SystemConfig
    - Events: UserBanned, ContentRemoved

14. **UI/UX** (`ui`)
    - Aggregates: Theme, Layout, Preference
    - Events: ThemeChanged, LayoutCustomized

15. **AI & Advanced Features** (`ai`)
    - Aggregates: MasteringJob, StemSeparation, AIModel
    - Events: AudioProcessed, ModelTrained

16. **Live Streaming** (`live`)
    - Aggregates: LiveStream, StreamSession, Viewer
    - Events: StreamStarted, ViewerJoined

17. **Collaboration** (`collab`)
    - Aggregates: Project, Version, Contributor
    - Events: ProjectCreated, VersionCommitted

18. **Blockchain/Web3** (`web3`)
    - Aggregates: NFT, SmartContract, Wallet
    - Events: NFTMinted, RoyaltyDistributed

19. **External Integrations** (`integrations`)
    - Aggregates: Integration, Connection, Sync
    - Events: IntegrationConnected, SyncCompleted

20. **Mobile/Desktop Apps** (`native`)
    - Aggregates: Device, AppSession, Notification
    - Events: DeviceRegistered, NotificationSent

21. **Gamification** (`gamification`)
    - Aggregates: XP, Level, Achievement, Leaderboard
    - Events: XPGained, LevelUp, AchievementUnlocked

#### 1.2.3 Event-Driven Architecture

```mermaid
graph LR
    SERVICE_A[Service A] -->|Publish Event| RABBITMQ[RabbitMQ Exchange]
    RABBITMQ -->|Route| QUEUE_B[Queue B]
    RABBITMQ -->|Route| QUEUE_C[Queue C]
    QUEUE_B --> SERVICE_B[Service B Subscribe]
    QUEUE_C --> SERVICE_C[Service C Subscribe]
    
    SERVICE_B -->|Store| EVENT_STORE[(Event Store)]
    SERVICE_C -->|Store| EVENT_STORE
```

**Event Naming Convention**: `{Domain}.{Entity}.{Action}.{Version}`
- Examples: `auth.user.registered.v1`, `marketplace.order.paid.v1`

**Event Structure** (JSON):
```json
{
  "event_id": "uuid-v4",
  "event_type": "auth.user.registered.v1",
  "aggregate_id": "user-123",
  "aggregate_type": "User",
  "timestamp": "2025-11-02T10:30:00Z",
  "version": 1,
  "data": {
    "user_id": "123",
    "email": "user@example.com",
    "username": "johndoe"
  },
  "metadata": {
    "correlation_id": "request-456",
    "causation_id": "command-789",
    "user_agent": "Mozilla/5.0..."
  }
}
```

#### 1.2.4 CQRS (Command Query Responsibility Segregation)

**Séparation stricte Write/Read**:

```
Commands (Write)          Queries (Read)
     ↓                         ↑
 Write Model              Read Model
     ↓                         ↑
PostgreSQL (Master)     Redis + Elasticsearch
```

**Command Example** (Go):
```go
type CreateUserCommand struct {
    CommandID   string
    Username    string
    Email       string
    Password    string
    FirstName   string
    LastName    string
}

type CreateUserHandler struct {
    repo UserRepository
    bus  EventBus
}

func (h *CreateUserHandler) Handle(ctx context.Context, cmd CreateUserCommand) error {
    // 1. Validate
    if err := cmd.Validate(); err != nil {
        return ErrInvalidCommand
    }
    
    // 2. Create aggregate
    user, err := domain.NewUser(cmd.Username, cmd.Email, cmd.Password)
    if err != nil {
        return err
    }
    
    // 3. Persist
    if err := h.repo.Save(ctx, user); err != nil {
        return err
    }
    
    // 4. Publish events
    for _, event := range user.UncommittedEvents() {
        h.bus.Publish(ctx, event)
    }
    
    return nil
}
```

**Query Example** (Go):
```go
type GetUserQuery struct {
    UserID string
}

type GetUserQueryHandler struct {
    cache  *redis.Client
    search *elasticsearch.Client
}

func (h *GetUserQueryHandler) Handle(ctx context.Context, q GetUserQuery) (*UserDTO, error) {
    // 1. Try cache first
    cached, err := h.cache.Get(ctx, "user:"+q.UserID).Result()
    if err == nil {
        return unmarshal(cached)
    }
    
    // 2. Query read model
    user, err := h.search.Get(ctx, "users", q.UserID)
    if err != nil {
        return nil, ErrUserNotFound
    }
    
    // 3. Cache for next time
    h.cache.Set(ctx, "user:"+q.UserID, user, 5*time.Minute)
    
    return toDTO(user), nil
}
```

## 2. ARCHITECTURE DES SERVICES

### 2.1 Backend API (Go)

**Repository**: `/veza-backend-api`
**Port**: `8080`
**Protocol**: HTTP/2 (REST), gRPC
**Language**: Go 1.23+
**Framework**: Gin 1.9+ (HTTP), gRPC-Go 1.59+

#### 2.1.1 Responsabilités

- Authentification/Autorisation (JWT, OAuth2, 2FA)
- Gestion utilisateurs, profils, rôles
- API REST pour clients web/mobile
- Business logic core
- Orchestration des workflows
- Gestion des transactions
- API publique documentée (OpenAPI)

#### 2.1.2 Endpoints Principaux

**Base URL**: `https://api.veza.app/v1`

| Groupe | Endpoints | Méthodes | Auth Required |
|--------|-----------|----------|---------------|
| **Auth** | `/auth/*` | POST | Partial |
| - Register | `/auth/register` | POST | No |
| - Login | `/auth/login` | POST | No |
| - Logout | `/auth/logout` | POST | Yes |
| - Refresh | `/auth/refresh` | POST | Yes (Refresh Token) |
| - 2FA Setup | `/auth/2fa/setup` | POST | Yes |
| - 2FA Verify | `/auth/2fa/verify` | POST | Yes |
| - Password Reset | `/auth/password/reset` | POST | No |
| **Users** | `/users/*` | GET, PUT, DELETE | Yes |
| - Get Profile | `/users/{id}` | GET | Yes |
| - Update Profile | `/users/{id}` | PUT | Yes |
| - Delete Account | `/users/{id}` | DELETE | Yes |
| - Upload Avatar | `/users/{id}/avatar` | POST | Yes |
| **Tracks** | `/tracks/*` | GET, POST, PUT, DELETE | Partial |
| - List Tracks | `/tracks` | GET | No |
| - Get Track | `/tracks/{id}` | GET | No |
| - Upload Track | `/tracks` | POST | Yes |
| - Update Metadata | `/tracks/{id}` | PUT | Yes (Owner) |
| - Delete Track | `/tracks/{id}` | DELETE | Yes (Owner) |
| **Playlists** | `/playlists/*` | GET, POST, PUT, DELETE | Partial |
| **Marketplace** | `/marketplace/*` | GET, POST | Partial |
| **Search** | `/search/*` | GET | No |
| **Admin** | `/admin/*` | ALL | Yes (Admin Role) |

#### 2.1.3 Structure Interne

```
veza-backend-api/
├── cmd/
│   └── api/
│       └── main.go                 # Entry point
├── internal/
│   ├── domain/                     # Domain layer (pure business)
│   │   ├── user/
│   │   │   ├── user.go            # User aggregate
│   │   │   ├── repository.go     # User repository interface
│   │   │   └── events.go         # Domain events
│   │   ├── track/
│   │   ├── playlist/
│   │   └── shared/
│   │       ├── errors.go
│   │       └── value_objects.go
│   ├── application/                # Application layer
│   │   ├── commands/
│   │   │   ├── create_user.go
│   │   │   └── upload_track.go
│   │   ├── queries/
│   │   │   ├── get_user.go
│   │   │   └── search_tracks.go
│   │   └── services/
│   │       ├── auth_service.go
│   │       ├── payment_service.go
│   │       └── notification_service.go
│   ├── infrastructure/             # Infrastructure layer
│   │   ├── persistence/
│   │   │   ├── postgres/
│   │   │   │   ├── user_repository.go
│   │   │   │   └── migrations/
│   │   │   └── redis/
│   │   │       └── cache_repository.go
│   │   ├── messaging/
│   │   │   └── rabbitmq/
│   │   │       ├── publisher.go
│   │   │       └── consumer.go
│   │   ├── storage/
│   │   │   └── s3/
│   │   │       └── file_storage.go
│   │   └── external/
│   │       ├── stripe/
│   │       └── sendgrid/
│   └── interfaces/                 # Interfaces layer
│       ├── http/
│       │   ├── handlers/
│       │   │   ├── auth_handler.go
│       │   │   └── user_handler.go
│       │   ├── middleware/
│       │   │   ├── auth.go
│       │   │   ├── rate_limit.go
│       │   │   └── cors.go
│       │   └── routes.go
│       └── grpc/
│           └── server.go
├── pkg/                            # Public packages
│   ├── logger/
│   ├── validator/
│   └── jwt/
├── migrations/                     # Database migrations
│   ├── 001_create_users.sql
│   └── 002_create_tracks.sql
├── go.mod
└── go.sum
```

#### 2.1.4 Technologies & Dépendances

```go
// go.mod (exact versions LOCKED)
module veza-backend-api

go 1.23.8

require (
    github.com/gin-gonic/gin v1.9.1              // HTTP framework
    github.com/google/uuid v1.6.0                // UUID generation
    github.com/golang-jwt/jwt/v5 v5.3.0          // JWT tokens
    github.com/lib/pq v1.10.9                    // PostgreSQL driver
    gorm.io/gorm v1.25.5                         // ORM
    gorm.io/driver/postgres v1.5.4               // GORM PostgreSQL
    github.com/redis/go-redis/v9 v9.16.0         // Redis client
    github.com/rabbitmq/amqp091-go v1.9.0        // RabbitMQ
    github.com/aws/aws-sdk-go-v2 v1.24.0         // AWS S3
    github.com/stripe/stripe-go/v76 v76.16.0     // Stripe payments
    go.uber.org/zap v1.27.0                      // Structured logging
    github.com/prometheus/client_golang v1.18.0  // Metrics
    google.golang.org/grpc v1.59.0               // gRPC
    github.com/spf13/viper v1.18.2               // Configuration
    golang.org/x/crypto v0.41.0                  // Bcrypt, argon2
)
```

### 2.2 Chat Server (Rust)

**Repository**: `/veza-chat-server`
**Port**: `8081`
**Protocol**: WebSocket (WS/WSS), gRPC
**Language**: Rust 1.75+
**Framework**: Axum 0.8+, Tokio 1.35+

#### 2.2.1 Responsabilités

- Chat temps réel (WebSocket)
- Messagerie 1-to-1 et groupes
- Rooms publiques/privées
- Notifications push
- Présence utilisateurs (online/offline)
- Message history et recherche
- File sharing dans chat
- Reactions et threads
- End-to-end encryption (optionnel)

#### 2.2.2 Architecture WebSocket

```mermaid
sequenceDiagram
    participant Client
    participant WSServer
    participant RoomManager
    participant MessageStore
    participant RabbitMQ
    
    Client->>WSServer: WebSocket Upgrade
    WSServer->>Client: 101 Switching Protocols
    Client->>WSServer: Auth Token
    WSServer->>RoomManager: Register Connection
    
    Client->>WSServer: Send Message
    WSServer->>MessageStore: Store Message
    MessageStore->>RabbitMQ: Publish Event
    WSServer->>RoomManager: Broadcast to Room
    RoomManager->>Client: Deliver Message
```

#### 2.2.3 Message Protocol

**WebSocket Message Format** (JSON):
```json
{
  "type": "message",
  "action": "send",
  "data": {
    "room_id": "room-123",
    "content": "Hello World!",
    "message_type": "text",
    "reply_to": null,
    "metadata": {}
  },
  "request_id": "req-456",
  "timestamp": "2025-11-02T10:30:00Z"
}
```

**Server Response**:
```json
{
  "type": "message",
  "action": "received",
  "data": {
    "message_id": "msg-789",
    "room_id": "room-123",
    "sender_id": "user-123",
    "content": "Hello World!",
    "created_at": "2025-11-02T10:30:00Z"
  },
  "request_id": "req-456"
}
```

#### 2.2.4 Structure Interne

```
veza-chat-server/
├── src/
│   ├── main.rs                     # Entry point
│   ├── lib.rs                      # Library root
│   ├── config.rs                   # Configuration
│   ├── websocket/
│   │   ├── mod.rs
│   │   ├── handler.rs             # WebSocket handler
│   │   ├── connection.rs          # Connection management
│   │   └── protocol.rs            # Message protocol
│   ├── rooms/
│   │   ├── mod.rs
│   │   ├── manager.rs             # Room management
│   │   └── state.rs               # Room state
│   ├── messages/
│   │   ├── mod.rs
│   │   ├── store.rs               # Message persistence
│   │   └── search.rs              # Message search
│   ├── presence/
│   │   ├── mod.rs
│   │   └── tracker.rs             # User presence
│   ├── auth/
│   │   ├── mod.rs
│   │   └── jwt.rs                 # JWT validation
│   ├── models/
│   │   ├── mod.rs
│   │   ├── message.rs
│   │   ├── room.rs
│   │   └── user.rs
│   └── infrastructure/
│       ├── database.rs            # PostgreSQL
│       ├── cache.rs               # Redis
│       └── messaging.rs           # RabbitMQ
├── migrations/
│   ├── 001_create_rooms.sql
│   └── 002_create_messages.sql
├── Cargo.toml
└── Cargo.lock
```

#### 2.2.5 Technologies & Dépendances

```toml
[dependencies]
# Async runtime
tokio = { version = "1.35", features = ["full", "tracing"] }
axum = { version = "0.8", features = ["macros", "ws"] }

# WebSocket
tokio-tungstenite = "0.21"
futures-util = "0.3"

# Database
sqlx = { version = "0.8", features = ["postgres", "runtime-tokio-native-tls", "uuid", "chrono", "json"] }
redis = { version = "0.32", features = ["tokio-comp", "connection-manager"] }

# Serialization
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

# Security
jsonwebtoken = "9.2"
bcrypt = "0.17"

# Messaging
lapin = "2.3"  # RabbitMQ client

# Monitoring
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }

# Utilities
uuid = { version = "1.6", features = ["v4", "serde"] }
chrono = { version = "0.4", features = ["serde"] }
dashmap = "6.1"  # Concurrent HashMap
```

### 2.3 Stream Server (Rust)

**Repository**: `/veza-stream-server`
**Port**: `8082`
**Protocol**: HTTP/2, HLS, WebRTC
**Language**: Rust 1.75+
**Framework**: Axum 0.7+, Tokio 1.0+

#### 2.3.1 Responsabilités

- Streaming audio haute performance
- Transcoding multi-format (MP3, FLAC, AAC, OGG)
- Adaptive bitrate streaming (HLS)
- Audio processing (normalization, EQ)
- Waveform generation
- CDN integration
- DRM protection (optionnel)
- Live streaming support
- Low-latency playback (<50ms)

#### 2.3.2 Streaming Pipeline

```mermaid
graph LR
    UPLOAD[File Upload] --> VALIDATE[Validation]
    VALIDATE --> TRANSCODE[Transcoding]
    TRANSCODE --> NORMALIZE[Audio Normalization]
    NORMALIZE --> WAVEFORM[Waveform Generation]
    WAVEFORM --> SEGMENTS[HLS Segmentation]
    SEGMENTS --> CDN[CDN Upload]
    CDN --> READY[Ready to Stream]
```

#### 2.3.3 Supported Formats

| Input Formats | Output Formats | Bitrates | Sample Rates |
|---------------|----------------|----------|--------------|
| WAV | MP3 | 128, 192, 256, 320 kbps | 44.1, 48 kHz |
| FLAC | AAC | 128, 192, 256, 320 kbps | 44.1, 48, 96 kHz |
| MP3 | OGG Vorbis | 128, 192, 256, 320 kbps | 44.1, 48 kHz |
| M4A | FLAC | Lossless | 44.1, 48, 96, 192 kHz |
| AIFF | OPUS | 64, 96, 128, 192 kbps | 48 kHz |

#### 2.3.4 HLS Streaming

**Playlist Structure** (.m3u8):
```
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:10
#EXT-X-MEDIA-SEQUENCE:0
#EXTINF:10.0,
segment0.ts
#EXTINF:10.0,
segment1.ts
#EXTINF:10.0,
segment2.ts
#EXT-X-ENDLIST
```

**Adaptive Bitrate**:
```
#EXTM3U
#EXT-X-STREAM-INF:BANDWIDTH=128000,RESOLUTION=0x0
stream_128k.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=192000,RESOLUTION=0x0
stream_192k.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=320000,RESOLUTION=0x0
stream_320k.m3u8
```

#### 2.3.5 Technologies & Dépendances

```toml
[dependencies]
# Async runtime
tokio = { version = "1.0", features = ["full"] }
axum = { version = "0.7", features = ["macros", "multipart", "ws"] }

# Audio processing
symphonia = { version = "0.5", features = ["all"] }
hound = "3.5"  # WAV
minimp3 = "0.5"  # MP3 decoder
rubato = "0.15"  # Resampling

# FFT and signal processing
rustfft = "6.2"
dasp = "0.11"

# Streaming protocols
m3u8-rs = "5.0"  # HLS playlists

# Database
sqlx = { version = "0.7", features = ["postgres", "runtime-tokio-rustls", "uuid", "chrono"] }
redis = { version = "0.25", features = ["tokio-comp", "connection-manager"] }

# Storage
reqwest = { version = "0.11", features = ["json", "stream"] }

# Compression
brotli = "3.4"
lz4_flex = "0.11"

# Utilities
uuid = { version = "1.6", features = ["v4", "serde"] }
chrono = { version = "0.4", features = ["serde"] }
bytes = "1.5"
```

### 2.4 Frontend Web (React)

**Repository**: `/apps/web`
**Port**: `5176` (dev), `443` (prod)
**Protocol**: HTTPS
**Language**: TypeScript 5.3+
**Framework**: React 18+, Vite 7+

#### 2.4.1 Responsabilités

- Interface utilisateur web
- State management (Zustand)
- API client (Axios + React Query)
- WebSocket client (chat, notifications)
- Audio player UI
- Forms avec validation (React Hook Form + Zod)
- Internationalisation (i18next)
- Responsive design (Tailwind CSS)
- Progressive Web App (PWA)

#### 2.4.2 Architecture Frontend

```
apps/web/
├── public/
│   ├── manifest.json
│   └── service-worker.js
├── src/
│   ├── main.tsx                    # Entry point
│   ├── App.tsx                     # Root component
│   ├── features/                   # Feature-based organization
│   │   ├── auth/
│   │   │   ├── components/
│   │   │   │   ├── LoginForm.tsx
│   │   │   │   └── RegisterForm.tsx
│   │   │   ├── hooks/
│   │   │   │   └── useAuth.ts
│   │   │   ├── services/
│   │   │   │   └── authService.ts
│   │   │   └── types.ts
│   │   ├── player/
│   │   ├── chat/
│   │   ├── marketplace/
│   │   └── dashboard/
│   ├── components/                 # Shared components
│   │   ├── ui/                     # Base UI components
│   │   │   ├── Button.tsx
│   │   │   ├── Input.tsx
│   │   │   └── Card.tsx
│   │   └── layout/
│   │       ├── Header.tsx
│   │       ├── Sidebar.tsx
│   │       └── Footer.tsx
│   ├── lib/                        # Utilities
│   │   ├── api.ts                  # API client
│   │   ├── websocket.ts            # WebSocket client
│   │   └── utils.ts
│   ├── stores/                     # Zustand stores
│   │   ├── authStore.ts
│   │   ├── playerStore.ts
│   │   └── chatStore.ts
│   ├── hooks/                      # Custom hooks
│   │   ├── useApi.ts
│   │   └── useWebSocket.ts
│   ├── types/                      # TypeScript types
│   │   └── index.ts
│   ├── i18n/                       # Translations
│   │   ├── en.json
│   │   ├── fr.json
│   │   └── i18n.ts
│   └── styles/
│       └── globals.css
├── package.json
├── tsconfig.json
├── vite.config.ts
└── tailwind.config.js
```

#### 2.4.3 Technologies & Dépendances

```json
{
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-router-dom": "^6.22.0",
    "@tanstack/react-query": "^5.17.0",
    "axios": "^1.6.7",
    "zustand": "^4.5.0",
    "react-hook-form": "^7.49.3",
    "zod": "^3.25.76",
    "@hookform/resolvers": "^3.3.4",
    "i18next": "^25.5.2",
    "react-i18next": "^15.7.3",
    "lucide-react": "^0.321.0",
    "tailwind-merge": "^2.2.1",
    "clsx": "^2.1.0"
  },
  "devDependencies": {
    "@vitejs/plugin-react": "^4.2.1",
    "typescript": "^5.3.3",
    "vite": "^7.1.5",
    "tailwindcss": "^4.0.0",
    "eslint": "^9.0.0",
    "prettier": "^3.2.5",
    "vitest": "^3.2.4",
    "@playwright/test": "^1.41.2"
  }
}
```

## 3. INFRASTRUCTURE ET DÉPLOIEMENT

### 3.1 Architecture de Déploiement

```mermaid
graph TB
    subgraph "Production Environment"
        subgraph "Edge Layer"
            CF[CloudFlare CDN]
            WAF[Web Application Firewall]
        end
        
        subgraph "Load Balancing"
            NGINX[NGINX Load Balancer]
        end
        
        subgraph "Application Layer"
            API1[API Server 1]
            API2[API Server 2]
            API3[API Server 3]
            CHAT1[Chat Server 1]
            CHAT2[Chat Server 2]
            STREAM1[Stream Server 1]
            STREAM2[Stream Server 2]
        end
        
        subgraph "Data Layer"
            PG_PRIMARY[(PostgreSQL Primary)]
            PG_REPLICA1[(PostgreSQL Replica 1)]
            PG_REPLICA2[(PostgreSQL Replica 2)]
            REDIS_CLUSTER[(Redis Cluster)]
        end
        
        subgraph "Storage Layer"
            S3[S3 Object Storage]
            CDN_ORIGIN[CDN Origin]
        end
    end
    
    CF --> WAF
    WAF --> NGINX
    
    NGINX --> API1
    NGINX --> API2
    NGINX --> API3
    NGINX --> CHAT1
    NGINX --> CHAT2
    NGINX --> STREAM1
    NGINX --> STREAM2
    
    API1 --> PG_PRIMARY
    API2 --> PG_PRIMARY
    API3 --> PG_PRIMARY
    
    API1 --> REDIS_CLUSTER
    CHAT1 --> REDIS_CLUSTER
    STREAM1 --> REDIS_CLUSTER
    
    PG_PRIMARY --> PG_REPLICA1
    PG_PRIMARY --> PG_REPLICA2
    
    STREAM1 --> S3
    S3 --> CDN_ORIGIN
    CDN_ORIGIN --> CF
```

### 3.2 Environnements

| Environnement | URL | Purpose | Data |
|---------------|-----|---------|------|
| **Development** | `http://localhost:*` | Local dev | Fixtures |
| **Staging** | `https://staging.veza.app` | Pre-prod testing | Anonymized prod |
| **Production** | `https://veza.app` | Live users | Production |

### 3.3 Docker Compose (Development)

```yaml
# docker-compose.yml
version: '3.8'

services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: veza_db
      POSTGRES_USER: veza
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U veza"]
      interval: 5s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    command: redis-server --appendonly yes
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5

  rabbitmq:
    image: rabbitmq:3.12-management-alpine
    ports:
      - "5672:5672"
      - "15672:15672"
    environment:
      RABBITMQ_DEFAULT_USER: veza
      RABBITMQ_DEFAULT_PASS: ${RABBITMQ_PASSWORD}
    volumes:
      - rabbitmq_data:/var/lib/rabbitmq
    healthcheck:
      test: ["CMD", "rabbitmq-diagnostics", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  backend-api:
    build:
      context: ./veza-backend-api
      dockerfile: Dockerfile
    ports:
      - "8080:8080"
    environment:
      DATABASE_URL: postgres://veza:${DB_PASSWORD}@postgres:5432/veza_db
      REDIS_URL: redis://redis:6379
      RABBITMQ_URL: amqp://veza:${RABBITMQ_PASSWORD}@rabbitmq:5672/
      JWT_SECRET: ${JWT_SECRET}
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
      rabbitmq:
        condition: service_healthy

  chat-server:
    build:
      context: ./veza-chat-server
      dockerfile: Dockerfile
    ports:
      - "8081:8081"
    environment:
      DATABASE_URL: postgres://veza:${DB_PASSWORD}@postgres:5432/veza_db
      REDIS_URL: redis://redis:6379
      RABBITMQ_URL: amqp://veza:${RABBITMQ_PASSWORD}@rabbitmq:5672/
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

  stream-server:
    build:
      context: ./veza-stream-server
      dockerfile: Dockerfile
    ports:
      - "8082:8082"
    environment:
      DATABASE_URL: postgres://veza:${DB_PASSWORD}@postgres:5432/veza_db
      REDIS_URL: redis://redis:6379
      S3_ENDPOINT: ${S3_ENDPOINT}
      S3_BUCKET: ${S3_BUCKET}
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

  frontend:
    build:
      context: ./apps/web
      dockerfile: Dockerfile
    ports:
      - "5176:80"
    environment:
      VITE_API_URL: http://backend-api:8080
      VITE_WS_URL: ws://chat-server:8081
      VITE_STREAM_URL: http://stream-server:8082

volumes:
  postgres_data:
  redis_data:
  rabbitmq_data:
```

### 3.4 Ports et Protocoles

| Service | Port | Protocol | Access |
|---------|------|----------|--------|
| Backend API | 8080 | HTTP/2, gRPC | Public |
| Chat Server | 8081 | WebSocket | Public |
| Stream Server | 8082 | HTTP/2, HLS | Public |
| PostgreSQL | 5432 | TCP | Internal |
| Redis | 6379 | TCP | Internal |
| RabbitMQ | 5672 | AMQP | Internal |
| RabbitMQ Management | 15672 | HTTP | Internal |
| Prometheus | 9090 | HTTP | Internal |
| Grafana | 3000 | HTTP | Internal |
| Traefik Dashboard | 8888 | HTTP | Internal |

## 4. FLUX DE DONNÉES

### 4.1 Flux d'Authentification

```mermaid
sequenceDiagram
    participant User
    participant Frontend
    participant API
    participant PostgreSQL
    participant Redis
    
    User->>Frontend: Enter credentials
    Frontend->>API: POST /auth/login
    API->>PostgreSQL: Validate credentials
    PostgreSQL-->>API: User found
    API->>API: Generate JWT
    API->>Redis: Store session
    API-->>Frontend: JWT + Refresh Token
    Frontend->>Frontend: Store tokens (httpOnly cookie)
    Frontend->>API: GET /users/me (with JWT)
    API->>Redis: Validate JWT
    Redis-->>API: Session valid
    API-->>Frontend: User profile
```

### 4.2 Flux d'Upload de Track

```mermaid
sequenceDiagram
    participant User
    participant Frontend
    participant API
    participant StreamServer
    participant S3
    participant RabbitMQ
    participant Worker
    participant PostgreSQL
    
    User->>Frontend: Select audio file
    Frontend->>API: POST /tracks/upload (multipart)
    API->>API: Validate file (type, size)
    API->>S3: Upload raw file
    S3-->>API: File URL
    API->>PostgreSQL: Create track record (status: processing)
    API->>RabbitMQ: Publish TrackUploaded event
    API-->>Frontend: Track ID, status
    
    RabbitMQ->>Worker: Consume TrackUploaded event
    Worker->>S3: Download raw file
    Worker->>StreamServer: POST /transcode
    StreamServer->>StreamServer: Transcode to multiple formats
    StreamServer->>StreamServer: Generate waveform
    StreamServer->>S3: Upload processed files
    StreamServer-->>Worker: Processing complete
    Worker->>PostgreSQL: Update track (status: ready)
    Worker->>RabbitMQ: Publish TrackProcessed event
    RabbitMQ->>API: Consume TrackProcessed event
    API->>Frontend: WebSocket notification
    Frontend->>User: Track ready!
```

### 4.3 Flux de Chat Temps Réel

```mermaid
sequenceDiagram
    participant UserA
    participant FrontendA
    participant ChatServer
    participant Redis
    participant PostgreSQL
    participant RabbitMQ
    participant FrontendB
    participant UserB
    
    FrontendA->>ChatServer: WebSocket connect
    ChatServer->>Redis: Register connection
    FrontendB->>ChatServer: WebSocket connect
    ChatServer->>Redis: Register connection
    
    UserA->>FrontendA: Type message
    FrontendA->>ChatServer: Send message
    ChatServer->>PostgreSQL: Store message
    ChatServer->>Redis: Cache message
    ChatServer->>RabbitMQ: Publish MessageSent event
    ChatServer->>FrontendB: Deliver message (WebSocket)
    FrontendB->>UserB: Display message
```

## 5. SÉCURITÉ

### 5.1 Authentication & Authorization

#### 5.1.1 JWT Structure

```json
{
  "header": {
    "alg": "RS256",
    "typ": "JWT"
  },
  "payload": {
    "sub": "user-123",
    "email": "user@example.com",
    "roles": ["user", "creator"],
    "permissions": ["track:create", "track:read"],
    "iat": 1730550000,
    "exp": 1730553600,
    "jti": "token-uuid"
  }
}
```

**Token Lifetime**:
- Access Token: 15 minutes
- Refresh Token: 30 days
- Remember Me Token: 90 days

#### 5.1.2 RBAC (Role-Based Access Control)

**Roles Hierarchy**:
```
admin (all permissions)
  ↓
moderator (moderation permissions)
  ↓
creator (content creation permissions)
  ↓
premium_user (premium features)
  ↓
user (basic permissions)
  ↓
guest (read-only)
```

**Permissions Matrix**:

| Resource | guest | user | creator | premium | moderator | admin |
|----------|-------|------|---------|---------|-----------|-------|
| Track Read | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Track Create | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Track Delete Own | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Track Delete Any | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
| User Ban | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
| System Config | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |

### 5.2 Data Encryption

**At Rest**:
- Database: AES-256-GCM (PostgreSQL pgcrypto)
- Files: AES-256-CBC (S3 SSE-KMS)
- Backups: AES-256-GCM

**In Transit**:
- TLS 1.3 minimum
- Cipher suites: TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256
- Certificate: Let's Encrypt + automatic renewal

### 5.3 Security Headers

```
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: geolocation=(), microphone=(), camera=()
```

### 5.4 Rate Limiting

| Endpoint | Rate Limit | Window | Burst |
|----------|------------|--------|-------|
| `/auth/login` | 5 requests | 15 min | 2 |
| `/auth/register` | 3 requests | 1 hour | 1 |
| `/api/v1/*` (authenticated) | 1000 requests | 1 min | 100 |
| `/api/v1/*` (guest) | 100 requests | 1 min | 20 |
| WebSocket connections | 10 connections | 1 min | 2 |

## 6. PERFORMANCE ET SCALABILITÉ

### 6.1 Performance Targets

| Metric | Target | Measurement |
|--------|--------|-------------|
| API Response Time (p95) | < 100ms | Prometheus |
| API Response Time (p99) | < 200ms | Prometheus |
| WebSocket Latency | < 50ms | Custom metrics |
| Database Query Time (p95) | < 10ms | pgStatements |
| Page Load Time (FCP) | < 1.5s | Lighthouse |
| Page Load Time (LCP) | < 2.5s | Lighthouse |
| Time to Interactive (TTI) | < 3.5s | Lighthouse |
| Audio Playback Start | < 500ms | Custom metrics |

### 6.2 Scalability Targets

| Resource | Target | Strategy |
|----------|--------|----------|
| Concurrent Users | 100,000+ | Horizontal scaling |
| Audio Streams | 10,000+ | CDN + adaptive bitrate |
| WebSocket Connections | 50,000+ | Multi-instance + Redis pub/sub |
| Database Connections | 1,000+ | Connection pooling (pgBouncer) |
| Messages/sec | 100,000+ | Queue sharding |
| File Uploads/min | 1,000+ | Background workers |

### 6.3 Caching Strategy

**Cache Layers**:

1. **Browser Cache** (Service Worker):
   - Static assets: 1 year
   - API responses: 5 minutes
   - Waveforms: 1 hour

2. **CDN Cache** (CloudFlare):
   - Audio files: 7 days
   - Images: 30 days
   - Static JS/CSS: 1 year

3. **Redis Cache**:
   - User sessions: 30 days
   - User profiles: 1 hour
   - Track metadata: 15 minutes
   - Search results: 5 minutes
   - Leaderboards: 1 minute

4. **Application Cache** (in-memory):
   - Configuration: Until restart
   - Feature flags: 1 minute
   - JWT public keys: 1 hour

**Cache Invalidation**:
- Write-through: Update DB + cache simultaneously
- Cache-aside: Read from cache, fallback to DB
- Event-driven: Invalidate on domain events

### 6.4 Database Optimization

**Indexes** (top 10 critical):
```sql
-- Users
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_username ON users(username);
CREATE INDEX idx_users_created_at ON users(created_at DESC);

-- Tracks
CREATE INDEX idx_tracks_creator_id ON tracks(creator_id);
CREATE INDEX idx_tracks_genre ON tracks(genre);
CREATE INDEX idx_tracks_created_at ON tracks(created_at DESC);

-- Messages
CREATE INDEX idx_messages_room_id_created_at ON messages(room_id, created_at DESC);
CREATE INDEX idx_messages_sender_id ON messages(sender_id);

-- Search
CREATE INDEX idx_tracks_search ON tracks USING GIN(to_tsvector('english', title || ' ' || artist));
CREATE INDEX idx_users_search ON users USING GIN(to_tsvector('english', username || ' ' || display_name));
```

**Partitioning**:
```sql
-- Messages table partitioned by month
CREATE TABLE messages_2025_01 PARTITION OF messages
    FOR VALUES FROM ('2025-01-01') TO ('2025-02-01');
    
-- Analytics events partitioned by day
CREATE TABLE analytics_events_2025_01_01 PARTITION OF analytics_events
    FOR VALUES FROM ('2025-01-01') TO ('2025-01-02');
```

**Connection Pooling** (pgBouncer):
```ini
[databases]
veza_db = host=postgres port=5432 dbname=veza_db

[pgbouncer]
pool_mode = transaction
max_client_conn = 1000
default_pool_size = 25
reserve_pool_size = 5
reserve_pool_timeout = 3
```

## 7. OBSERVABILITÉ

### 7.1 Logging

**Log Levels**:
- `TRACE`: Very detailed (disabled in production)
- `DEBUG`: Detailed debugging information
- `INFO`: General informational messages
- `WARN`: Warning messages
- `ERROR`: Error messages
- `FATAL`: Critical errors (application crash)

**Log Format** (JSON):
```json
{
  "timestamp": "2025-11-02T10:30:00.123Z",
  "level": "INFO",
  "service": "backend-api",
  "trace_id": "abc123",
  "span_id": "def456",
  "message": "User logged in successfully",
  "user_id": "user-123",
  "ip": "192.168.1.100",
  "duration_ms": 45
}
```

**Centralized Logging** (Loki):
```yaml
# promtail-config.yaml
server:
  http_listen_port: 9080

clients:
  - url: http://loki:3100/loki/api/v1/push

scrape_configs:
  - job_name: docker
    docker_sd_configs:
      - host: unix:///var/run/docker.sock
    relabel_configs:
      - source_labels: ['__meta_docker_container_name']
        target_label: 'container'
```

### 7.2 Metrics (Prometheus)

**Application Metrics**:
```go
// Go (backend-api)
var (
    httpRequestsTotal = prometheus.NewCounterVec(
        prometheus.CounterOpts{
            Name: "http_requests_total",
            Help: "Total number of HTTP requests",
        },
        []string{"method", "endpoint", "status"},
    )
    
    httpRequestDuration = prometheus.NewHistogramVec(
        prometheus.HistogramOpts{
            Name: "http_request_duration_seconds",
            Help: "HTTP request duration in seconds",
            Buckets: prometheus.DefBuckets,
        },
        []string{"method", "endpoint"},
    )
    
    activeWebSocketConnections = prometheus.NewGauge(
        prometheus.GaugeOpts{
            Name: "websocket_connections_active",
            Help: "Number of active WebSocket connections",
        },
    )
)
```

**Infrastructure Metrics**:
- CPU usage per service
- Memory usage per service
- Disk I/O
- Network I/O
- Database connections
- Cache hit/miss ratio

### 7.3 Tracing (Jaeger)

**Distributed Tracing**:
```go
import "go.opentelemetry.io/otel"

func CreateUser(ctx context.Context, input CreateUserInput) error {
    ctx, span := otel.Tracer("backend-api").Start(ctx, "CreateUser")
    defer span.End()
    
    span.SetAttributes(
        attribute.String("user.username", input.Username),
        attribute.String("user.email", input.Email),
    )
    
    // Business logic...
    
    if err != nil {
        span.RecordError(err)
        span.SetStatus(codes.Error, err.Error())
        return err
    }
    
    span.SetStatus(codes.Ok, "User created successfully")
    return nil
}
```

### 7.4 Alerting

**Alert Rules** (Prometheus Alertmanager):
```yaml
groups:
  - name: veza_alerts
    interval: 30s
    rules:
      # High error rate
      - alert: HighErrorRate
        expr: rate(http_requests_total{status=~"5.."}[5m]) > 0.05
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "High error rate detected"
          description: "Error rate is {{ $value | humanizePercentage }}"
      
      # High response time
      - alert: HighResponseTime
        expr: histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m])) > 0.5
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "High response time (p95)"
          description: "Response time p95 is {{ $value }}s"
      
      # Database connection pool exhausted
      - alert: DatabasePoolExhausted
        expr: pg_stat_database_numbackends / pg_settings_max_connections > 0.9
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "Database connection pool nearly exhausted"
          description: "Connection usage is {{ $value | humanizePercentage }}"
      
      # Service down
      - alert: ServiceDown
        expr: up{job="backend-api"} == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "Backend API is down"
          description: "Backend API has been down for more than 1 minute"
```

## 8. DÉCISIONS ARCHITECTURALES (ADR)

### ADR-001: Choix de Go pour le Backend API

**Date**: 2025-01-01  
**Statut**: Accepted  
**Contexte**: Besoin d'un langage performant, typé, avec bonne concurrence pour API REST haute charge.  
**Décision**: Utiliser Go 1.23+ avec framework Gin.  
**Conséquences**:  
- ✅ Compilation rapide, binaire unique
- ✅ Goroutines pour concurrence
- ✅ Typage fort, pas de runtime errors
- ✅ Excellent pour microservices
- ❌ Verbosité du code (error handling)
- ❌ Écosystème moins riche que Node.js

**Alternatives rejetées**:
- **Node.js**: Single-threaded, performance inférieure
- **Python**: GIL, performance médiocre pour API haute charge
- **Java**: Trop lourd, démarrage lent, complexité

### ADR-002: Choix de Rust pour Services Temps Réel

**Date**: 2025-01-01  
**Statut**: Accepted  
**Contexte**: WebSocket haute performance, sécurité mémoire critique.  
**Décision**: Utiliser Rust 1.75+ avec Axum + Tokio.  
**Conséquences**:  
- ✅ Zero-cost abstractions
- ✅ Sécurité mémoire garantie
- ✅ Performance native (C/C++ level)
- ✅ Concurrence safe (ownership model)
- ❌ Courbe d'apprentissage raide
- ❌ Temps de compilation long

**Alternatives rejetées**:
- **Go**: Garbage collection (latence imprévisible)
- **C++**: Pas de sécurité mémoire, complexité
- **Elixir**: Performance inférieure pour streaming audio

### ADR-003: Choix de PostgreSQL comme Base Principale

**Date**: 2025-01-01  
**Statut**: Accepted  
**Contexte**: Besoin ACID, relations complexes, performance.  
**Décision**: PostgreSQL 15+ comme base principale.  
**Conséquences**:  
- ✅ ACID complet
- ✅ Relations complexes (foreign keys, joins)
- ✅ Full-text search intégré
- ✅ JSON/JSONB pour flexibilité
- ✅ Extensions (pgcrypto, pg_trgm, etc.)
- ❌ Scaling horizontal complexe

**Alternatives rejetées**:
- **MySQL**: Moins de fonctionnalités avancées
- **MongoDB**: Pas ACID, relations difficiles
- **CockroachDB**: Trop jeune, écosystème limité

### ADR-004: Architecture Microservices Modulaire

**Date**: 2025-01-01  
**Statut**: Accepted  
**Contexte**: 600+ features, équipe multiple, scalabilité.  
**Décision**: Architecture microservices avec 3 services principaux (API, Chat, Stream).  
**Conséquences**:  
- ✅ Scalabilité indépendante
- ✅ Technologies différentes par service
- ✅ Isolation des pannes
- ✅ Déploiements indépendants
- ❌ Complexité opérationnelle
- ❌ Transactions distribuées complexes

**Alternatives rejetées**:
- **Monolithe**: Pas scalable, déploiements risqués
- **Serverless**: Vendor lock-in, cold starts
- **Microservices complets** (20+ services): Trop complexe au démarrage

### ADR-005: gRPC pour Communication Inter-Services

**Date**: 2025-01-01  
**Statut**: Accepted  
**Contexte**: Communication rapide et typée entre services.  
**Décision**: gRPC avec Protocol Buffers pour inter-service, REST pour clients.  
**Conséquences**:  
- ✅ Typage fort avec protobuf
- ✅ Performance (binaire, HTTP/2)
- ✅ Génération de code
- ✅ Streaming bidirectionnel
- ❌ Debugging plus difficile
- ❌ Moins universel que REST

**Alternatives rejetées**:
- **REST inter-services**: Moins performant, pas typé
- **GraphQL**: Trop complexe pour inter-service
- **Message Queue pure**: Latence, complexité

### ADR-006: Redis pour Cache et Sessions

**Date**: 2025-01-01  
**Statut**: Accepted  
**Contexte**: Besoin cache in-memory ultra-rapide + pub/sub.  
**Décision**: Redis 7+ Cluster.  
**Conséquences**:  
- ✅ Performance exceptionnelle (<1ms)
- ✅ Pub/sub intégré
- ✅ Structures de données riches
- ✅ Cluster mode (scaling horizontal)
- ❌ Volatilité (RAM)
- ❌ Coût (RAM expensive)

**Alternatives rejetées**:
- **Memcached**: Moins de fonctionnalités
- **In-memory applicatif**: Pas partagé entre instances
- **Hazelcast**: Trop complexe, Java-centric

### ADR-007: RabbitMQ pour Message Queue

**Date**: 2025-01-01  
**Statut**: Accepted  
**Contexte**: Événements asynchrones, découplage services.  
**Décision**: RabbitMQ 3.12+ avec AMQP.  
**Conséquences**:  
- ✅ Mature, stable
- ✅ Routing flexible (exchanges, queues)
- ✅ Garanties de livraison
- ✅ Management UI
- ❌ Throughput inférieur à Kafka
- ❌ Persistence moins optimale que Kafka

**Alternatives rejetées**:
- **Kafka**: Over-engineering pour début, complexité
- **AWS SQS**: Vendor lock-in
- **NATS**: Moins mature pour persistence

### ADR-008: React avec TypeScript pour Frontend

**Date**: 2025-01-01  
**Statut**: Accepted  
**Contexte**: UI complexe, typage strict, écosystème riche.  
**Décision**: React 18+ avec TypeScript 5.3+ strict.  
**Conséquences**:  
- ✅ Écosystème immense
- ✅ Typage strict (moins d'erreurs runtime)
- ✅ Performance (Concurrent Mode)
- ✅ Communauté énorme
- ❌ Bundle size important
- ❌ Complexité state management

**Alternatives rejetées**:
- **Vue.js**: Écosystème plus petit
- **Svelte**: Moins mature, écosystème limité
- **Angular**: Trop lourd, opinionated

### ADR-009: Vite comme Build Tool Frontend

**Date**: 2025-01-01  
**Statut**: Accepted  
**Contexte**: Build rapide, HMR performant.  
**Décision**: Vite 7+ au lieu de Webpack.  
**Conséquences**:  
- ✅ Build ultra-rapide (ESBuild)
- ✅ HMR instantané
- ✅ Configuration simple
- ✅ Support natif TypeScript
- ❌ Écosystème moins mature que Webpack

**Alternatives rejetées**:
- **Webpack**: Lent, configuration complexe
- **Parcel**: Moins performant que Vite
- **Rollup**: Moins de fonctionnalités DX

### ADR-010: Docker pour Conteneurisation

**Date**: 2025-01-01  
**Statut**: Accepted  
**Contexte**: Déploiement consistant multi-environnements.  
**Décision**: Docker 24+ avec multi-stage builds.  
**Conséquences**:  
- ✅ Portabilité totale
- ✅ Isolation
- ✅ Écosystème mature
- ✅ CI/CD intégré
- ❌ Overhead léger (performance)
- ❌ Sécurité (root privileges)

**Alternatives rejetées**:
- **VMs**: Trop lourd, lent
- **Bare metal**: Pas portable
- **Podman**: Moins mature

## 9. CONVENTIONS DE NOMMAGE

### 9.1 Base de Données

**Tables**: snake_case, pluriel
```sql
users
tracks
playlists
playlist_tracks
```

**Colonnes**: snake_case
```sql
user_id
created_at
updated_at
first_name
```

**Indexes**: `idx_{table}_{column(s)}`
```sql
idx_users_email
idx_tracks_creator_id_created_at
```

**Foreign Keys**: `fk_{source_table}_{target_table}`
```sql
fk_playlist_tracks_playlists
fk_playlist_tracks_tracks
```

### 9.2 Backend Go

**Packages**: lowercase, singular
```go
domain
application
infrastructure
```

**Structs**: PascalCase
```go
type User struct { }
type CreateUserCommand struct { }
```

**Functions/Methods**: PascalCase (public), camelCase (private)
```go
func CreateUser() { }      // Public
func validateEmail() { }   // Private
```

**Variables**: camelCase
```go
var userRepository UserRepository
var maxConnections int
```

**Constants**: PascalCase ou SCREAMING_SNAKE_CASE
```go
const MaxRetries = 3
const DEFAULT_TIMEOUT = 30 * time.Second
```

**Interfaces**: PascalCase, suffix `-er` si applicable
```go
type UserRepository interface { }
type Logger interface { }
type Validator interface { }
```

### 9.3 Rust

**Modules**: snake_case
```rust
mod websocket;
mod message_store;
```

**Structs/Enums**: PascalCase
```rust
struct Message { }
enum MessageType { }
```

**Functions**: snake_case
```rust
fn send_message() { }
fn validate_token() { }
```

**Constants**: SCREAMING_SNAKE_CASE
```rust
const MAX_MESSAGE_SIZE: usize = 1024;
```

**Traits**: PascalCase
```rust
trait MessageStore { }
trait Authenticator { }
```

### 9.4 TypeScript/React

**Files**: PascalCase (components), camelCase (utilities)
```
LoginForm.tsx
Button.tsx
utils.ts
api.ts
```

**Components**: PascalCase
```tsx
function LoginForm() { }
const Button: React.FC = () => { }
```

**Functions**: camelCase
```ts
function fetchUsers() { }
const handleSubmit = () => { }
```

**Types/Interfaces**: PascalCase
```ts
interface User { }
type CreateUserInput = { }
```

**Enums**: PascalCase
```ts
enum UserRole { }
```

**Constants**: SCREAMING_SNAKE_CASE
```ts
const API_BASE_URL = "https://api.veza.app";
```

### 9.5 API REST

**Endpoints**: kebab-case, pluriel pour ressources
```
GET  /api/v1/users
POST /api/v1/users
GET  /api/v1/users/{id}
PUT  /api/v1/users/{id}
DELETE /api/v1/users/{id}
POST /api/v1/users/{id}/avatar
GET  /api/v1/users/{id}/playlists
```

**Query Params**: snake_case
```
GET /api/v1/tracks?genre=rock&sort_by=created_at&order=desc
```

**JSON Fields**: camelCase
```json
{
  "userId": "123",
  "firstName": "John",
  "createdAt": "2025-11-02T10:30:00Z"
}
```

### 9.6 Events

**Event Names**: `{domain}.{entity}.{action}.{version}`
```
auth.user.registered.v1
marketplace.order.paid.v1
chat.message.sent.v1
```

**Event Fields**: camelCase (JSON)
```json
{
  "eventId": "evt-123",
  "eventType": "auth.user.registered.v1",
  "aggregateId": "user-123"
}
```

## 10. STRUCTURE DES RÉPERTOIRES

```
veza-full-stack/
├── .github/                        # GitHub Actions CI/CD
│   └── workflows/
│       ├── backend-ci.yml
│       ├── chat-ci.yml
│       ├── stream-ci.yml
│       └── frontend-ci.yml
├── ansible/                        # Ansible deployment
│   ├── inventory/
│   ├── playbooks/
│   └── roles/
├── apps/                           # Applications frontend
│   ├── web/                        # React web app
│   ├── mobile/                     # React Native mobile
│   └── desktop/                    # Electron desktop
├── config/                         # Configurations centralisées
│   ├── docker/
│   ├── prometheus/
│   ├── grafana/
│   └── nginx/
├── docs/                           # Documentation
│   ├── ORIGIN/                     # ⭐ Documents ORIGIN (immuables)
│   │   ├── ORIGIN_MASTER_ARCHITECTURE.md
│   │   ├── ORIGIN_DEVELOPMENT_PHASES.md
│   │   ├── ORIGIN_FEATURES_REGISTRY.md
│   │   └── ... (15 documents)
│   ├── architecture/
│   ├── api/
│   └── guides/
├── features/                       # Feature flags & contracts
│   └── core-contracts/
├── fixtures/                       # Test data & fixtures
│   ├── scenarios/
│   └── services/
├── scripts/                        # Utility scripts
│   ├── start-veza.sh
│   ├── stop-veza.sh
│   └── test-veza.sh
├── veza-backend-api/               # ⭐ Backend API (Go)
│   ├── cmd/
│   │   └── api/
│   │       └── main.go
│   ├── internal/
│   │   ├── domain/
│   │   ├── application/
│   │   ├── infrastructure/
│   │   └── interfaces/
│   ├── pkg/
│   ├── migrations/
│   ├── go.mod
│   └── Dockerfile
├── veza-chat-server/               # ⭐ Chat Server (Rust)
│   ├── src/
│   │   ├── main.rs
│   │   ├── lib.rs
│   │   ├── websocket/
│   │   ├── rooms/
│   │   └── messages/
│   ├── migrations/
│   ├── Cargo.toml
│   └── Dockerfile
├── veza-stream-server/             # ⭐ Stream Server (Rust)
│   ├── src/
│   │   ├── main.rs
│   │   ├── audio/
│   │   └── streaming/
│   ├── Cargo.toml
│   └── Dockerfile
├── veza-rust-common/               # Shared Rust code
│   ├── src/
│   │   ├── auth.rs
│   │   ├── models.rs
│   │   └── utils.rs
│   └── Cargo.toml
├── docker-compose.yml              # Development environment
├── docker-compose.production.yml   # Production environment
├── Makefile                        # Build automation
├── .env.example                    # Environment variables template
└── README.md                       # Project README
```

## ✅ CHECKLIST DE VALIDATION

### Architecture
- [ ] Tous les services sont définis avec ports et protocoles
- [ ] Les flux de données sont documentés avec diagrammes
- [ ] Les bounded contexts DDD sont clairement délimités
- [ ] Les patterns architecturaux sont explicites (Clean, CQRS, Event-Driven)
- [ ] Les décisions architecturales (ADR) sont documentées avec justifications

### Sécurité
- [ ] Authentification JWT avec refresh tokens
- [ ] Autorisation RBAC avec matrice de permissions
- [ ] Chiffrement at-rest et in-transit défini
- [ ] Rate limiting configuré par endpoint
- [ ] Security headers complets

### Performance
- [ ] Targets de performance définies (latence, throughput)
- [ ] Stratégie de caching multi-niveaux
- [ ] Optimisations base de données (indexes, partitioning)
- [ ] Connection pooling configuré
- [ ] CDN pour assets statiques et audio

### Observabilité
- [ ] Logging structuré (JSON) centralisé (Loki)
- [ ] Métriques Prometheus pour tous les services
- [ ] Distributed tracing (Jaeger/OpenTelemetry)
- [ ] Alerting rules définies (Alertmanager)
- [ ] Dashboards Grafana

### Infrastructure
- [ ] Docker Compose pour développement
- [ ] Kubernetes ready (futurs déploiements)
- [ ] CI/CD pipelines GitHub Actions
- [ ] Déploiement Ansible automatisé
- [ ] Environnements (dev, staging, prod) définis

## 📊 MÉTRIQUES DE SUCCÈS

### Technique
- **Code Quality**: Coverage > 80%, SonarQube Quality Gate A
- **Performance API**: p95 < 100ms, p99 < 200ms
- **Performance Frontend**: Lighthouse Score > 90
- **Uptime**: > 99.9% (SLA)
- **Security**: Zero vulnerabilities critiques (Snyk/Dependabot)

### Business
- **Concurrent Users**: 100,000+ supportés
- **Audio Streams**: 10,000+ simultanés
- **WebSocket Connections**: 50,000+ simultanées
- **Messages/sec**: 100,000+
- **Database Queries**: p95 < 10ms

### DevOps
- **Deploy Time**: < 10 minutes (zero-downtime)
- **Rollback Time**: < 5 minutes
- **Build Time**: < 5 minutes (CI)
- **MTTR** (Mean Time To Recovery): < 15 minutes
- **Change Failure Rate**: < 5%

## 🔄 HISTORIQUE DES VERSIONS

| Version | Date | Changements |
|---------|------|-------------|
| 1.0.0 | 2025-11-02 | Version initiale - Architecture complète définitive |

---

## ⚠️ AVERTISSEMENT

**CE DOCUMENT EST IMMUABLE**

Toute modification de ce document doit suivre le processus de Change Management formel:

1. **Proposition**: Créer une RFC (Request For Comments) avec justification détaillée
2. **Review**: Review par l'équipe technique (Lead Backend, Lead Frontend, DevOps, CTO)
3. **Approval**: Approbation unanime requise
4. **Documentation**: Mettre à jour ADR avec nouvelle décision
5. **Communication**: Communiquer à toute l'équipe
6. **Implémentation**: Planifier la migration si nécessaire

**Raisons acceptables de modification**:
- Vulnérabilité de sécurité critique découverte
- Technologie devenue obsolète (end-of-life)
- Performance dégradée non récupérable
- Changement réglementaire (GDPR, etc.)

**Raisons NON acceptables**:
- "On préfère technologie X"
- "C'est plus à la mode"
- "J'ai vu sur Hacker News..."
- "Mon ancien projet utilisait Y"

---

**Document créé par**: Architecture Team  
**Date de création**: 2025-11-02  
**Prochaine révision**: 2026-11-02 (ou sur trigger critique)  
**Propriétaire**: CTO / Lead Architect

**Statut**: ✅ **APPROUVÉ ET VERROUILLÉ**