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

46 KiB
Raw Blame History

ORIGIN_TECHNICAL_STACK.md

📋 RÉSUMÉ EXÉCUTIF

Ce document définit la stack technique de la plateforme Veza, une plateforme audio open source pour musiciens indépendants. Les choix technologiques sont guidés par trois contraintes architecturales : performance, souveraineté des données, et respect éthique des utilisateurs. Toute technologie reposant sur l'extraction comportementale (ML/IA), la spéculation financière (blockchain/NFT), ou la manipulation attentionnelle (gamification addictive) est exclue par principe.

Les versions sont verrouillées, les alternatives rejetées documentées, et la stratégie de mise à jour définie (LTS only).

🎯 OBJECTIFS

Objectif Principal

Définir une stack technique stable, éthique et maintenable pour une plateforme audio qui sert les musiciens sans les exploiter.

Objectifs Secondaires

  • Éliminer les débats technologiques récurrents
  • Assurer la compatibilité entre composants
  • Faciliter l'onboarding des nouveaux développeurs
  • Minimiser la dette technique liée aux upgrades
  • Garantir le support long terme (LTS)
  • Documenter les exclusions éthiques comme contraintes architecturales

📖 TABLE DES MATIÈRES

  1. Vue d'Ensemble
  2. Backend Stack
  3. Rust Stream Server Stack
  4. Frontend Stack
  5. Mobile Stack
  6. Desktop Stack
  7. Infrastructure Stack
  8. Database Stack
  9. Message Queue & Cache
  10. Services Externes
  11. DevOps & CI/CD Stack
  12. Monitoring & Observabilité
  13. Sécurité Stack
  14. Development Tools
  15. Stratégie de Mise à Jour
  16. Matrice de Compatibilité
  17. Stack de Découverte Musicale Éthique
  18. Exclusions et Raisons Éthiques

🔒 RÈGLES IMMUABLES

  1. Versions EXACTES verrouillées - pas de ^ ou ~ en production
  2. LTS ONLY - uniquement versions Long Term Support
  3. NO experimental features - pas de beta, alpha, RC
  4. NO breaking changes - pas d'upgrade majeur pendant phases actives
  5. Security patches ONLY - exceptions pour CVE critiques uniquement
  6. One stack per domain - pas de mix Go/Node pour backend, etc.
  7. Proven technologies - minimum 2 ans d'existence en production
  8. Active community - > 1000 GitHub stars, documentation complète
  9. Commercial support available - option support payant si nécessaire
  10. Docker compatibility - toutes technologies containerisables

1. VUE D'ENSEMBLE

1.1 Stack Decision Matrix

Domain Technology Version Justification Support Until
Backend API Go 1.24 Performance, simplicité, concurrence Feb 2028
Chat Server Go 1.24 Même stack que l'API, WebSocket natif Feb 2028
Stream Server Rust stable HLS/FFmpeg, zero-cost abstractions Rolling
Frontend Web React 18.2.0 Écosystème, Concurrent Mode Ongoing
Mobile React Native 0.73.x Code sharing, performance native Rolling
Desktop Electron 28.x Cross-platform, web stack reuse Rolling
Database PostgreSQL 16 ACID, relations, performance Nov 2028
Cache Redis 7.x In-memory, pub/sub Jul 2026
Message Queue RabbitMQ 3.x Mature, routing flexible Rolling
Search Elasticsearch 8.x Recherche musicale déterministe Rolling
Payment Hyperswitch latest Open source, multi-provider Rolling
Container Docker 24.x Standard industrie Rolling
Load Balancer HAProxy 2.x Blue-green deployments Rolling

1.2 Language Versions

Go:         1.24      (Released: Feb 2025, Support: Feb 2028)
Rust:       stable    (Rolling releases, stable channel, stream server only)
TypeScript: 5.3.3     (Latest stable)
Node.js:    20.11.0   (LTS - Iron, Support: Apr 2026)

Fichiers de version à créer

  • rust-toolchain.toml : fixer le channel Rust stable pour le stream server
  • .nvmrc : fixer la version Node.js pour le frontend

1.3 Architecture Stack Summary

┌──────────────────────────────────────────────────────────┐
│                     CLIENT TIER                          │
│  React 18 (Web) | React Native 0.73 (Mobile) | Electron │
└──────────────────────────────────────────────────────────┘
                            │
                            │ HTTPS/WSS
                            ↓
┌──────────────────────────────────────────────────────────┐
│                   LOAD BALANCER TIER                     │
│            HAProxy 2.x (Blue-Green Deployments)          │
└──────────────────────────────────────────────────────────┘
                            │
                            ↓
┌──────────────────────────────────────────────────────────┐
│                   APPLICATION TIER                       │
│  Go API 1.24 | Go Chat | Rust Stream (HLS) | Workers   │
└──────────────────────────────────────────────────────────┘
                            │
                ┌───────────┼───────────┐
                ↓           ↓           ↓
┌────────────────────┐ ┌─────────┐ ┌────────────────────┐
│    DATA TIER       │ │ SEARCH  │ │   MESSAGE TIER     │
│ PostgreSQL 16      │ │ Elastic │ │ RabbitMQ 3         │
│ Redis 7            │ │ search  │ │ (Event Bus)        │
│ S3 (Object Storage)│ │ 8.x    │ └────────────────────┘
└────────────────────┘ └─────────┘

2. BACKEND STACK

2.1 Core

Language: Go 1.24
Release: February 2025
Support: Until February 2028
Official Site: https://go.dev/

Le backend Go couvre l'API REST et le Chat Server (WebSocket). Le Chat Server était initialement prévu en Rust mais reste en Go pour maintenir une stack backend unifiée.

