senke/veza
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
veza/veza-docs/ORIGIN/ORIGIN_MASTER_ARCHITECTURE.md
senke 2df921abd5 v0.9.1
2026-03-05 19:22:31 +01:00

70 KiB
Raw Blame History

ORIGIN_MASTER_ARCHITECTURE.md

📋 RÉSUMÉ EXÉCUTIF

Ce document définit l'architecture technique de la plateforme Veza (Talas), une plateforme audio open source pour musiciens indépendants. Il constitue la source de vérité pour toutes les décisions architecturales. L'architecture cible une plateforme audio combinant streaming, marketplace, social et éducation avec une capacité de 100,000+ utilisateurs concurrents. Cette architecture intègre des contraintes éthiques explicites : pas de tracking comportemental, pas d'IA/ML, pas de blockchain, pas de gamification addictive. Les métriques servent le créateur, pas la plateforme.

🎯 OBJECTIFS

Objectif Principal

Définir une architecture microservices scalable, sécurisée et performante, alignée sur des principes éthiques documentés et auditables, capable de supporter les 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 (REST)
  • Définir les patterns de sécurité, performance et observabilité
  • Garantir l'auditabilité complète du code et des algorithmes (open source)

📖 TABLE DES MATIÈRES

  1. Principes d'Architecture Éthique
  2. Vue d'Ensemble Architecturale
  3. Architecture des Services
  4. Découverte Éthique (remplacement ML)
  5. Infrastructure et Déploiement
  6. Flux de Données
  7. Sécurité
  8. Performance et Scalabilité
  9. Observabilité
  10. Décisions Architecturales (ADR)
  11. Conventions de Nommage
  12. Structure des Répertoires
  13. Exclusions et Raisons Éthiques

🔒 RÈGLES IMMUABLES

Les décisions suivantes sont ABSOLUES et NON NÉGOCIABLES :

  1. Backend API Principal: Go 1.23+ uniquement (stabilité, performance, typage fort)
  2. Chat Server: Go 1.23+ (WebSocket, cohérence stack, performance suffisante)
  3. Stream Server: Rust 1.75+ uniquement (sécurité mémoire, performance critique audio)
  4. Frontend: React 18+ avec TypeScript 5.3+ strict mode (pas de JavaScript pur)
  5. Base de Données Principale: PostgreSQL 15+ (ACID, relations, performance)
  6. Recherche: Elasticsearch (fulltext, pas de ML)
  7. Cache: Redis 7+ (in-memory, pub/sub, sessions)
  8. Communication Services: REST uniquement (inter-service et clients externes)
  9. Message Queue: RabbitMQ 3.12+ pour événements asynchrones
  10. Paiements: Hyperswitch (agrégateur open source, pas de vendor lock-in Stripe)
  11. Container Runtime: Docker 24+ (standardisation, portabilité)
  12. API Gateway: Traefik 2.10+ (moderne, cloud-native, labels)
  13. Monitoring: Prometheus + Grafana + Loki (standard industrie)
  14. Pas d'IA/ML : aucun pipeline d'intelligence artificielle ou machine learning
  15. Pas de blockchain/Web3 : aucun smart contract, NFT, IPFS, crypto
  16. Pas de gamification addictive : pas de XP, niveaux, leaderboards

1. PRINCIPES D'ARCHITECTURE ÉTHIQUE

Ces principes sont des contraintes architecturales. Ils contraignent les choix techniques au même titre que les exigences de performance ou de sécurité.

1.1 Pas de tracking comportemental

Aucune collecte de données d'usage à des fins de profilage, ciblage publicitaire ou revente. Les analytics collectées servent exclusivement le créateur (nombre d'écoutes, provenance géographique agrégée) et sont accessibles à l'artiste via son dashboard. Aucune donnée comportementale n'alimente un algorithme de recommandation.

1.2 Métriques au service du créateur, pas de la plateforme

