Stack & Structure (Server)

1. Philosophie architecturale

Le découpage suit une architecture en couches, organisée par modules métier. Le domaine ne connaît ni Gin, ni Redis, ni GORM ; l’infrastructure implémente les interfaces définies par les modules.

CQRS allégé

• Command : valide l’intention, applique les règles métier, écrit en PostgreSQL et invalide le cache concerné.
• Query : tente une lecture Redis, puis lit PostgreSQL en cas de miss et hydrate le cache.
• Transport : Gin traduit HTTP en commandes/requêtes et transforme les résultats en réponses uniformes.
• Temps réel : les événements peuvent être diffusés via WebSocket/SSE après une mutation ; cette diffusion ne remplace pas la transaction PostgreSQL.

On garde	On évite
Une seule base PostgreSQL comme source de vérité	Deux modèles de données divergents ou une base de lecture séparée
Des interfaces de repository par module	Un repository générique qui contourne le domaine
Redis en cache de lecture avec invalidation à l’écriture	Redis comme source de vérité ou comme file de messages
Des handlers courts et testables	La logique métier dans les handlers Gin
Des transactions GORM explicites quand plusieurs écritures sont liées	L’event sourcing, les projections asynchrones et le message broker prématurés
gRPC pour les agents et REST pour le front	Un couplage direct du domaine à un protocole de transport

2. Stack technique

Besoin	Choix
Langage / HTTP	Go, Gin
ORM PostgreSQL	GORM (gorm.io/gorm)
Driver PostgreSQL	gorm.io/driver/postgres
Base de données	PostgreSQL
Cache	Redis avec github.com/redis/go-redis/v9
Migrations	gorm.AutoMigrate en développement ; golang-migrate en production
Validation	go-playground/validator/v10
Logs	zerolog
Configuration	viper
Authentification	JWT signé, rotation/expiration des clés selon la politique d’exploitation
Agents	gRPC et Protocol Buffers
Documentation	swaggo/swag et gin-swagger
Temps réel	WebSocket ou Server-Sent Events (SSE)
Tests d’intégration	testcontainers-go avec PostgreSQL et Redis

3. Structure du projet

berth-api/
├── cmd/
│   └── api/
│       └── main.go
├── internal/
│   ├── config/
│   │   └── config.go
│   ├── server/
│   │   ├── server.go
│   │   └── routes.go
│   ├── database/
│   │   ├── postgres.go       # gorm.Open + *sql.DB + pool
│   │   └── redis.go
│   ├── domain/
│   │   ├── application.go
│   │   ├── agent.go
│   │   ├── deployment.go
│   │   └── user.go
│   ├── modules/
│   │   ├── application/
│   │   │   ├── command/
│   │   │   │   └── restart.go
│   │   │   ├── query/
│   │   │   │   ├── get.go
│   │   │   │   └── list.go
│   │   │   ├── repository.go
│   │   │   ├── cache.go
│   │   │   └── handler.go
│   │   ├── agent/
│   │   │   ├── command/
│   │   │   ├── query/
│   │   │   ├── repository.go
│   │   │   ├── cache.go
│   │   │   └── handler.go
│   │   ├── deployment/
│   │   │   ├── command/
│   │   │   ├── query/
│   │   │   ├── repository.go
│   │   │   ├── cache.go
│   │   │   └── handler.go
│   │   └── auth/
│   │       ├── command/
│   │       ├── query/
│   │       ├── repository.go
│   │       ├── cache.go
│   │       └── handler.go
│   ├── middleware/
│   │   ├── auth.go
│   │   ├── request_id.go
│   │   └── recovery.go
│   ├── grpc/
│   │   ├── server.go
│   │   └── proto/
│   └── pkg/
│       ├── apperror/
│       │   └── error.go
│       ├── response/
│       │   └── response.go
│       └── validator/
│           └── validator.go
├── pkg/
│   └── logger/
│       └── logger.go
├── migrations/               # versions SQL exécutées par golang-migrate en prod
├── Dockerfile
├── docker-compose.yml
├── .env.example
├── go.mod
└── go.sum