Justification

  • Performance: Compiled, garbage collected, excellent concurrency
  • Simplicité: Simple syntax, fast compilation, single binary
  • Concurrence: Goroutines et channels natifs
  • Tooling: Built-in testing, formatting, documentation
  • Écosystème: Mature, nombreuses libraries stables
  • Maintenance: Backward compatibility garantie

Alternatives Rejetées

  • Node.js: Single-threaded, performance inférieure, callback hell
  • Python: GIL limitations, performance médiocre pour APIs haute charge
  • Java: Trop verbeux, startup lent, memory footprint élevé
  • C++: Trop complexe, unsafe, temps de développement long

2.2 Web Framework

Framework: Gin Web Framework
Version: 1.9.1
Repo: https://github.com/gin-gonic/gin
Stars: 74k+

// go.mod
require github.com/gin-gonic/gin v1.9.1

Features

  • HTTP/2 support
  • Middleware chaining
  • JSON validation
  • Error management
  • Performance: 40k req/s (benchmarks)

Alternatives Rejetées

  • Echo: Moins mature, communauté plus petite
  • Fiber: Basé sur Fasthttp (non standard library)
  • Chi: Minimaliste mais manque features (validation, etc.)
  • Standard lib: Trop bas niveau, verbose

2.3 ORM & Database

ORM: GORM
Version: 1.25.5
Repo: https://github.com/go-gorm/gorm
Driver: gorm.io/driver/postgres v1.5.4

require (
    gorm.io/gorm v1.25.5
    gorm.io/driver/postgres v1.5.4
)

Features

  • Associations (has one, has many, many to many)
  • Hooks (before/after create, update, delete)
  • Transactions
  • Migrations
  • Soft delete
  • Preloading

Alternatives Rejetées

  • SQLBoiler: Type-safe mais code generation complexe
  • Ent: Facebook-backed mais trop opinionated
  • Database/sql: Trop bas niveau, beaucoup de boilerplate

2.4 JWT & Authentication

Library: golang-jwt/jwt
Version: v5.3.0
Repo: https://github.com/golang-jwt/jwt

require github.com/golang-jwt/jwt/v5 v5.3.0

Features

  • RS256, HS256, ES256 algorithms
  • Claims validation
  • Token parsing et verification
  • Keyfunc support

Migration en cours

  • HS256 → RS256 : migration planifiée pour séparer les clés de signature (privée) et de vérification (publique), nécessaire pour la communication inter-services sécurisée.

2.5 Validation

Library: go-playground/validator
Version: v10.16.0
Repo: https://github.com/go-playground/validator

require github.com/go-playground/validator/v10 v10.16.0

Features

  • Struct validation
  • Custom validators
  • Cross-field validation
  • Internationalization
  • 150+ built-in validators

2.6 Configuration

Library: spf13/viper
Version: v1.18.2
Repo: https://github.com/spf13/viper

require github.com/spf13/viper v1.18.2

Features

  • Multiple formats (JSON, YAML, ENV, TOML)
  • Environment variables
  • Remote config (Consul, etcd)
  • Hot reload
  • Default values

Migration prévue : dotenv → dotenvy

Le package github.com/joho/godotenv est en maintenance minimale. Migration vers github.com/joeshaw/dotenvy ou intégration directe via Viper à planifier.

2.7 Logging

Library: uber-go/zap
Version: v1.27.0
Repo: https://github.com/uber-go/zap

require go.uber.org/zap v1.27.0

Features

  • Structured logging
  • High performance (zero allocation)
  • Leveled logging
  • JSON output
  • Sampling

Alternatives Rejetées

  • Logrus: Plus lent que zap
  • Zerolog: Moins de features, communauté plus petite
  • Standard log: Pas de structured logging

2.8 UUID Generation

Library: google/uuid
Version: v1.6.0

require github.com/google/uuid v1.6.0

2.9 HTTP Client

Library: Go standard library net/http
Version: Included in Go 1.23

For external APIs with retry/circuit breaker:

Library: hashicorp/go-retryablehttp
Version: v0.7.5

2.10 Testing

Frameworks:

  • Standard: testing package (built-in)
  • Assertions: testify/assert v1.9.0
  • Mocking: golang/mock v1.6.0
require (
    github.com/stretchr/testify v1.9.0
    github.com/golang/mock v1.6.0
)

2.11 Complete Backend go.mod

module veza-backend-api

go 1.24

require (
    // Web Framework
    github.com/gin-gonic/gin v1.9.1
    
    // Database
    gorm.io/gorm v1.25.5
    gorm.io/driver/postgres v1.5.4
    github.com/lib/pq v1.10.9
    
    // Cache & Session
    github.com/redis/go-redis/v9 v9.16.0
    
    // Message Queue
    github.com/rabbitmq/amqp091-go v1.9.0
    
    // Authentication & Security
    github.com/golang-jwt/jwt/v5 v5.3.0
    golang.org/x/crypto v0.41.0
    
    // Validation
    github.com/go-playground/validator/v10 v10.16.0
    
    // Configuration
    github.com/spf13/viper v1.18.2
    github.com/joho/godotenv v1.5.1    // TODO: migrer vers dotenvy
    
    // Logging
    go.uber.org/zap v1.27.0
    
    // Utilities
    github.com/google/uuid v1.6.0
    
    // External Services
    github.com/aws/aws-sdk-go-v2 v1.24.0          // S3
    github.com/sendgrid/sendgrid-go v3.14.0       // Email
    
    // Payments (open source, multi-provider)
    // Hyperswitch — appel via API REST, pas de SDK Go natif
    
    // Monitoring
    github.com/prometheus/client_golang v1.18.0
    
    // gRPC
    google.golang.org/grpc v1.59.0
    google.golang.org/protobuf v1.30.0
    
    // Testing
    github.com/stretchr/testify v1.9.0
    github.com/golang/mock v1.6.0
)

3. RUST STREAM SERVER STACK