Les compteurs d'écoutes, les statistiques de téléchargement et les revenus marketplace sont exposés aux créateurs. La plateforme ne calcule pas de métriques d'engagement destinées à optimiser la rétention (temps passé, taux de scroll, boucles de notification).

1.3 Données minimales et justifiées

Chaque donnée collectée est documentée avec sa finalité. Si la finalité disparaît, la donnée est supprimée. Le schéma de base de données ne contient pas de colonnes "pour plus tard". Les données personnelles sont soumises aux principes de minimisation RGPD.

1.4 Algorithmes documentés et auditables

Tout algorithme de tri, classement ou découverte est documenté dans le code et dans la documentation. Les règles de classement (recherche, découverte, trending) sont déterministes et reproductibles. Pas de boîte noire.

1.5 Open source auditable

Le code source est publié sous licence open source. Toute personne peut vérifier que les principes éthiques sont respectés dans l'implémentation. Les dépendances sont auditées (Snyk/Dependabot).

2. VUE D'ENSEMBLE ARCHITECTURALE

2.1 Architecture Globale

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 Go]
        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]
    end
    
    subgraph "External Services"
        HYPERSWITCH[Hyperswitch 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 --> HYPERSWITCH
    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

2.2 Patterns Architecturaux

2.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/       # Hyperswitch, SendGrid, etc.
└── interfaces/          # Adapters externes
    ├── http/           # REST handlers (Gin)
    └── websocket/      # WebSocket handlers

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)

2.2.2 Domain-Driven Design (DDD)

Bounded Contexts (18 Domaines)

  1. Authentication & Security (auth)

    • Aggregates: User, Session, MFAConfig
    • Events: UserRegistered, UserLoggedIn, PasswordChanged

  2. User Profiles (profiles)

    • Aggregates: UserProfile, Badge
    • 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, CuratedPlaylist
    • Events: SearchPerformed, PlaylistCurated
    • Note: découverte par règles, curation humaine et graphe social (pas de ML)

  12. Analytics (analytics)

    • Aggregates: Metric, Report, Dashboard
    • Events: MetricRecorded, ReportGenerated
    • Note: métriques au service du créateur uniquement

  13. Administration (admin)

    • Aggregates: AdminUser, ModeratorAction, SystemConfig
    • Events: UserBanned, ContentRemoved

  14. UI/UX (ui)

    • Aggregates: Theme, Layout, Preference
    • Events: ThemeChanged, LayoutCustomized

  15. Live Streaming (live)

    • Aggregates: LiveStream, StreamSession, Viewer
    • Events: StreamStarted, ViewerJoined

  16. Collaboration (collab)

    • Aggregates: Project, Version, Contributor
    • Events: ProjectCreated, VersionCommitted

  17. External Integrations (integrations)

    • Aggregates: Integration, Connection, Sync
    • Events: IntegrationConnected, SyncCompleted

  18. Mobile/Desktop Apps (native)

    • Aggregates: Device, AppSession, Notification
    • Events: DeviceRegistered, NotificationSent

2.2.3 Event-Driven Architecture

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):

{
  "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..."
  }
}

2.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):

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):

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
}

3. ARCHITECTURE DES SERVICES

3.1 Backend API (Go)

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

3.1.1 Responsabilités

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

3.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)

3.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/
│   │       ├── hyperswitch/
│   │       └── sendgrid/
│   └── interfaces/                 # Interfaces layer
│       └── http/
│           ├── handlers/
│           │   ├── auth_handler.go
│           │   └── user_handler.go
│           ├── middleware/
│           │   ├── auth.go
│           │   ├── rate_limit.go
│           │   └── cors.go
│           └── routes.go
├── pkg/                            # Public packages
│   ├── logger/
│   ├── validator/
│   └── jwt/
├── migrations/                     # Database migrations
│   ├── 001_create_users.sql
│   └── 002_create_tracks.sql
├── go.mod
└── go.sum

3.1.4 Technologies & Dépendances

