1729 lines
46 KiB
Markdown
1729 lines
46 KiB
Markdown
# 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](#1-vue-densemble)
|
|
2. [Backend Stack](#2-backend-stack)
|
|
3. [Rust Stream Server Stack](#3-rust-stream-server-stack)
|
|
4. [Frontend Stack](#4-frontend-stack)
|
|
5. [Mobile Stack](#5-mobile-stack)
|
|
6. [Desktop Stack](#6-desktop-stack)
|
|
7. [Infrastructure Stack](#7-infrastructure-stack)
|
|
8. [Database Stack](#8-database-stack)
|
|
9. [Message Queue & Cache](#9-message-queue--cache)
|
|
10. [Services Externes](#10-services-externes)
|
|
11. [DevOps & CI/CD Stack](#11-devops--cicd-stack)
|
|
12. [Monitoring & Observabilité](#12-monitoring--observabilité)
|
|
13. [Sécurité Stack](#13-sécurité-stack)
|
|
14. [Development Tools](#14-development-tools)
|
|
15. [Stratégie de Mise à Jour](#15-stratégie-de-mise-à-jour)
|
|
16. [Matrice de Compatibilité](#16-matrice-de-compatibilité)
|
|
17. [Stack de Découverte Musicale Éthique](#17-stack-de-découverte-musicale-éthique)
|
|
18. [Exclusions et Raisons Éthiques](#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
|
|
// 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
|
|
|
|
```go
|
|
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
|
|
|
|
```go
|
|
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
|
|
|
|
```go
|
|
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
|
|
|
|
```go
|
|
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
|
|
|
|
```go
|
|
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
|
|
|
|
```go
|
|
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
|
|
|
|
```go
|
|
require (
|
|
github.com/stretchr/testify v1.9.0
|
|
github.com/golang/mock v1.6.0
|
|
)
|
|
```
|
|
|
|
### 2.11 Complete Backend go.mod
|
|
|
|
```go
|
|
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`
|
|
```toml
|
|
[toolchain]
|
|
channel = "stable"
|
|
```
|
|
|
|
### 3.2 Async Runtime
|
|
|
|
**Framework**: Tokio
|
|
**Version**: 1.35.x
|
|
**Repo**: https://github.com/tokio-rs/tokio
|
|
|
|
```toml
|
|
[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
|
|
|
|
```toml
|
|
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
|
|
|
|
```toml
|
|
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
|
|
|
|
```toml
|
|
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
|
|
|
|
```toml
|
|
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
|
|
|
|
```toml
|
|
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
|
|
|
|
```toml
|
|
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
|
|
|
|
```toml
|
|
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)
|
|
|
|
```toml
|
|
[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/
|
|
|
|
```json
|
|
{
|
|
"devDependencies": {
|
|
"typescript": "5.3.3"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Configuration (tsconfig.json)
|
|
```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/
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```json
|
|
{
|
|
"dependencies": {
|
|
"react-router-dom": "6.22.0"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 4.5 State Management
|
|
|
|
**Library**: Zustand
|
|
**Version**: 4.5.0
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```json
|
|
{
|
|
"dependencies": {
|
|
"lucide-react": "0.321.0"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 4.12 Internationalization
|
|
|
|
**Library**: i18next + react-i18next
|
|
**Versions**: i18next 25.5.2, react-i18next 15.7.3
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```json
|
|
{
|
|
"devDependencies": {
|
|
"@playwright/test": "1.41.2"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 4.14 Code Quality
|
|
|
|
**Linter**: ESLint
|
|
**Version**: 9.0.0
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```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)
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```yaml
|
|
# 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
|
|
|
|
```yaml
|
|
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
|
|
|
|
```sql
|
|
-- 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
|
|
|
|
```ini
|
|
[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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```conf
|
|
# 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
|
|
|
|
```yaml
|
|
# 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
|
|
|
|
```yaml
|
|
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)
|
|
|
|
```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
|
|
|
|
```go
|
|
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)
|
|
|
|
```go
|
|
require github.com/getsentry/sentry-go v0.27.0
|
|
```
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```yaml
|
|
# .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
|
|
|
|
```yaml
|
|
# 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)
|
|
|
|
```bash
|
|
# .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
|
|
|
|
```yaml
|
|
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
|
|
|
|
```yaml
|
|
image: grafana/grafana:10.2.0
|
|
```
|
|
|
|
### 12.3 Logging
|
|
|
|
**Tool**: Loki + Promtail
|
|
**Version**: Loki 2.9.x
|
|
|
|
```yaml
|
|
image: grafana/loki:2.9.0
|
|
image: grafana/promtail:2.9.0
|
|
```
|
|
|
|
### 12.4 Distributed Tracing
|
|
|
|
**Tool**: Jaeger
|
|
**Version**: 1.52.x
|
|
|
|
```yaml
|
|
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
|
|
|
|
```yaml
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
// go.mod - EXACT versions
|
|
require github.com/gin-gonic/gin v1.9.1 // NOT v1.9 or ^1.9.1
|
|
```
|
|
|
|
```toml
|
|
# Cargo.toml - EXACT versions
|
|
tokio = "=1.35.0" # NOT "1.35" or "^1.35"
|
|
```
|
|
|
|
```json
|
|
// 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
|
|
|
|
```yaml
|
|
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**
|
|
|