Périmètre : Rust est utilisé uniquement pour le Stream Server (HLS/FFmpeg). Il n'est pas prévu d'étendre Rust à d'autres services. Le Chat Server, initialement prévu en Rust, est implémenté en Go (voir section 2).

3.1 Core

Language: Rust stable
Channel: Stable (fixé via rust-toolchain.toml)
Edition: 2021
Official Site: https://www.rust-lang.org/

Justification pour le streaming

  • Sécurité mémoire: Ownership model, zero-cost abstractions
  • Performance: Proche du C/C++, sans garbage collection
  • Latence prévisible: Pas de GC pauses, critique pour le streaming audio
  • Intégration FFmpeg: Bindings natifs performants pour le transcodage HLS

Alternatives Rejetées

  • C++: Pas de sécurité mémoire, complexité
  • Go: Garbage collection (latence imprévisible pour streaming temps réel)

Fichier requis : rust-toolchain.toml

[toolchain]
channel = "stable"

3.2 Async Runtime

Framework: Tokio
Version: 1.35.x
Repo: https://github.com/tokio-rs/tokio

[dependencies]
tokio = { version = "1.35", features = ["full", "tracing"] }

Features

  • Multi-threaded async runtime
  • Work-stealing scheduler
  • I/O drivers (TCP, UDP, Unix sockets)
  • Timers and timeouts
  • Signal handling

Alternatives Rejetées

  • async-std: Moins de fonctionnalités, communauté plus petite
  • smol: Trop minimaliste
  • Actix: Runtime spécifique à actix-web

3.3 Web Framework

Framework: Axum
Version: 0.7.x
Repo: https://github.com/tokio-rs/axum

axum = { version = "0.7", features = ["macros"] }

Features

  • Built on tower (middleware)
  • Type-safe routing
  • Low overhead
  • Adapté au streaming HLS

Alternatives Rejetées

  • Actix-web: Moins idiomatique, unsafe en interne
  • Rocket: Compilation lente, async moins mature
  • Warp: Complexité types, courbe apprentissage

3.4 Database (Async)

ORM: SQLx
Version: 0.7.x

sqlx = { 
    version = "0.7", 
    features = [
        "postgres",
        "runtime-tokio-native-tls",
        "chrono",
        "uuid",
        "json",
        "migrate",
        "macros"
    ] 
}

Features

  • Compile-time checked queries
  • Async/await native
  • Migrations
  • Type-safe
  • Connection pooling

Alternatives Rejetées

  • Diesel: Sync only, pas d'async
  • SeaORM: Moins mature
  • tokio-postgres: Trop bas niveau

3.5 Serialization

Libraries:

  • JSON: serde_json 1.0
  • MessagePack: rmp-serde 1.1
  • TOML: toml 0.9
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
rmp-serde = "1.1"
toml = "0.9"

3.6 Logging & Tracing

Framework: tracing
Version: 0.1.x

tracing = "0.1"
tracing-subscriber = { 
    version = "0.3", 
    features = ["env-filter", "json", "chrono"] 
}
tracing-appender = "0.2"

3.7 Error Handling

Libraries:

  • Macros: thiserror 2.0
  • Context: anyhow 1.0
thiserror = "2.0"
anyhow = "1.0"

3.8 Concurrency

Libraries:

  • HashMap concurrent: dashmap 6.1
  • Mutex high-perf: parking_lot 0.12
  • Channels: flume 0.11
dashmap = "6.1"
parking_lot = "0.12"
flume = "0.11"

3.9 Streaming HLS & Audio

Approche : Le stream server utilise FFmpeg comme outil externe pour le transcodage et la segmentation HLS. Les libraries Rust gèrent le pilotage de FFmpeg et la lecture des formats audio.

Libraries:

  • Codec: symphonia 0.5 (lecture multi-format)
  • FFmpeg : appelé via std::process::Command ou bindings
symphonia = { version = "0.5", features = ["all"] }

FFmpeg est une dépendance système, pas une crate Rust. Il doit être installé dans l'image Docker du stream server.

3.10 Complete Rust Cargo.toml (Stream Server)

[package]
name = "stream_server"
version = "0.2.0"
edition = "2021"

[dependencies]
# Runtime
tokio = { version = "1.35", features = ["full", "tracing"] }
axum = { version = "0.7", features = ["macros"] }

# Database & Cache
sqlx = { version = "0.7", features = ["postgres", "runtime-tokio-native-tls", "uuid", "chrono", "json", "migrate", "macros"] }
redis = { version = "0.25", features = ["tokio-comp", "connection-manager"] }

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

# Audio
symphonia = { version = "0.5", features = ["all"] }

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

# Concurrency
dashmap = "6.1"
parking_lot = "0.12"

# Utilities
uuid = { version = "1.6", features = ["v4", "serde"] }
chrono = { version = "0.4", features = ["serde"] }
anyhow = "1.0"
thiserror = "2.0"

4. FRONTEND STACK

4.1 Core

Framework: React
Version: 18.2.0
Official Site: https://react.dev/

Justification

  • Écosystème: Largest ecosystem, nombreuses libraries
  • Performance: Concurrent Mode, Suspense
  • Communauté: Énorme, documentation complète
  • Hiring: Facile de recruter des devs React
  • Stability: Mature, Facebook-backed

Alternatives Rejetées

  • Vue.js: Écosystème plus petit, moins de ressources
  • Svelte: Trop récent, écosystème limité
  • Angular: Trop lourd, courbe apprentissage raide
  • Solid.js: Trop nouveau, risqué

4.2 TypeScript

Language: TypeScript
Version: 5.3.3
Official Site: https://www.typescriptlang.org/

{
  "devDependencies": {
    "typescript": "5.3.3"
  }
}