// 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 (RS256)
    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/olivere/elastic/v7 v7.0.32        // Elasticsearch client
    go.uber.org/zap v1.27.0                      // Structured logging
    github.com/prometheus/client_golang v1.18.0  // Metrics
    github.com/spf13/viper v1.18.2               // Configuration
    golang.org/x/crypto v0.41.0                  // Bcrypt, argon2
)

Note paiements : les paiements transitent via Hyperswitch (agrégateur open source). Le SDK Go Hyperswitch est intégré via son API REST. Pas de dépendance directe à un PSP unique (Stripe, Adyen, etc.).

3.2 Chat Server (Go)

Repository: /veza-chat-server Port: 8081 Protocol: WebSocket (WS/WSS) Language: Go 1.23+ Framework: Gin 1.9+ (HTTP), gorilla/websocket

3.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

3.2.2 Architecture WebSocket

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

3.2.3 Message Protocol

WebSocket Message Format (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:

{
  "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"
}

3.2.4 Structure Interne

veza-chat-server/
├── cmd/
│   └── chat/
│       └── main.go                 # Entry point
├── internal/
│   ├── domain/
│   │   ├── message.go             # Message aggregate
│   │   ├── room.go                # Room aggregate
│   │   └── events.go              # Domain events
│   ├── application/
│   │   ├── chat_service.go        # Chat service
│   │   └── presence_service.go    # Presence tracking
│   ├── infrastructure/
│   │   ├── persistence/
│   │   │   └── postgres/
│   │   │       ├── message_repository.go
│   │   │       └── room_repository.go
│   │   ├── cache/
│   │   │   └── redis_presence.go  # Redis presence + pub/sub
│   │   └── messaging/
│   │       └── rabbitmq/
│   │           ├── publisher.go
│   │           └── consumer.go
│   └── interfaces/
│       ├── http/
│       │   ├── handlers/
│       │   │   └── chat_handler.go
│       │   └── routes.go
│       └── websocket/
│           ├── hub.go             # Connection hub (goroutines)
│           ├── client.go          # WebSocket client handler
│           └── protocol.go        # Message protocol
├── migrations/
│   ├── 001_create_rooms.sql
│   └── 002_create_messages.sql
├── go.mod
└── go.sum

3.2.5 Technologies & Dépendances

// go.mod
module veza-chat-server

go 1.23.8

require (
    github.com/gin-gonic/gin v1.9.1              // HTTP framework
    github.com/gorilla/websocket v1.5.1           // WebSocket
    github.com/google/uuid v1.6.0                // UUID generation
    github.com/golang-jwt/jwt/v5 v5.3.0          // JWT validation (RS256)
    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 (presence, pub/sub)
    github.com/rabbitmq/amqp091-go v1.9.0        // RabbitMQ
    go.uber.org/zap v1.27.0                      // Structured logging
    github.com/prometheus/client_golang v1.18.0  // Metrics
    github.com/spf13/viper v1.18.2               // Configuration
)

3.3 Stream Server (Rust)

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

3.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
  • Live streaming support
  • Low-latency playback (<50ms)

3.3.2 Streaming Pipeline

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]

3.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

3.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

3.3.5 Technologies & Dépendances

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

# 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"

3.4 Frontend Web (React)

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

3.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)

3.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

3.4.3 Technologies & Dépendances

{
  "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"
  }
}

4. DÉCOUVERTE ÉTHIQUE (REMPLACEMENT ML)

L'architecture de découverte de Veza remplace les systèmes de recommandation ML par des mécanismes transparents, documentés et auditables.