Configuration (tsconfig.json)

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "jsx": "react-jsx",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "allowImportingTsExtensions": true,
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "skipLibCheck": true
  }
}

4.3 Build Tool

Tool: Vite
Version: 7.1.5
Official Site: https://vitejs.dev/

{
  "devDependencies": {
    "vite": "7.1.5",
    "@vitejs/plugin-react": "4.2.1"
  }
}

Justification

  • Performance: ESBuild-based, ultra-fast
  • HMR: Hot Module Replacement instantané
  • DX: Developer experience excellent
  • Modern: ESM native, pas de legacy

Alternatives Rejetées

  • Webpack: Lent, configuration complexe
  • Parcel: Moins performant que Vite
  • Rollup: Moins de features DX

4.4 Routing

Library: React Router
Version: 6.22.0

{
  "dependencies": {
    "react-router-dom": "6.22.0"
  }
}

4.5 State Management

Library: Zustand
Version: 4.5.0

{
  "dependencies": {
    "zustand": "4.5.0"
  }
}

Justification

  • Simplicité: API minimale, pas de boilerplate
  • Performance: Re-renders optimisés
  • TypeScript: Excellent support
  • Size: 1KB minified

Alternatives Rejetées

  • Redux: Trop de boilerplate
  • MobX: Plus complexe, moins populaire
  • Recoil: Facebook expérimental, moins stable
  • Jotai: Plus récent, écosystème limité

4.6 Data Fetching

Library: TanStack Query (React Query)
Version: 5.17.0

{
  "dependencies": {
    "@tanstack/react-query": "5.17.0"
  }
}

Features

  • Caching automatique
  • Background refetching
  • Optimistic updates
  • Pagination
  • Infinite scroll
  • Devtools

4.7 HTTP Client

Library: Axios
Version: 1.6.7

{
  "dependencies": {
    "axios": "1.6.7"
  }
}

Alternatives Rejetées

  • Fetch API: Pas de interceptors, moins de features
  • ky: Moins mature

4.8 Forms

Library: React Hook Form
Version: 7.49.3
Validation: Zod 3.25.76

{
  "dependencies": {
    "react-hook-form": "7.49.3",
    "zod": "3.25.76",
    "@hookform/resolvers": "3.3.4"
  }
}

Features

  • Uncontrolled forms (performance)
  • Minimal re-renders
  • Built-in validation
  • TypeScript support

Alternatives Rejetées

  • Formik: Plus lent, plus de re-renders
  • React Final Form: Moins populaire

4.9 UI Components

Base Library: Radix UI
Versions: Latest stable

{
  "dependencies": {
    "@radix-ui/react-avatar": "1.0.4",
    "@radix-ui/react-dialog": "1.0.5",
    "@radix-ui/react-dropdown-menu": "2.0.6",
    "@radix-ui/react-label": "2.0.2",
    "@radix-ui/react-select": "2.0.0",
    "@radix-ui/react-tabs": "1.0.4",
    "@radix-ui/react-toast": "1.1.5"
  }
}

Justification

  • Unstyled: Total control styling
  • Accessible: WAI-ARIA compliant
  • Composable: Flexible architecture

4.10 Styling

Framework: Tailwind CSS
Version: 4.0.0

{
  "devDependencies": {
    "tailwindcss": "4.0.0",
    "@tailwindcss/postcss": "4.0.0"
  }
}

Utilities:

  • clsx: 2.1.0 (conditional classes)
  • tailwind-merge: 2.2.1 (merge classes)

Alternatives Rejetées

  • CSS Modules: Trop verbeux
  • Styled Components: Runtime overhead
  • Emotion: Moins performant que Tailwind
  • Vanilla CSS: Pas de utility-first

4.11 Icons

Library: Lucide React
Version: 0.321.0

{
  "dependencies": {
    "lucide-react": "0.321.0"
  }
}

4.12 Internationalization

Library: i18next + react-i18next
Versions: i18next 25.5.2, react-i18next 15.7.3

{
  "dependencies": {
    "i18next": "25.5.2",
    "react-i18next": "15.7.3",
    "i18next-browser-languagedetector": "8.2.0"
  }
}

4.13 Testing

Unit Tests: Vitest
Version: 3.2.4

{
  "devDependencies": {
    "vitest": "3.2.4",
    "@testing-library/react": "14.2.1",
    "@testing-library/jest-dom": "6.4.2",
    "@testing-library/user-event": "14.5.2",
    "jsdom": "24.0.0"
  }
}

E2E Tests: Playwright
Version: 1.41.2

{
  "devDependencies": {
    "@playwright/test": "1.41.2"
  }
}

4.14 Code Quality

Linter: ESLint
Version: 9.0.0

{
  "devDependencies": {
    "eslint": "9.0.0",
    "@typescript-eslint/eslint-plugin": "8.0.0",
    "@typescript-eslint/parser": "8.0.0",
    "eslint-plugin-react": "7.37.0",
    "eslint-plugin-react-hooks": "5.0.0",
    "eslint-plugin-jsx-a11y": "6.10.2"
  }
}

Formatter: Prettier
Version: 3.2.5

4.15 Complete package.json

{
  "name": "veza-frontend",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "preview": "vite preview",
    "test": "vitest",
    "test:e2e": "playwright test",
    "lint": "eslint . --ext ts,tsx",
    "format": "prettier --write \"src/**/*.{ts,tsx,js,jsx,json,css,md}\""
  },
  "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",
    "i18next-browser-languagedetector": "8.2.0",
    "lucide-react": "0.321.0",
    "clsx": "2.1.0",
    "tailwind-merge": "2.2.1",
    "@radix-ui/react-avatar": "1.0.4",
    "@radix-ui/react-dialog": "1.0.5",
    "@radix-ui/react-dropdown-menu": "2.0.6",
    "@radix-ui/react-label": "2.0.2",
    "@radix-ui/react-select": "2.0.0",
    "@radix-ui/react-tabs": "1.0.4",
    "@radix-ui/react-toast": "1.1.5"
  },
  "devDependencies": {
    "@vitejs/plugin-react": "4.2.1",
    "typescript": "5.3.3",
    "vite": "7.1.5",
    "tailwindcss": "4.0.0",
    "@tailwindcss/postcss": "4.0.0",
    "eslint": "9.0.0",
    "@typescript-eslint/eslint-plugin": "8.0.0",
    "@typescript-eslint/parser": "8.0.0",
    "eslint-plugin-react": "7.37.0",
    "eslint-plugin-react-hooks": "5.0.0",
    "eslint-plugin-jsx-a11y": "6.10.2",
    "eslint-plugin-react-refresh": "0.4.5",
    "prettier": "3.2.5",
    "vitest": "3.2.4",
    "@testing-library/react": "14.2.1",
    "@testing-library/jest-dom": "6.4.2",
    "@testing-library/user-event": "14.5.2",
    "jsdom": "24.0.0",
    "@playwright/test": "1.41.2",
    "msw": "2.11.2"
  }
}

5. MOBILE STACK

Framework: React Native
Version: 0.73.x (latest stable)

{
  "dependencies": {
    "react": "18.2.0",
    "react-native": "0.73.4"
  }
}

Key Libraries

  • Navigation: @react-navigation/native 6.x
  • Storage: @react-native-async-storage/async-storage 1.x
  • Networking: Same as web (axios)
  • State: Same as web (zustand)

6. DESKTOP STACK

Framework: Electron
Version: 28.x

{
  "devDependencies": {
    "electron": "28.2.0",
    "electron-builder": "24.9.1"
  }
}

Features

  • Reuse React web codebase
  • Native menu, notifications
  • Auto-update (electron-updater)
  • Tray icon support

7. INFRASTRUCTURE STACK

7.1 Containerization

Tool: Docker
Version: 24.0.x
Compose: 2.23.x

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

7.2 Load Balancer & Reverse Proxy

Tool: HAProxy
Version: 2.x
Stratégie de déploiement: Blue-green

image: haproxy:2.9

Features

  • Blue-green deployments (zero-downtime)
  • Health checks
  • SSL termination
  • Connection draining

Justification

HAProxy gère le routage entre environnements blue et green pour les déploiements sans interruption. Configuration statique et prévisible, pas besoin de service discovery dynamique.

Alternatives Rejetées

  • Traefik: Service discovery automatique non nécessaire à cette échelle
  • Envoy: Trop complexe pour nos besoins
  • NGINX: Moins adapté au blue-green natif

8. DATABASE STACK

8.1 Primary Database

Database: PostgreSQL
Version: 16
Support: Until November 2028
Official Site: https://www.postgresql.org/

Justification

  • ACID: Full transactional support
  • Relations: Complex foreign keys, joins
  • Performance: Query optimizer excellent
  • Features: JSON/JSONB, full-text search, partitioning
  • Extensions: PostGIS, pgcrypto, pg_trgm
  • Stability: 30+ years, mature

Alternatives Rejetées

  • MySQL: Moins de features, moins performant
  • MongoDB: Pas ACID, relations difficiles
  • CockroachDB: Trop jeune, complexe
  • Cassandra: Over-engineering, trop complexe

8.2 PostgreSQL Extensions

-- Enabled extensions
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";      -- UUID generation
CREATE EXTENSION IF NOT EXISTS "pgcrypto";       -- Encryption
CREATE EXTENSION IF NOT EXISTS "pg_trgm";        -- Trigram similarity
CREATE EXTENSION IF NOT EXISTS "unaccent";       -- Remove accents
CREATE EXTENSION IF NOT EXISTS "hstore";         -- Key-value store

8.3 Connection Pooling

Tool: PgBouncer
Version: 1.21.x

[pgbouncer]
pool_mode = transaction
max_client_conn = 1000
default_pool_size = 25

8.4 Database Migrations

Backend (Go): GORM Auto-Migrate + SQL files
Stream Server (Rust): SQLx migrations

# GORM (Go API + Chat Server)
db.AutoMigrate(&User{}, &Track{}, &Playlist{})

# SQLx (Stream Server)
sqlx migrate run

9. MESSAGE QUEUE & CACHE

9.1 Cache & Session Store

Tool: Redis
Version: 7.2.x
Support: Until July 2026
Official Site: https://redis.io/

Configuration

  • Mode: Cluster (3 masters, 3 replicas)
  • Persistence: AOF + RDB
  • Eviction: allkeys-lru
# redis.conf
maxmemory 4gb
maxmemory-policy allkeys-lru
save 900 1
save 300 10
save 60 10000
appendonly yes

Alternatives Rejetées

  • Memcached: Moins de features, pas de pub/sub
  • Hazelcast: Trop complexe, Java-centric

9.2 Message Queue

Tool: RabbitMQ
Version: 3.12.x
Support: Until December 2025
Official Site: https://www.rabbitmq.com/

Configuration

  • Exchanges: Topic, Fanout
  • Queues: Durable, auto-delete false
  • Message TTL: 24 hours
  • Dead Letter Exchange: Yes
# rabbitmq.conf
management.tcp.port = 15672
listeners.tcp.default = 5672

Alternatives Rejetées

  • Apache Kafka: Over-engineering, trop complexe pour début
  • AWS SQS: Vendor lock-in
  • NATS: Moins mature pour persistence

9.3 Search Engine

Tool: Elasticsearch
Version: 8.x

image: docker.elastic.co/elasticsearch/elasticsearch:8.11.0

Rôle

Moteur de recherche déterministe pour la découverte musicale (voir section 17). Indexation par tags, genres, artistes. Pas de scoring ML — la pertinence repose sur des critères déclarés par les artistes et des filtres explicites des utilisateurs.