4.1 Découverte par règles (genres/tags déclarés par l'artiste)

Les artistes déclarent eux-mêmes les genres, sous-genres et tags de leurs morceaux. La découverte s'appuie sur ces métadonnées déclaratives. L'algorithme de matching est déterministe : un utilisateur qui filtre "jazz" obtient les morceaux tagués "jazz", triés par date de publication ou popularité (nombre d'écoutes).

Requête utilisateur → Filtres (genre, tags, date) → Elasticsearch query → Résultats triés

Aucun profil utilisateur n'influence les résultats. Deux utilisateurs avec la même requête obtiennent les mêmes résultats.

4.2 Curation humaine

Les playlists de découverte sont créées et maintenues par des humains (équipe éditoriale, artistes invités, communauté). La plateforme ne génère pas automatiquement de playlists "pour vous" basées sur un profil comportemental.

Les playlists curées sont stockées en base PostgreSQL avec attribution claire du curateur.

4.3 Découverte par graphe social

Un utilisateur découvre de la musique via les artistes et utilisateurs qu'il suit. Le flux de découverte social est chronologique (pas d'algorithme de tri par "pertinence"). Les nouvelles publications des comptes suivis apparaissent dans un feed chronologique simple.

Feed social = SELECT tracks FROM follows WHERE follower_id = :user_id ORDER BY created_at DESC

4.4 Recherche fulltext (Elasticsearch)

La recherche utilise Elasticsearch pour l'indexation fulltext des titres, artistes, descriptions et tags. Pas de ML, pas de "did you mean" basé sur le comportement utilisateur.

graph LR
    USER[Utilisateur] -->|Recherche texte| API[API Go]
    API -->|Query| ES[Elasticsearch]
    ES -->|Résultats| API
    API -->|JSON| USER
    
    TRACK_CREATED[Track créée] -->|Event| WORKER[Worker]
    WORKER -->|Index| ES

Champs indexés : titre, artiste, description, genre, tags, album. Tri par défaut : pertinence Elasticsearch (TF-IDF/BM25), puis date. Filtres : genre, tags, durée, date de publication, licence.

4.5 Trending (algorithme documenté)

Le classement "trending" est basé sur une formule documentée et auditable :

score = nombre_écoutes_7_jours * decay_factor(age_publication)

La formule est publiée dans le code source et dans la documentation. Aucun facteur opaque n'intervient.

5. INFRASTRUCTURE ET DÉPLOIEMENT

5.1 Architecture de Déploiement

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

5.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

5.3 Docker Compose (Development)

# 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}
      HYPERSWITCH_URL: ${HYPERSWITCH_URL}
      HYPERSWITCH_API_KEY: ${HYPERSWITCH_API_KEY}
    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/
      JWT_SECRET: ${JWT_SECRET}
    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:

5.4 Ports et Protocoles

Service Port Protocol Access
Backend API 8080 HTTP/2 (REST) Public
Chat Server 8081 HTTP, 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

6. FLUX DE DONNÉES

6.1 Flux d'Authentification

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

6.2 Flux d'Upload de Track

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!

6.3 Flux de Chat Temps Réel

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

7. SÉCURITÉ

7.1 Authentication & Authorization

7.1.1 JWT Structure

{
  "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"
  }
}

Algorithme de signature : RS256 (asymétrique). Migration depuis HS256 planifiée.

Token Lifetime :

  • Access Token: 15 minutes
  • Refresh Token: 30 days
  • Remember Me Token: 90 days

7.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 ❌ ❌ ❌ ❌ ❌ ✅

7.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

7.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=()

7.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

8. PERFORMANCE ET SCALABILITÉ

8.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

8.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

8.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

  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

8.4 Database Optimization

Indexes (top 10 critical):

-- 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:

-- 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):

[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

9. OBSERVABILITÉ

9.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):

{
  "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):

# 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'

9.2 Metrics (Prometheus)

Application Metrics:

// 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

9.3 Tracing (Jaeger)

Distributed Tracing:

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
}

9.4 Alerting

Alert Rules (Prometheus Alertmanager):

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"

10. 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 Go pour le Chat Server