10. SERVICES EXTERNES

10.1 Object Storage

Provider: AWS S3
SDK: aws-sdk-go-v2 v1.24.0 (Go)

require github.com/aws/aws-sdk-go-v2 v1.24.0

Alternative: MinIO (self-hosted, S3-compatible)

10.2 CDN

Provider: CloudFlare
Features:

  • Edge caching
  • DDoS protection
  • Web Application Firewall
  • Analytics

Alternative: AWS CloudFront

10.3 Payments

Provider: Hyperswitch (open source, multi-provider)
Repo: https://github.com/juspay/hyperswitch
Intégration: API REST (pas de SDK Go natif)

Features:

  • Routage multi-processeur de paiement (Stripe, Adyen, etc.)
  • Checkout unifié
  • Webhooks
  • Dashboard open source
  • Pas de vendor lock-in

Justification

Hyperswitch est un orchestrateur de paiements open source. Il permet de router les paiements vers plusieurs processeurs sans dépendance à un fournisseur unique. Aligné avec les principes de souveraineté du projet.

Alternatives Rejetées

  • Stripe direct: Vendor lock-in, commission non-négociable
  • PayPal: UX inférieure, frais élevés

10.4 Email

Provider: SendGrid
SDK: sendgrid-go v3.14.0

require github.com/sendgrid/sendgrid-go v3.14.0

Alternative: AWS SES

10.5 SMS (Optional)

Provider: Twilio
SDK: twilio-go v1.20.0

10.6 Error Tracking

Tool: Sentry
SDK: sentry-go v0.27.0 (Go), @sentry/react 7.x (Frontend)

require github.com/getsentry/sentry-go v0.27.0

{
  "dependencies": {
    "@sentry/react": "7.100.0"
  }
}

11. DEVOPS & CI/CD STACK

11.1 Version Control

Tool: Git
Hosting: GitHub
Workflow: GitHub Flow (feature branches)

11.2 CI/CD

Tool: GitHub Actions
Workflows actifs: 14

# .github/workflows/backend-ci.yml
name: Backend CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-22.04
    services:
      postgres:
        image: postgres:16
      redis:
        image: redis:7
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.24'
      - run: go test ./...

11.3 Infrastructure as Code

Tool: Ansible
Version: 2.15.x

# playbooks/deploy.yml
- hosts: production
  roles:
    - docker
    - postgresql
    - redis
    - backend-api

Future: Terraform (si besoin d'infrastructure multi-serveurs)

11.4 Secret Management

Tool: Environment Variables (.env)
Production: AWS Secrets Manager ou HashiCorp Vault (future)

# .env.example
DATABASE_URL=postgres://...
REDIS_URL=redis://...
JWT_PRIVATE_KEY_PATH=...
JWT_PUBLIC_KEY_PATH=...
HYPERSWITCH_API_KEY=...
HYPERSWITCH_BASE_URL=...

Migration godotenv → dotenvy planifiée (voir section 2.6).

11.5 Container Registry

Registry: GitHub Container Registry (ghcr.io)
Alternative: Docker Hub

12. MONITORING & OBSERVABILITÉ

12.1 Metrics

Tool: Prometheus
Version: 2.48.x

image: prom/prometheus:v2.48.0

Client Libraries:

  • Go: prometheus/client_golang v1.18.0

Le stack de monitoring en production : Prometheus (métriques) + Grafana (visualisation) + Alertmanager (alertes) + Sentry (error tracking).

12.2 Visualization

Tool: Grafana
Version: 10.2.x

image: grafana/grafana:10.2.0

12.3 Logging

Tool: Loki + Promtail
Version: Loki 2.9.x

image: grafana/loki:2.9.0
image: grafana/promtail:2.9.0

12.4 Distributed Tracing

Tool: Jaeger
Version: 1.52.x

image: jaegertracing/all-in-one:1.52

Client Libraries:

  • Go: OpenTelemetry go.opentelemetry.io/otel v1.21.0

12.5 Alerting

Tool: Prometheus Alertmanager
Version: 0.26.x

image: prom/alertmanager:v0.26.0

12.6 Uptime Monitoring

Tool: UptimeRobot (external)
Alternative: BetterUptime, StatusCake

13. SÉCURITÉ STACK

13.1 SSL/TLS

Certificates: Let's Encrypt
Terminaison SSL: HAProxy

13.2 Secrets Management

Development: dotenv files (migration vers dotenvy prévue, voir section 2.6)
Production: AWS Secrets Manager ou HashiCorp Vault (future)

13.3 Vulnerability Scanning

Tools:

  • Go: govulncheck
  • Rust: cargo audit
  • Node.js: npm audit
  • Docker: trivy
# Scan workflows
go run golang.org/x/vuln/cmd/govulncheck ./...
cargo audit
npm audit
trivy image veza/backend-api:latest

13.4 Static Analysis

Tools:

  • Go: golangci-lint 1.55.x
  • Rust: clippy (built-in)
  • TypeScript: ESLint
  • SonarQube: Community Edition (optional)

13.5 Dependency Management

Tools:

  • Go: Dependabot (GitHub)
  • Rust: cargo-outdated
  • Node.js: Dependabot + Renovate

14. DEVELOPMENT TOOLS

14.1 IDEs & Editors

Recommended:

  • VSCode: Latest (with Go, Rust, ESLint extensions)
  • GoLand: 2024.x (JetBrains)
  • RustRover: 2024.x (JetBrains)

14.2 API Testing

Tool: Insomnia
Version: 2023.x
Alternative: Postman

14.3 Database Client

Tool: DBeaver Community
Version: 23.x
Alternative: pgAdmin 4

14.4 Git GUI

Tools:

  • GitKraken (cross-platform)
  • Sourcetree (Windows/Mac)
  • Git CLI (recommended)

15. STRATÉGIE DE MISE À JOUR

15.1 Politique Générale

Type Action Fréquence Approval
Security patches Update immédiat As needed Auto-approved
Minor versions Update quarterly Q1, Q2, Q3, Q4 Tech Lead
Major versions Evaluate, plan migration Yearly CTO + Team
LTS renewals Plan before EOL 6 months before CTO

15.2 Dependency Updates

# Go
go get -u ./...
go mod tidy

# Rust
cargo update

# Node.js
npm update
npm outdated

15.3 Version Pinning

Production: Versions EXACTES verrouillées

// go.mod - EXACT versions
require github.com/gin-gonic/gin v1.9.1  // NOT v1.9 or ^1.9.1

# Cargo.toml - EXACT versions
tokio = "=1.35.0"  # NOT "1.35" or "^1.35"

// package.json - EXACT versions
{
  "dependencies": {
    "react": "18.2.0"  // NOT ^18.2.0 or ~18.2.0
  }
}

15.4 Breaking Changes

Process:

  1. Identification: Automated alerts (Dependabot, Renovate)
  2. Evaluation: Impact analysis, migration effort
  3. RFC: Formal RFC si changement > 2 semaines effort
  4. Planning: Assignation phase (hors critical path)
  5. Migration: Feature branch, tests complets
  6. Rollout: Staging first, puis production

15.5 EOL (End-of-Life) Management

Critical Components EOL Dates:

Component Version EOL Date Action Plan
Go 1.24 Feb 2028 Évaluer 1.25 en Q4 2027
PostgreSQL 16 Nov 2028 Évaluer 17 en Q3 2028
Node.js 20.x Apr 2026 Upgrade to 22 LTS prévu
Redis 7.x Jul 2026 Upgrade to 7.4+ en Q2 2026
RabbitMQ 3.x Rolling Suivre releases stables

Monitoring: Automated tracking avec endoflife.date API

16. MATRICE DE COMPATIBILITÉ

16.1 Inter-Service Compatibility

Component A Version Component B Version Compatible Notes
Go API 1.24 PostgreSQL 16 ✅ Yes lib/pq 1.10.9
Go API 1.24 Redis 7.x ✅ Yes go-redis 9.16.0
Go Chat 1.24 PostgreSQL 16 ✅ Yes GORM
Rust Stream stable PostgreSQL 16 ✅ Yes SQLx 0.7.x
Rust Stream stable Redis 7.x ✅ Yes redis-rs 0.25
Go API 1.24 Hyperswitch latest ✅ Yes API REST
React 18.2 Vite 7.1.5 ✅ Yes @vitejs/plugin-react 4.2.1
Electron 28.x React 18.2 ✅ Yes Electron React Boilerplate

16.2 OS Compatibility

OS Support Notes
Linux Primary Ubuntu 22.04 LTS (production)
macOS Development macOS 13+ (Ventura)
Windows Development Windows 11 + WSL2

16.3 Browser Compatibility

Browser Version Support Notes
Chrome 100+ ✅ Full Recommended
Firefox 100+ ✅ Full
Safari 16+ ✅ Full macOS/iOS
Edge 100+ ✅ Full Chromium-based
Opera 85+ ⚠️ Partial Not officially tested
IE11 N/A ❌ No Deprecated

17. STACK DE DÉCOUVERTE MUSICALE ÉTHIQUE

La découverte musicale sur Veza repose sur des mécanismes déterministes et transparents. Aucun algorithme de recommandation basé sur le machine learning n'est utilisé.

17.1 Principes

  • Pas de ML/IA : aucun modèle de recommandation, aucun profiling comportemental
  • Transparence : l'utilisateur comprend pourquoi un résultat apparaît
  • Contrôle artiste : les métadonnées de découverte sont déclarées par les artistes, pas inférées

17.2 Composants techniques

Composant Technologie Rôle
Recherche Elasticsearch 8.x Full-text search sur titres, artistes, descriptions
Taxonomie PostgreSQL 16 Tags et genres déclarés par les artistes, stockés en base relationnelle
Curation humaine Go API + interface admin Outils pour curateurs : playlists éditoriales, mises en avant manuelles
Filtres utilisateur Frontend React Filtres explicites : genre, instrument, langue, durée, licence

17.3 Recherche Elasticsearch

image: docker.elastic.co/elasticsearch/elasticsearch:8.11.0
  • Index par : titre, artiste, tags, genre, description, langue
  • Scoring basé sur la pertinence textuelle (BM25), pas sur un modèle entraîné
  • Pas de tracking de clics pour pondérer les résultats
  • Autocomplétion et suggestions basées sur les données déclarées

17.4 Curation humaine

Les curateurs disposent d'outils dans l'interface d'administration pour :

  • Créer des playlists éditoriales thématiques
  • Mettre en avant des artistes ou morceaux
  • Organiser des sélections par contexte (nouveautés, géographie, instrument)

Aucune automatisation ML dans le processus de curation. Les décisions éditoriales sont humaines et traçables.

17.5 Ce qui est explicitement exclu

  • Modèles de recommandation (collaborative filtering, content-based filtering)
  • Analyse audio automatique (fingerprinting ML, extraction de features)
  • Scoring de popularité opaque
  • A/B testing sur les recommandations
  • Boucles de rétroaction comportementale (« les gens qui ont écouté X écoutent aussi Y »)

18. EXCLUSIONS ET RAISONS ÉTHIQUES

Les technologies suivantes ont été évaluées et exclues par principe architectural. Ces exclusions ne sont pas provisoires — elles reflètent les valeurs fondamentales du projet.

18.1 Intelligence Artificielle / Machine Learning

Technologie exclue Catégorie Raison de l'exclusion
TensorFlow ML Framework Recommandation algorithmique = manipulation attentionnelle
PyTorch ML Framework Même raison que TensorFlow
Hugging Face Transformers NLP/ML Aucun cas d'usage NLP qui ne puisse être résolu par Elasticsearch
librosa Analyse audio ML Extraction de features audio = profiling du contenu sans consentement artiste
essentia Analyse audio ML Même raison que librosa
scikit-learn ML classique Pas de modèle prédictif dans une plateforme éthique
ONNX Runtime Inférence ML Pas de modèle à exécuter

Principe : La découverte musicale doit être un choix conscient de l'utilisateur, pas le résultat d'un algorithme optimisant le temps d'écoute.

18.2 Blockchain / Web3 / NFT / Crypto

Technologie exclue Catégorie Raison de l'exclusion
Ethereum / Solidity Smart contracts Spéculation financière incompatible avec le soutien aux musiciens
IPFS Stockage décentralisé Complexité sans bénéfice réel — S3/MinIO suffit
Web3.js / ethers.js Blockchain SDK Pas de blockchain = pas de SDK blockchain
Metamask / Wallets Wallet crypto Pas de tokens, pas de NFT
Polygon / L2 Scaling blockchain Pas de blockchain à scaler

Principe : Les musiciens sont payés en monnaie réelle via des processeurs de paiement réels (Hyperswitch). La spéculation sur des tokens n'aide pas les artistes indépendants.

18.3 Gamification Addictive

Mécanisme exclu Raison de l'exclusion
Streaks / séries consécutives Crée une obligation artificielle, pas un engagement réel
Points / XP / niveaux Transforme l'écoute musicale en jeu, détourne de la musique
Classements compétitifs Met les artistes en compétition sur des métriques qui ne reflètent pas la qualité
Badges de complétion Encourage la consommation quantitative au détriment de l'écoute attentive
Notifications push de rétention Manipulation attentionnelle, dark pattern

Principe : L'engagement doit venir de la qualité de la musique et de l'expérience, pas de mécanismes psychologiques exploitant les biais cognitifs.

18.4 Règle générale

Toute technologie dont le but principal est d'augmenter le temps passé sur la plateforme au détriment du choix conscient de l'utilisateur est exclue. Cette règle s'applique aux choix futurs comme aux choix actuels.

✅ CHECKLIST DE VALIDATION

Backend Stack

  • Go 1.24 installed
  • All go.mod dependencies locked exact versions
  • PostgreSQL 16 accessible
  • Redis 7.x accessible
  • RabbitMQ 3.x accessible
  • S3-compatible storage configured
  • Hyperswitch instance configured
  • SendGrid API key configured
  • JWT RS256 keys generated (migration depuis HS256)

Rust Stream Server

  • Rust stable installed (via rust-toolchain.toml)
  • All Cargo.toml dependencies locked
  • FFmpeg installé dans l'image Docker
  • SQLx CLI installed
  • Database migrations tested
  • Stream server compiles et sert du HLS

Frontend Stack

  • Node.js 20.11 LTS installed (via .nvmrc)
  • All package.json dependencies exact versions
  • TypeScript 5.3.3
  • Vite build successful
  • Tests passing (Vitest)
  • E2E tests passing (Playwright)

Infrastructure

  • Docker 24.x installed
  • Docker Compose 2.23.x installed
  • HAProxy configured (blue-green)
  • Prometheus + Grafana + Alertmanager accessible
  • Sentry configured
  • Elasticsearch 8.x accessible

📊 MÉTRIQUES DE SUCCÈS

Stability

  • Breaking changes: 0 per quarter (except security)
  • Build failures: < 1% of builds
  • Dependency conflicts: 0
  • Security vulnerabilities: 0 critical, < 5 high

Performance

  • Build time backend: < 2 minutes
  • Build time frontend: < 1 minute
  • Docker image size backend: < 50MB
  • Docker image size frontend: < 100MB
  • Dependencies install time: < 5 minutes

Maintenance

  • Outdated dependencies: < 10%
  • EOL components: 0
  • Update cycles: Quarterly
  • Documentation coverage: 100% for stack changes

🔄 HISTORIQUE DES VERSIONS

Version Date Changements
1.0.0 2025-11-02 Version initiale — stack technique verrouillée
2.0.0 2026-03-04 Révision éthique : suppression ML/IA, blockchain/NFT, gamification addictive. Go 1.24, PostgreSQL 16, Chat Server migré de Rust vers Go, Stripe remplacé par Hyperswitch, Traefik remplacé par HAProxy blue-green, ajout sections découverte musicale éthique et exclusions éthiques, Rust scopé au stream server uniquement

⚠️ AVERTISSEMENT

CE DOCUMENT DÉFINIT DES CONTRAINTES ARCHITECTURALES

La stack technique et les exclusions éthiques définies ici sont des contraintes architecturales, pas des suggestions. Toute modification nécessite :

  1. RFC technique avec justification (security, EOL, performance critique)
  2. Impact analysis complet (migration effort, breaking changes, testing)
  3. Vérification éthique : la technologie proposée ne contrevient-elle pas aux exclusions de la section 18 ?
  4. Migration plan détaillé
  5. Update tous documents ORIGIN impactés

Seules exceptions autorisées:

  • Security patches (CVE critiques)
  • EOL forcé (6 mois avant end-of-life)
  • Impossibilité technique (bug bloquant non-résolu)

Interdictions absolues:

  • Ajout de composants ML/IA, blockchain/NFT, ou gamification addictive
  • Changement de langage principal (Go → Node, etc.)
  • Changement de framework principal (React → Vue, etc.)
  • Extension de Rust au-delà du stream server
  • Ajout stack non-approuvée sans RFC
  • Downgrade de version (sauf rollback urgence)

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

Statut: ✅ APPROUVÉ — v2.0.0