Date: 2025-01-01 (révisé 2026-03-04)
Statut: Accepted (révisé)
Contexte: Le chat nécessite des WebSocket performantes mais pas la performance critique du streaming audio. Rust était initialement prévu pour tous les services temps réel, mais la complexité de développement et de maintenance n'est pas justifiée pour le chat.
Décision: Utiliser Go 1.23+ avec gorilla/websocket pour le Chat Server. Rust reste pour le Stream Server uniquement.
Conséquences:

  • ✅ Cohérence stack avec le Backend API (Go + Go)
  • ✅ Goroutines suffisantes pour les WebSocket chat
  • ✅ Recrutement et maintenance plus simples
  • ✅ Temps de compilation rapide
  • ❌ GC pauses possibles (acceptable pour le chat, non critique)

Alternatives rejetées:

  • Rust (Axum): surengineering pour le chat, complexité de développement excessive
  • Node.js: single-threaded, performance inférieure

ADR-002b: Choix de Rust pour le Stream Server

Date: 2025-01-01
Statut: Accepted
Contexte: Le streaming audio nécessite une performance native pour le transcoding, le traitement audio et le HLS.
Décision: Utiliser Rust 1.75+ avec Axum + Tokio pour le Stream Server uniquement.
Conséquences:

  • ✅ Zero-cost abstractions pour le traitement audio
  • ✅ Sécurité mémoire garantie
  • ✅ Performance native (C/C++ level)
  • ❌ Courbe d'apprentissage raide
  • ❌ Temps de compilation long

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: Nombreuses features réparties sur 18 domaines métier, é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: REST pour Communication Inter-Services

Date: 2025-01-01 (révisé 2026-03-04)
Statut: Accepted (révisé)
Contexte: Avec 3 services (API, Chat, Stream), la complexité de gRPC (protobuf, code generation, debugging) n'est pas justifiée. REST est suffisant et simplifie le développement, le debugging et l'observabilité.
Décision: REST (JSON over HTTP/2) pour toutes les communications : inter-services et clients externes.
Conséquences:

  • ✅ Simplicité de développement et debugging
  • ✅ Outillage universel (curl, Postman, navigateur)
  • ✅ OpenAPI pour documentation et génération de clients
  • ✅ Un seul protocole à maîtriser
  • ❌ Overhead JSON vs protobuf (acceptable pour 3 services)

Alternatives rejetées:

  • gRPC: surengineering pour 3 services, debugging difficile
  • 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

ADR-011: Hyperswitch pour les Paiements

Date: 2026-03-04
Statut: Accepted
Contexte: Le projet nécessite un système de paiement pour la marketplace (vente de licences, beats, services). Un vendor lock-in sur un seul PSP (Stripe) limite la flexibilité et augmente les coûts.
Décision: Utiliser Hyperswitch, agrégateur de paiement open source, comme couche d'abstraction au-dessus des PSP.
Conséquences:

  • ✅ Multi-PSP (Stripe, Adyen, PayPal, etc.) sans changement de code
  • ✅ Open source, auditable
  • ✅ Pas de vendor lock-in
  • ✅ Smart routing entre PSP
  • ❌ Hébergement et maintenance de l'instance Hyperswitch
  • ❌ Moins de documentation que l'intégration Stripe directe

Alternatives rejetées:

  • Stripe direct: vendor lock-in, commissions non négociables
  • Développement interne: trop risqué pour la conformité PCI-DSS

ADR-012: Elasticsearch pour la Recherche (pas de ML)

Date: 2026-03-04
Statut: Accepted
Contexte: La recherche et la découverte de contenu doivent être transparentes et auditables. Les systèmes de recommandation ML sont des boîtes noires incompatibles avec les principes éthiques du projet.
Décision: Utiliser Elasticsearch pour la recherche fulltext avec des algorithmes déterministes (BM25). La découverte repose sur des règles, la curation humaine et le graphe social.
Conséquences:

  • ✅ Algorithme de scoring transparent et documenté
  • ✅ Résultats reproductibles et auditables
  • ✅ Pas de profilage utilisateur
  • ✅ Infrastructure mature et éprouvée
  • ❌ Pas de personnalisation automatique (choix éthique assumé)

Alternatives rejetées:

  • Algolia: propriétaire, boîte noire
  • ML/embeddings: incompatible avec les principes éthiques
  • PostgreSQL GIN seul: performance insuffisante à grande échelle

11. CONVENTIONS DE NOMMAGE

11.1 Base de Données

Tables: snake_case, pluriel

users
tracks
playlists
playlist_tracks

Colonnes: snake_case

user_id
created_at
updated_at
first_name

Indexes: idx_{table}_{column(s)}

idx_users_email
idx_tracks_creator_id_created_at

Foreign Keys: fk_{source_table}_{target_table}

fk_playlist_tracks_playlists
fk_playlist_tracks_tracks

11.2 Backend Go

Packages: lowercase, singular

domain
application
infrastructure

Structs: PascalCase

type User struct { }
type CreateUserCommand struct { }

Functions/Methods: PascalCase (public), camelCase (private)

func CreateUser() { }      // Public
func validateEmail() { }   // Private

Variables: camelCase

var userRepository UserRepository
var maxConnections int

Constants: PascalCase ou SCREAMING_SNAKE_CASE

const MaxRetries = 3
const DEFAULT_TIMEOUT = 30 * time.Second

Interfaces: PascalCase, suffix -er si applicable

type UserRepository interface { }
type Logger interface { }
type Validator interface { }

11.3 Rust

Modules: snake_case

mod websocket;
mod message_store;

Structs/Enums: PascalCase

struct Message { }
enum MessageType { }

Functions: snake_case

fn send_message() { }
fn validate_token() { }

Constants: SCREAMING_SNAKE_CASE

const MAX_MESSAGE_SIZE: usize = 1024;

Traits: PascalCase

trait MessageStore { }
trait Authenticator { }

11.4 TypeScript/React

Files: PascalCase (components), camelCase (utilities)

LoginForm.tsx
Button.tsx
utils.ts
api.ts

Components: PascalCase

function LoginForm() { }
const Button: React.FC = () => { }

Functions: camelCase

function fetchUsers() { }
const handleSubmit = () => { }

Types/Interfaces: PascalCase

interface User { }
type CreateUserInput = { }

Enums: PascalCase

enum UserRole { }

Constants: SCREAMING_SNAKE_CASE

const API_BASE_URL = "https://api.veza.app";

11.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

{
  "userId": "123",
  "firstName": "John",
  "createdAt": "2025-11-02T10:30:00Z"
}

11.6 Events

Event Names: {domain}.{entity}.{action}.{version}

auth.user.registered.v1
marketplace.order.paid.v1
chat.message.sent.v1

Event Fields: camelCase (JSON)

{
  "eventId": "evt-123",
  "eventType": "auth.user.registered.v1",
  "aggregateId": "user-123"
}

12. 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 (Go)
│   ├── cmd/
│   │   └── chat/
│   │       └── main.go
│   ├── internal/
│   │   ├── domain/
│   │   ├── application/
│   │   ├── infrastructure/
│   │   └── interfaces/
│   ├── migrations/
│   ├── go.mod
│   └── Dockerfile
├── veza-stream-server/             # ⭐ Stream Server (Rust)
│   ├── src/
│   │   ├── main.rs
│   │   ├── audio/
│   │   └── streaming/
│   ├── Cargo.toml
│   └── Dockerfile
├── docker-compose.yml              # Development environment
├── docker-compose.production.yml   # Production environment
├── Makefile                        # Build automation
├── .env.example                    # Environment variables template
└── README.md                       # Project README

13. EXCLUSIONS ET RAISONS ÉTHIQUES

Ce qui suit a été explicitement exclu de l'architecture Veza. Chaque exclusion est une décision architecturale permanente, pas un report.

13.1 IA / Machine Learning

Composant exclu Raison
Mastering automatique (IA) L'artiste maîtrise son processus créatif. Un mastering IA impose une esthétique normalisée.
Séparation de stems (IA) Nécessite des modèles ML opaques. Risque de faciliter le plagiat non consenti.
Détection de genre automatique Les artistes déclarent eux-mêmes leurs genres. La classification automatique impose des catégories réductrices.
Recommandations ML Les algorithmes de recommandation ML créent des bulles de filtre et optimisent l'engagement, pas la découverte.
Content ID (fingerprinting ML) Systèmes opaques avec un historique de faux positifs nuisibles aux artistes indépendants.
Transcription automatique Dépendance à des modèles propriétaires (Whisper, etc.) sans garantie de précision.

13.2 Blockchain / Web3 / Crypto

Composant exclu Raison
NFT / tokens Spéculation financière incompatible avec le soutien aux créateurs. Impact environnemental.
Smart contracts Complexité inutile pour la gestion de droits. Le droit d'auteur existe déjà.
IPFS / stockage décentralisé Performance insuffisante pour le streaming audio. Complexité opérationnelle disproportionnée.
Crypto-paiements Volatilité, blanchiment, pas de protection consommateur. Les artistes ont besoin de revenus stables.
DAO / gouvernance blockchain Les décisions de gouvernance sont prises par la communauté via des mécanismes classiques (votes, forums).

13.3 Gamification addictive

Composant exclu Raison
Système XP / points Transforme l'écoute musicale en compétition. Optimise le temps passé, pas la satisfaction.
Niveaux utilisateur Crée une hiérarchie artificielle entre utilisateurs.
Leaderboards / classements Encourage la quantité au détriment de la qualité. Favorise les comportements de farming.
Streaks / séries Mécanisme de rétention manipulatoire (FOMO).
Badges de complétion Acceptable uniquement pour les parcours éducatifs (sans pression sociale).

13.4 Autres exclusions techniques

Composant exclu Raison
WebRTC Code mort, hors scope définitif. Le streaming audio fonctionne via HLS.
gRPC inter-services Surengineering pour 3 services. REST est suffisant et plus simple à débugger.
Kafka RabbitMQ est suffisant pour le volume actuel et projeté.
DRM Incompatible avec la philosophie open source et la confiance envers les artistes.

✅ 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 (18 domaines, pas d'IA/Web3/Gamification)
  • Les patterns architecturaux sont explicites (Clean, CQRS, Event-Driven)
  • Les décisions architecturales (ADR) sont documentées avec justifications
  • Les principes éthiques sont documentés comme contraintes architecturales
  • Les exclusions sont documentées avec leurs raisons

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
2.0.0 2026-03-04 Révision éthique - Suppression IA/ML, Web3/NFT, gamification addictive. Chat Server migré de Rust à Go. gRPC remplacé par REST. Stripe remplacé par Hyperswitch. Ajout principes d'architecture éthique, découverte éthique, exclusions documentées. JWT HS256 → RS256.

⚠️ AVERTISSEMENT

CE DOCUMENT EST LA SOURCE DE VÉRITÉ ARCHITECTURALE

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. Vérification éthique : confirmer que la modification respecte les principes d'architecture éthique (section 1)
  3. Review : review par l'équipe technique
  4. Approval : approbation requise
  5. Documentation : mettre à jour ADR avec nouvelle décision
  6. Communication : communiquer à toute l'équipe
  7. 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 (RGPD, etc.)
  • Renforcement des principes éthiques

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"
  • Réintroduction d'IA/ML, blockchain, ou gamification addictive

Alignement éthique : ce document intègre les principes éthiques comme contraintes architecturales permanentes. Les exclusions documentées en section 13 ne sont pas des reports mais des décisions définitives. Toute proposition de réintroduction d'un composant exclu est rejetée par défaut.

Document créé par : Architecture Team
Date de création : 2025-11-02
Dernière révision : 2026-03-04 (révision éthique v2.0.0)
Propriétaire : CTO / Lead Architect

Statut : ✅ RÉVISÉ ET VERROUILLÉ — ALIGNÉ ÉTHIQUE