chore: add CLAUDE.md

chore: remove unused redis
chore: auto test new context in HexagonalArchitectureTest
2026-08-06 19:52:48 +02:00 · 2026-08-06 19:42:32 +02:00 · 2026-08-06 19:33:38 +02:00 · 2026-08-06 19:23:47 +02:00 · 2026-08-06 19:10:32 +02:00 · 2026-08-05 00:43:12 +02:00
24 changed files with 818 additions and 411 deletions
@@ -0,0 +1,133 @@
+# CLAUDE.md — event-demo
+
+Ce fichier donne le contexte du projet pour toute session Claude Code future sur ce dépôt.
+
+## Vue d'ensemble
+
+`event-demo` est un projet démo personnel (Fabrice Lecomte) qui illustre plusieurs patterns
+d'architecture backend :
+
+- Event Sourcing
+- Event-Driven (bus d'événements asynchrone)
+- CQRS (séparation commandes / projections en lecture)
+- Architecture Hexagonale (ports & adapters), un dossier par *bounded context*
+
+Le cas d'usage servant de support est un jeu de cartes façon UNO (créer une partie, rejoindre,
+jouer une carte, piocher, etc.), avec authentification des joueurs.
+
+Dépôts distants configurés : `gitea` (auto-hébergé, git.gogn.synology.me — remote historique)
+et `github` (`flecomte/event-demo`, miroir). Vérifier vers lequel pousser selon le contexte.
+
+## Stack technique
+
+- **Langage** : Kotlin 2.1.21, JDK 21 (toolchain Gradle)
+- **Framework serveur** : Ktor 3.5.1 (Netty), DI via Koin 4.2.1
+- **Sérialisation** : kotlinx.serialization (JSON)
+- **Persistance** :
+  - PostgreSQL (event store, via HikariCP) + migrations Flyway (`migrations/events/`)
+  - RabbitMQ (bus d'événements / bus de commandes, via amqp-client)
+- **Auth** : JWT (ktor-server-auth-jwt), hash de mot de passe via password4j
+- **Infra dev/prod** : Docker Compose (fichiers `docker/docker-compose-{dev,test,prod}.yaml`
+  incluant des « parts » réutilisables dans `docker/parts/`), reverse proxy Træfik
+- **Tests** : Kotest (runner JUnit5), MockK, kotest-extensions-koin, ArchUnit (test d'architecture)
+- **Qualité** : ktlint (`ktlint_official`, standard + experimental activés), reporting checkstyle
+- **CI** : GitHub Actions (`.github/workflows/tests.yml`) — build/cache Gradle, `ktlintCheck`,
+  puis tests exécutés **dans Docker** (`docker compose -f docker/docker-compose-test.yaml run tests`)
+- **API** : documentée en OpenAPI (`resources/openapi/documentation.yaml`)
+
+## Architecture
+
+Un dossier par *bounded context* sous `src/main/kotlin/eventDemo/contexts/<context>/`, chacun
+strictement découpé en 3 couches :
+
+- `domain/` — aucune dépendance vers les autres couches
+- `application/` — ne dépend que de `domain`
+- `infrastructure/` — dépend de `domain` et `application`
+
+Contexts actuels :
+
+- **`auth`** : `User`, création de compte, login JWT, event store dédié (Postgresql),
+  projection utilisateur.
+- **`game`** : cœur du jeu — `Card`, `DrawPile`/`DiscardPile`, `Player`, `GameId`, commandes
+  (`JoinTheGameCommand`, `PlayCardCommand`, `ReadyToPlayCommand`, `TakeCartFromDrawPileCommand`),
+  state machine du jeu via `sealed interface Game` (`GameInit` → `GameCreated` → `GameStarted` →
+  `GameEnded`), notifications, projections (liste de parties), listeners/réactions.
+
+Libs transverses dans `libs/` (indépendantes de tout contexte) :
+
+- `bus/` — abstraction `Bus<E>` avec implémentations in-memory et RabbitMQ (fanout exchange)
+- `command/` — `Command`, `CommandUnicityChecker` (empêche la double exécution d'une commande,
+  cache glissant de 10 min par défaut)
+- `eventSource/` — `Event`, `EventStream` (append/lecture par version, gestion de
+  `VersionConflictException`), `EventStore` in-memory / Postgresql
+- `helpers/`, `serializer/` — utilitaires (conversion de frames WebSocket, sérialiseurs UUID, etc.)
+
+## Patterns notables dans le code
+
+- **Event sourcing** : `Game.loadFromHistory(events)` reconstruit l'état en repliant
+  (`fold`) les événements sur une state machine scellée, en utilisant la syntaxe Kotlin 2.1
+  `when` avec garde `if` (ex. `is GameCreatedEvent if this is GameInit -> applyEvent(event)`).
+- **CQRS** : écriture via les command handlers (`application/command/handlers`), lecture via des
+  projections dédiées (`application/projections`), propagées via le bus RabbitMQ, pas de couplage
+  direct avec l'écriture.
+- **Event-driven** : réactions asynchrones (`ReactionListener`, `EventToNotificationSubscriber`)
+  déclenchées par le bus RabbitMQ (exchange fanout, une queue par abonné).
+- **Exceptions métier** : hiérarchie `GameException` / `IllegalActionException` dans
+  `domain/game/errors`, une exception par règle métier violée (ex.
+  `NeedMorePlayersToStartGameException`, `ItsNotTheTurnException`).
+
+## Commandes utiles
+
+```shell
+./gradlew build            # build complet
+./gradlew test             # tests (JUnit5 via Kotest)
+./gradlew ktlintCheck      # lint
+./gradlew ktlintFormat     # auto-format
+./gradlew buildFatJar      # jar exécutable "all-in-one" (utilisé par le Dockerfile prod)
+
+# Dépendances seules (Postgres, RabbitMQ, Træfik, pgAdmin...) pour lancer l'app en local hors docker
+docker compose -f docker/docker-compose-dev.yaml up -d
+
+# Stack de test façon CI
+docker compose -f docker/docker-compose-test.yaml up -d
+# ou directement (comme en CI) :
+docker compose -f docker/docker-compose-test.yaml run tests
+
+# Stack complète en prod
+docker compose -f docker/docker-compose-prod.yaml -p event-demo up -d
+```
+
+URLs en dev (voir `doc/installation.md`, nécessite Træfik + résolution des `*.traefik.me`) :
+API sur `http://api.traefik.me/`, dashboard
+Træfik, pgAdmin et RabbitMQ management exposés via des sous-domaines `traefik.me`.
+
+## Conventions de code
+
+- ktlint en mode `ktlint_official` + règles `standard` et `experimental` activées
+  (voir `.editorconfig`), indentation **2 espaces**, virgules finales (*trailing commas*)
+  systématiques, wrapping forcé des expressions/signatures multi-lignes.
+- Fins de ligne forcées en **LF** (`.gitattributes`), sauf `gradlew.bat` en CRLF.
+- Code et identifiants en anglais.
+- Style Kotlin idiomatique/fonctionnel : `fold`, `let`, `apply`, `when` exhaustifs, classes/interfaces
+  scellées (`sealed class`/`sealed interface`) pour modéliser états et événements plutôt que des enums
+  avec des champs optionnels.
+
+## Pièges connus / choses à savoir avant de toucher au build ou à la CI
+
+- **MockK/ByteBuddy en Docker** : l'auto-attach dynamique de MockK échoue dans les conteneurs
+  (le handshake SIGQUIT de l'AttachListener JVM time-out). Le `build.gradle.kts` charge donc
+  l'agent `byte-buddy-agent` de façon statique via `-javaagent` pour les tâches `Test`, afin
+  que MockK détecte l'instrumentation déjà présente et saute l'attach dynamique. Ne pas retirer
+  ce bloc sans repenser l'exécution des tests en Docker.
+- **Secret Postgres en CI** : `docker/postgresql.secret` est généré à la volée par le workflow
+  GitHub Actions s'il n'existe pas (`echo -n "changeit" > docker/postgresql.secret`) — normal,
+  pas un fichier à committer.
+- Les tests « officiels » de la CI tournent **dans Docker**, pas directement via `./gradlew test`
+  sur l'hôte — en cas de comportement différent entre local et CI, vérifier d'abord les
+  variables d'environnement/versions du `docker-compose-test.yaml`.
+
+## Historique récent (pour contexte)
+
+Le projet a connu un « Massive refactor to build the V2 » (commit `e2d7942`) : passage d'une
+architecture par couches techniques plates (`adapter/presenter/domain`) à l'organisation actuelle
+par bounded context (`auth`/`game`) avec 3 couches hexagonales chacune.
@@ -2,7 +2,6 @@ Event Demo
 ==========
 - [Installation](./doc/installation.md)
 - [What's the demo for ?](#whats-the-demo-for-)
- [What's in this demo](#whats-in-this-demo)
 - [The stack](#the-stack)
 - [Architecture](./doc/architecture.md)

@@ -18,31 +17,6 @@ of different patterns and architectures.
 - The CQRS pattern.
 - With the Hexagonal architecture.

-
-What's in this demo
-------------------
-
- The **event sourcing** pattern.
- The **event driven** pattern.
- The **CQRS** pattern with **command** and **query**.
- A fully **asynchronous** architecture.Concurently process.
- A **pure Kotlin** implementation of **readmodel**/**projection**.
- A **Redis** implementation of **readmodel**/**projection**.
- A **pure Kotlin** implementation of **Event Store**.
- A **Postgresql** implementation of **Event Store**.
- A **pure Kotlin** implementation of **Event Bus**.
- A **RabbitMQ** implementation of **Event Bus**.
- A **Hexagonal** architecture.
- Use of **Web Sockets**.
- Use of the classic **Rest** route.
- Simple usage of the **JWT**.
- The **Ktor** framework.
- The **Koin** Dependency Injection framework
- Concurrently process.
- Use of coroutines.
- Using **docker compose** for the stack with **traefik**.
- Use of **flyway** to migrate the postgresql schema.
-
 The stack
 ---------

@@ -51,11 +25,11 @@ Language

 Framework
 - Ktor
+  - with Koin for Dependency Injection

 Database
 - Postgresql
  - with Flyway
- Redis
 - RabbitMQ

 Infra
@@ -81,7 +81,6 @@ dependencies {
  implementation("io.github.oshai:kotlin-logging-jvm:${kotlinLoggingVersion.get()}")
  implementation("org.jetbrains.kotlinx:kotlinx-serialization-json-jvm:${kotlinSerializationVersion.get()}")
  implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.6.2")
-  implementation("redis.clients:jedis:5.2.0")
  implementation("org.postgresql:postgresql:42.7.13")
  implementation("com.zaxxer:HikariCP:6.3.0")
  implementation("com.rabbitmq:amqp-client:5.25.0")
@@ -1,11 +0,0 @@
-Architecture
-============
-
-The Workflow
------------
-![Workflow Diagram](./schemas/Workflow.svg)
-
-The business Entities
---------------------
-
-![Entities and Projections Diagram](./schemas/Entities.svg)
@@ -1,67 +0,0 @@
-# Exemple de structure 
-
-Les couches, du plus interne au plus externe
-```
-Domain (le cœur, ne dépend de RIEN d'externe)
-↑
-Application (orchestre le Domain, ne connaît pas l'infra concrète)
-↑
-Infrastructure (WebSocket, DB, event store — dépend de tout le reste)
-```
-
-```
-src/
-└── contexts/
-    ├── auth/
-        └── ... 
-    └── game/
-        ├── domain/                              ← Le cœur métier, zéro dépendance externe
-        │   ├── game/
-        │   │   ├── Game.ts                      ← Aggregate Root
-        │   │   ├── Player.ts                    ← Entity interne
-        │   │   ├── Card.ts                      ← Entity
-        │   │   ├── Color.ts                     ← Value Object
-        │   │   ├── Deck.ts                      ← VO ou petite structure
-        │   │   └── errors/
-        │   │       ├── InvalidMoveError.ts
-        │   │       └── ColorChoiceRequiredError.ts
-        │   └── events/                          ← Events de DOMAINE (internes)
-        │       ├── CardPlayed.ts
-        │       ├── CardDrawn.ts
-        │       ├── TurnPassed.ts
-        │       └── DomainEvent.ts               ← interface/type de base
-        ├── application/                         ← Orchestration, cas d'usage
-        │   ├── commands/                        ← Les Commandes (intentions)
-        │   │   ├── PlayCardCommand.ts
-        │   │   └── DrawCardCommand.ts
-        │   ├── handlers/                        ← Un handler par commande
-        │   │   ├── PlayCardHandler.ts           ← charge l'aggregate, appelle game.playCard(), save
-        │   │   └── DrawCardHandler.ts
-        │   ├── projections/                     ← LA LOGIQUE de construction des projections
-        │   │   ├── GameSummaryProjector.kt      ← écoute les events, met à jour la vue
-        │   │   └── PlayerStatsProjector.kt
-        │   └── ports/                           ← INTERFACES seulement (le "hexagone")
-        │       ├── GameRepository.ts            ← interface, pas d'implémentation
-        │       ├── EventPublisher.ts            ← interface, pas d'implémentation
-        │       └── ProjectionStore.kt           ← interface, où lire/écrire la projection
-        ├── infrastructure/                      ← Tout ce qui est technique/externe
-        │   ├── persistence/
-        │   │   ├── EventStoreGameRepository.ts  ← implémente GameRepository
-        │   │   ├── EventStore.ts
-        │   │   ├── projections/
-        │   │   │   ├── GameSummaryProjectionStore.kt   ← implémentation concrète (DB, table dédiée)
-        │   │   │   └── models/
-        │   │   │       └── GameSummaryView.kt          ← structure de la vue elle-même 
-        │   ├── websocket/
-        │   │   ├── WebSocketServer.ts
-        │   │   ├── connectionManager.ts         ← Map<gameId, Map<playerId, WebSocket>>
-        │   │   └── commandRouter.ts             ← reçoit le message brut, dispatch vers le bon handler
-        │   └── eventPublisher/
-        │       └── WebSocketEventPublisher.ts   ← implémente EventPublisher, fait le broadcast
-        └── presentation/                        ← Traduction vers/depuis le client (le fameux DTO layer)
-            ├── clientEvents/
-            │   ├── ClientEvent.ts               ← types des events envoyés au front
-            │   └── toClientEvent.ts             ← fonction de traduction domain event → client event
-            └── clientCommands/
-                └── parseIncomingCommand.ts      ← valide/parse le message brut du client → Command
-```
@@ -21,15 +21,13 @@ docker compose -f docker\docker-compose-test.yaml up -d

 Api url:
 - [Backend API](http://api.traefik.me/)
- [Frontend web site](http://app.traefik.me/) (WIP)
+- [Frontend web site](http://app.traefik.me/)

-Exposed url on test env:
+Exposed url on dev env:
 - [PostgreSql](http://localhost:5432/)
- [Redis](http://localhost:6379/)
 - [RabbitMQ](http://localhost:15672/)

 Admin service URL:
 - [Træfik dashboard](http://traefik.traefik.me/)
- [Redis insight](http://insight.redis.traefik.me/)
 - [pgAdmin](http://pgadmin.postgresql.traefik.me/)
 - [RabbitMQ management](http://management.rabbitmq.traefik.me/)
@@ -1,93 +0,0 @@
-@startuml
-'https://plantuml.com/class-diagram
-
-left to right direction
-
-class GameList <<Projection>> {
-  + status: Status
-}
-class GameState <<Projection>> {
-  + players: List<Player>
-  + currentPlayerTurn: Player
-  + lastCardPlayer: Player
-  + colorOnCurrentStack: Color
-  + direction: Direction
-  + readyPlayers: List<Player>
-  + deck: Deck
-  + isStarted: Boolean
-  + playerWins: List<Player>
-}
-interface Card {
-  + id: UUID
-}
-enum Color {
-  + Blue
-  + Red
-  + Yellow
-  + Green
-}
-class GameId {
-  + id: UUID
-}
-class Player {
-  + id: PlayerId
-  + name: String
-}
-class Deck {
-  + stack: Stack
-  + discard: Discard
-  + playersHands: PlayersHands
-}
-class Stack {
-  + cards: List<Card>
-  + shuffle()
-}
-class Discard {
-  + cards: List<Card>
-}
-class PlayerHands {
-  + map: Map<PlayerId, List<Card>>
-}
-
-class NumericCard {
-  + number: Int
-  + color: Color
-}
-class ReverseCard {
-  + color: Color
-}
-class PassCard {
-  + color: Color
-}
-class Plus2Card {
-  + color: Color
-}
-class Plus4Card
-class ChangeColorCard
-
-GameState *-- Deck
-GameState o-- "many" Player
-Deck *-- PlayerHands
-PlayerHands *-- "many" Card
-PlayerHands o-- "many" Player
-Stack *-- "many" Card
-Discard *-- "many" Card
-Deck *-- Stack
-Deck *-- Discard
-GameState *-- GameId
-Card <|--- NumericCard
-Card <|--- ReverseCard
-Card <|--- PassCard
-Card <|--- ChangeColorCard
-Card <|--- Plus2Card
-Card <|--- Plus4Card
-
-ReverseCard o-- Color
-NumericCard o-- Color
-PassCard o-- Color
-Plus2Card o-- Color
-
-GameList *-- GameId
-GameList o-- "many" Player
-
-@enduml
@@ -1,84 +0,0 @@
-@startuml
-'https://plantuml.com/use-case-diagram
-
-package Legend {
-    usecase (Queries) #7693C4
-    usecase (Projections) #AB64C9
-    usecase (Events) #5FAD56
-}
-
-actor  User
-entity Query #7693C4
-
-entity Command #5FAD56
-entity Event #5FAD56
-entity Projection #AB64C9
-
-database  Postgresql
-database  Redis
-queue     RabbitMQ
-
-usecase  (Web socket adapter) #5FAD56
-usecase  (Command handler) #5FAD56
-usecase/ (Action) #5FAD56
-usecase  (Event handler) #5FAD56
-usecase  (Version builder) #5FAD56
-usecase  (Event store) #5FAD56
-usecase  (Event stream) #5FAD56
-usecase  (Event bus) #5FAD56
-usecase/ (Reaction listener) #5FAD56
-
-usecase/ (Projection builder) #AB64C9
-usecase  (Projection repository) #AB64C9
-usecase  (Projection bus) #AB64C9
-
-usecase  (Controller) #7693C4
-
-User -> Query : <<create>>
-Command <- User : <<create>>
-User ---> (Controller) : Get \nprojection
-User <-- (Controller) : Returns \nprojection
-
-(Controller) --------> (Projection repository) : Get \nprojection
-
-User -> (Web socket adapter) : Send \ncommand
-(Web socket adapter) --> (Command handler) : Send \ncommand
-(Web socket adapter) ...> User : Send notification \n(error or success)
-
-(Command handler) ..> (Web socket adapter) : Send \nnotification
-(Command handler) -> (Action) : Execute action
-(Command handler) <- (Action) : Returns \nevent builder
-(Command handler) ---> (Event handler) : Dispatch \nevent \n(send an event builder)
-(Command handler) --> Event : <<Create>>
-
-(Event handler) --> (Event store) : Publish \nevent
-(Event handler) <-- (Reaction listener) : Dispatch \n new event
-(Version builder) <- (Event handler) : build next version
-note "Acquire a lock, \nget the next event version, \nand then, build the event " as EventHandlerNote
-EventHandlerNote <-- (Event handler)
-
-(Event store) -left-> (Event stream)
-(Event store) ---> (Event bus) : Publish \nevent
-
-(Event stream) --> Postgresql : Persist \nevent
-(Event bus) -> RabbitMQ : Publish \nevent
-(Event bus) -> RabbitMQ : Subscribe \nto event
-(Event bus) <. RabbitMQ : Emit event
-
-(Reaction listener) ---> (Projection bus) : Subscribe
-(Reaction listener) <.. (Projection bus) : Emit projection
-
-(Projection bus) <- (Projection repository) : Publish \nprojection
-RabbitMQ <- (Projection bus) : Publish \nprojection
-RabbitMQ <- (Projection bus) : Subscribe \nto projection
-RabbitMQ .> (Projection bus) : Emit projection
-
-(Event bus) <---- (Projection repository) : Subscribe
-(Event bus) ..> (Projection repository) : Emit event
-
-(Projection repository) --> Redis : Persist \nprojection
-(Projection repository) <- Redis : Get \nprojection
-(Projection repository) -> (Projection builder) : Build \nprojection
-
-(Projection builder) --> Projection : <<create projection>>
-@enduml
@@ -1,3 +1,2 @@
-REDIS_URL=redis://redis:6379
 POSTGRESQL_URL=jdbc:postgresql://postgresql/event-demo
 RABBITMQ_URL=rabbitmq
@@ -10,8 +10,6 @@ services:
        condition: service_healthy
      rabbitmq:
        condition: service_healthy
-      redis:
-        condition: service_healthy
    env_file:
      - ../.env.docker
    labels:
@@ -1,8 +1,4 @@
 services:
-  redis:
-    ports:
-      - "6379:6379"
-
  postgresql:
    ports:
      - "5432:5432"
@@ -1,12 +1,4 @@
 services:
-  redis:
-    image: redis/redis-stack:7.4.0-v8
-    healthcheck:
-      test: [ "CMD", "redis-cli", "--raw", "incr", "ping" ]
-    volumes:
-      - redis_data:/data
-      - redisinsight_data:/redisinsight
-
  flyway:
    image: flyway/flyway
    command: migrate
@@ -45,7 +37,5 @@ services:
      - rabbitmq_data:/var/lib/rabbitmq/

 volumes:
-  redis_data:
-  redisinsight_data:
  postgresql_data:
  rabbitmq_data:
@@ -13,8 +13,6 @@ services:
        condition: service_healthy
      rabbitmq:
        condition: service_healthy
-      redis:
-        condition: service_healthy
    env_file:
      - ../.env.docker

@@ -12,12 +12,6 @@ services:
      - "traefik.http.routers.pgadmin.rule=Host(`pgadmin.postgresql.traefik.me`)"
      - "traefik.http.services.pgadmin.loadbalancer.server.port=80"

-  redis:
-    labels:
-      - "traefik.http.routers.redisinsight.rule=Host(`insight.redis.traefik.me`)"
-      - "traefik.http.routers.redisinsight.service=redisinsight"
-      - "traefik.http.services.redisinsight.loadbalancer.server.port=8001"
-
  rabbitmq:
    labels:
      - "traefik.http.routers.rabbitmq-management.rule=Host(`management.rabbitmq.traefik.me`)"
@@ -1,58 +1,264 @@
 openapi: "3.0.3"
 info:
  title: "event_demo API"
-  description: "event_demo API"
-  version: "1.0.0"
+  description: |
+    API for the event_demo project: a small event-sourced Uno-like card game.
+
+    The API is split in two parts:
+    - a classic REST API used to authenticate, create users, list games and
+      replay a game's history.
+    - a WebSocket endpoint (`/games/{id}`) used to play a game in real time:
+      the client sends `GameCommand` messages and receives `Notification`
+      messages back. See the `x-websocket-channels` section below for details,
+      since WebSockets are not natively described by OpenAPI 3.0.
+
+    Authentication is done with a JWT bearer token obtained from `/login/{username}`.
+    Note that most polymorphic messages (`GameCommand`, `Notification`) are
+    discriminated by a `type` field whose value is the fully-qualified Kotlin
+    class name of the payload (since no custom serial name is declared for
+    these types), while `Card` uses short discriminator values
+    (`Simple`, `Reverse`, `Pass`, `Plus2`, `Plus4`, `ChangeColor`).
+  version: "2.0.0"
 servers:
 - url: "https://event_demo"
+
+tags:
+- name: Auth
+  description: User registration and authentication
+- name: Games
+  description: Listing games and reading/playing their state
+
+security:
+- bearerAuth: []
+
 paths:
-  "/game/{id}/card/last":
-    get:
-      description: get the last card played
+  "/login/{username}":
+    post:
+      tags: [Auth]
+      summary: Log in and obtain a JWT
+      security: []
+      parameters:
+        - name: username
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: password
+          in: query
+          description: The user's plain-text password.
+          required: true
+          schema:
+            type: string
      responses:
        200:
-          description: The last card
+          description: Successful login
          content:
            application/json:
              schema:
-                $ref: "#/components/schemas/Card"
+                $ref: "#/components/schemas/LoginResponse"
+        400:
+          description: Unknown username or invalid password
+  "/users/create":
+    post:
+      tags: [Auth]
+      summary: Create a new user account
+      description: Requires a valid JWT (any authenticated user can create new users).
+      parameters:
+        - name: username
+          in: query
+          required: true
+          schema:
+            type: string
+        - name: password
+          in: query
+          description: The plain-text password, hashed server-side before being stored.
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: The newly created user
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CreateUserResponse"
+        401:
+          $ref: "#/components/responses/Unauthorized"
+  "/games":
+    get:
+      tags: [Games]
+      summary: List all known games
+      description: Returns up to the 100 most recent games (pagination is not yet exposed on this route).
+      responses:
+        200:
+          description: The list of games
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/GameList"
+        401:
+          $ref: "#/components/responses/Unauthorized"
+  "/games/{id}":
+    get:
+      tags: [Games]
+      summary: Replay a game's full notification history
+      description: |
+        Rebuilds every notification that would have been sent to the calling
+        player since the beginning of the game (from its event stream), so a
+        client reconnecting can catch up on the current game state.
+
+        This same path also accepts a WebSocket upgrade to play the game live,
+        see `x-websocket-channels` at the root of this document.
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        200:
+          description: The full list of notifications for this game, from this player's point of view
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Notification"
+        401:
+          $ref: "#/components/responses/Unauthorized"
+        404:
+          description: No game found for this id
+
+x-websocket-channels:
+  "/games/{id}":
+    description: |
+      WebSocket endpoint to join and play a game in real time. Requires the
+      same JWT bearer authentication as the REST routes (sent the same way,
+      e.g. via the `Authorization` header during the WebSocket handshake).
+    parameters:
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+    send:
+      description: Commands sent by the client to act on the game.
+      schema:
+        $ref: "#/components/schemas/GameCommand"
+    receive:
+      description: Notifications sent by the server as the game progresses.
+      schema:
+        $ref: "#/components/schemas/Notification"

 components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: >
+        JWT obtained from `POST /login/{username}`. It carries the `username`
+        and `userid` claims and currently expires 60 seconds after issuance.
+
+  responses:
+    Unauthorized:
+      description: Missing, invalid or expired JWT
+      content:
+        text/plain:
+          schema:
+            type: string
+            example: "Token is not valid or has expired"
+
  schemas:
-    Card:
-      oneOf:
-        - $ref: "#/components/schemas/SimpleCard"
-        - $ref: "#/components/schemas/ReverseCard"
-        - $ref: "#/components/schemas/PassCard"
-        - $ref: "#/components/schemas/Plus2Card"
-        - $ref: "#/components/schemas/Plus4Card"
-        - $ref: "#/components/schemas/ChangeColorCard"
-    SimpleCard:
+    LoginResponse:
+      type: object
+      required: [token]
      properties:
-        number:
+        token:
+          type: string
+          description: JWT bearer token to use on subsequent requests.
+
+    CreateUserResponse:
+      type: object
+      required: [id]
+      properties:
+        id:
+          type: string
+          format: uuid
+
+    HttpErrorBadRequest:
+      type: object
+      description: Generic problem-details style error body used by some validation failures.
+      properties:
+        title:
+          type: string
+        statusCode:
          type: integer
-        color:
-          $ref: "#/components/schemas/CardColor"
-    ReverseCard:
+        invalidParams:
+          type: array
+          items:
+            $ref: "#/components/schemas/InvalidParam"
+
+    InvalidParam:
+      type: object
+      required: [name, reason]
      properties:
-        color:
-          $ref: "#/components/schemas/CardColor"
-    PassCard:
+        name:
+          type: string
+        reason:
+          type: string
+
+    PlayerId:
+      type: string
+      format: uuid
+
+    Player:
+      type: object
+      required: [name, userId, hand, id]
      properties:
-        color:
-          $ref: "#/components/schemas/CardColor"
-    Plus2Card:
+        name:
+          type: string
+        userId:
+          type: string
+          format: uuid
+        id:
+          $ref: "#/components/schemas/PlayerId"
+        hand:
+          description: The set of cards currently held by the player.
+          type: array
+          items:
+            $ref: "#/components/schemas/Card"
+
+    GameList:
+      type: object
+      required: [aggregateId, status, players, winners]
      properties:
-        color:
-          $ref: "#/components/schemas/CardColor"
-    Plus4Card:
-      properties:
-        nextColor:
-          $ref: "#/components/schemas/CardColor"
-    ChangeColorCard:
-      properties:
-        nextColor:
-          $ref: "#/components/schemas/CardColor"
+        aggregateId:
+          type: string
+          format: uuid
+        status:
+          $ref: "#/components/schemas/GameStatus"
+        players:
+          type: array
+          items:
+            $ref: "#/components/schemas/Player"
+        winners:
+          type: array
+          items:
+            $ref: "#/components/schemas/PlayerId"
+
+    GameStatus:
+      type: string
+      enum:
+        - OPENING
+        - IS_STARTED
+        - FINISH
+        - CANCELED
+
    CardColor:
      type: string
      enum:
@@ -60,3 +266,401 @@ components:
        - Red
        - Yellow
        - Green
+
+    Card:
+      description: >
+        A playing card. Discriminated by the "type" field using the short
+        names declared on each Kotlin subtype (@SerialName), unlike
+        GameCommand/Notification below.
+      oneOf:
+        - $ref: "#/components/schemas/NumericCard"
+        - $ref: "#/components/schemas/ReverseCard"
+        - $ref: "#/components/schemas/PassCard"
+        - $ref: "#/components/schemas/Plus2Card"
+        - $ref: "#/components/schemas/Plus4Card"
+        - $ref: "#/components/schemas/ChangeColorCard"
+      discriminator:
+        propertyName: type
+        mapping:
+          Simple: "#/components/schemas/NumericCard"
+          Reverse: "#/components/schemas/ReverseCard"
+          Pass: "#/components/schemas/PassCard"
+          Plus2: "#/components/schemas/Plus2Card"
+          Plus4: "#/components/schemas/Plus4Card"
+          ChangeColor: "#/components/schemas/ChangeColorCard"
+
+    NumericCard:
+      description: A numbered card (0-9) of a given color.
+      type: object
+      required: [type, id, number, color]
+      properties:
+        type:
+          type: string
+          enum: [Simple]
+        id:
+          type: string
+          format: uuid
+        number:
+          type: integer
+          minimum: 0
+          maximum: 9
+        color:
+          $ref: "#/components/schemas/CardColor"
+
+    ReverseCard:
+      description: Reverses the turn order.
+      type: object
+      required: [type, id, color]
+      properties:
+        type:
+          type: string
+          enum: [Reverse]
+        id:
+          type: string
+          format: uuid
+        color:
+          $ref: "#/components/schemas/CardColor"
+
+    PassCard:
+      description: Skips the next player's turn.
+      type: object
+      required: [type, id, color]
+      properties:
+        type:
+          type: string
+          enum: [Pass]
+        id:
+          type: string
+          format: uuid
+        color:
+          $ref: "#/components/schemas/CardColor"
+
+    Plus2Card:
+      description: Forces the next player to draw 2 cards and skips their turn.
+      type: object
+      required: [type, id, color]
+      properties:
+        type:
+          type: string
+          enum: [Plus2]
+        id:
+          type: string
+          format: uuid
+        color:
+          $ref: "#/components/schemas/CardColor"
+
+    Plus4Card:
+      description: >
+        Forces the next player to draw 4 cards and skips their turn. The new
+        color is chosen separately, via the `chosenColor` field of
+        PlayCardCommand, and is not part of the card itself.
+      type: object
+      required: [type, id]
+      properties:
+        type:
+          type: string
+          enum: [Plus4]
+        id:
+          type: string
+          format: uuid
+
+    ChangeColorCard:
+      description: >
+        Changes the current color. The new color is chosen separately, via
+        the `chosenColor` field of PlayCardCommand, and is not part of the
+        card itself.
+      type: object
+      required: [type, id]
+      properties:
+        type:
+          type: string
+          enum: [ChangeColor]
+        id:
+          type: string
+          format: uuid
+
+    GameCommand:
+      description: >
+        A command sent by the client over the game WebSocket to act on a game.
+        Discriminated by "type", whose value is the fully-qualified Kotlin
+        class name of the command (no `@SerialName` is declared on these
+        types).
+      oneOf:
+        - $ref: "#/components/schemas/JoinTheGameCommand"
+        - $ref: "#/components/schemas/PlayCardCommand"
+        - $ref: "#/components/schemas/ReadyToPlayCommand"
+        - $ref: "#/components/schemas/TakeCartFromDrawPileCommand"
+      discriminator:
+        propertyName: type
+        mapping:
+          eventDemo.contexts.game.application.command.models.JoinTheGameCommand: "#/components/schemas/JoinTheGameCommand"
+          eventDemo.contexts.game.application.command.models.PlayCardCommand: "#/components/schemas/PlayCardCommand"
+          eventDemo.contexts.game.application.command.models.ReadyToPlayCommand: "#/components/schemas/ReadyToPlayCommand"
+          eventDemo.contexts.game.application.command.models.TakeCartFromDrawPileCommand: "#/components/schemas/TakeCartFromDrawPileCommand"
+
+    JoinTheGameCommand:
+      description: Join an existing (not yet started) game.
+      type: object
+      required: [type, userId, payload]
+      properties:
+        type:
+          type: string
+          enum: [eventDemo.contexts.game.application.command.models.JoinTheGameCommand]
+        userId:
+          type: string
+          format: uuid
+        payload:
+          type: object
+          required: [aggregateId]
+          properties:
+            aggregateId:
+              type: string
+              format: uuid
+              description: The id of the game to join.
+
+    ReadyToPlayCommand:
+      description: Mark the calling player as ready, so the game can start once everyone is ready.
+      type: object
+      required: [type, userId, payload]
+      properties:
+        type:
+          type: string
+          enum: [eventDemo.contexts.game.application.command.models.ReadyToPlayCommand]
+        userId:
+          type: string
+          format: uuid
+        payload:
+          type: object
+          required: [aggregateId, playerId]
+          properties:
+            aggregateId:
+              type: string
+              format: uuid
+            playerId:
+              $ref: "#/components/schemas/PlayerId"
+
+    TakeCartFromDrawPileCommand:
+      description: Draw a card from the draw pile.
+      type: object
+      required: [type, userId, payload]
+      properties:
+        type:
+          type: string
+          enum: [eventDemo.contexts.game.application.command.models.TakeCartFromDrawPileCommand]
+        userId:
+          type: string
+          format: uuid
+        payload:
+          type: object
+          required: [aggregateId, playerId]
+          properties:
+            aggregateId:
+              type: string
+              format: uuid
+            playerId:
+              $ref: "#/components/schemas/PlayerId"
+
+    PlayCardCommand:
+      description: Play a card from the calling player's hand.
+      type: object
+      required: [type, userId, payload]
+      properties:
+        type:
+          type: string
+          enum: [eventDemo.contexts.game.application.command.models.PlayCardCommand]
+        userId:
+          type: string
+          format: uuid
+        payload:
+          type: object
+          required: [aggregateId, playerId, card]
+          properties:
+            aggregateId:
+              type: string
+              format: uuid
+            playerId:
+              $ref: "#/components/schemas/PlayerId"
+            card:
+              $ref: "#/components/schemas/Card"
+            chosenColor:
+              description: The color to switch to, only required when playing a Plus4Card or ChangeColorCard.
+              nullable: true
+              allOf:
+                - $ref: "#/components/schemas/CardColor"
+
+    Notification:
+      description: >
+        A notification sent by the server, either replayed by `GET /games/{id}`
+        or streamed live over the game WebSocket. Discriminated by "type",
+        whose value is the fully-qualified Kotlin class name of the
+        notification (no `@SerialName` is declared on these types).
+      oneOf:
+        - $ref: "#/components/schemas/WelcomeToTheGameNotification"
+        - $ref: "#/components/schemas/PlayerAsJoinTheGameNotification"
+        - $ref: "#/components/schemas/PlayerWasReadyNotification"
+        - $ref: "#/components/schemas/TheGameWasStartedNotification"
+        - $ref: "#/components/schemas/ItsTheTurnOfNotification"
+        - $ref: "#/components/schemas/PlayerAsPlayACardNotification"
+        - $ref: "#/components/schemas/YourNewCardNotification"
+        - $ref: "#/components/schemas/PlayerHavePassNotification"
+        - $ref: "#/components/schemas/PilesShuffledNotification"
+        - $ref: "#/components/schemas/PlayerWinNotification"
+      discriminator:
+        propertyName: type
+        mapping:
+          eventDemo.contexts.game.application.notification.models.WelcomeToTheGameNotification: "#/components/schemas/WelcomeToTheGameNotification"
+          eventDemo.contexts.game.application.notification.models.PlayerAsJoinTheGameNotification: "#/components/schemas/PlayerAsJoinTheGameNotification"
+          eventDemo.contexts.game.application.notification.models.PlayerWasReadyNotification: "#/components/schemas/PlayerWasReadyNotification"
+          eventDemo.contexts.game.application.notification.models.TheGameWasStartedNotification: "#/components/schemas/TheGameWasStartedNotification"
+          eventDemo.contexts.game.application.notification.models.ItsTheTurnOfNotification: "#/components/schemas/ItsTheTurnOfNotification"
+          eventDemo.contexts.game.application.notification.models.PlayerAsPlayACardNotification: "#/components/schemas/PlayerAsPlayACardNotification"
+          eventDemo.contexts.game.application.notification.models.YourNewCardNotification: "#/components/schemas/YourNewCardNotification"
+          eventDemo.contexts.game.application.notification.models.PlayerHavePassNotification: "#/components/schemas/PlayerHavePassNotification"
+          eventDemo.contexts.game.application.notification.models.PilesShuffledNotification: "#/components/schemas/PilesShuffledNotification"
+          eventDemo.contexts.game.application.notification.models.PlayerWinNotification: "#/components/schemas/PlayerWinNotification"
+
+    WelcomeToTheGameNotification:
+      description: Sent to a player right after they join a game, listing all players currently in it.
+      type: object
+      required: [type, id, players]
+      properties:
+        type:
+          type: string
+          enum: [eventDemo.contexts.game.application.notification.models.WelcomeToTheGameNotification]
+        id:
+          type: string
+          format: uuid
+        players:
+          type: array
+          items:
+            $ref: "#/components/schemas/Player"
+
+    PlayerAsJoinTheGameNotification:
+      description: Sent to the other players when a new player joins the game.
+      type: object
+      required: [type, id, player]
+      properties:
+        type:
+          type: string
+          enum: [eventDemo.contexts.game.application.notification.models.PlayerAsJoinTheGameNotification]
+        id:
+          type: string
+          format: uuid
+        player:
+          $ref: "#/components/schemas/Player"
+
+    PlayerWasReadyNotification:
+      description: Sent to all players when a player marks themselves as ready.
+      type: object
+      required: [type, id, playerId]
+      properties:
+        type:
+          type: string
+          enum: [eventDemo.contexts.game.application.notification.models.PlayerWasReadyNotification]
+        id:
+          type: string
+          format: uuid
+        playerId:
+          $ref: "#/components/schemas/PlayerId"
+
+    TheGameWasStartedNotification:
+      description: Sent to each player when the game starts, with their initial hand.
+      type: object
+      required: [type, id, hand]
+      properties:
+        type:
+          type: string
+          enum: [eventDemo.contexts.game.application.notification.models.TheGameWasStartedNotification]
+        id:
+          type: string
+          format: uuid
+        hand:
+          type: array
+          items:
+            $ref: "#/components/schemas/Card"
+
+    ItsTheTurnOfNotification:
+      description: Sent to all players to indicate whose turn it now is.
+      type: object
+      required: [type, id, player]
+      properties:
+        type:
+          type: string
+          enum: [eventDemo.contexts.game.application.notification.models.ItsTheTurnOfNotification]
+        id:
+          type: string
+          format: uuid
+        player:
+          $ref: "#/components/schemas/Player"
+
+    PlayerAsPlayACardNotification:
+      description: Sent to all players when a player plays a card.
+      type: object
+      required: [type, id, playerId, card]
+      properties:
+        type:
+          type: string
+          enum: [eventDemo.contexts.game.application.notification.models.PlayerAsPlayACardNotification]
+        id:
+          type: string
+          format: uuid
+        playerId:
+          $ref: "#/components/schemas/PlayerId"
+        card:
+          $ref: "#/components/schemas/Card"
+
+    YourNewCardNotification:
+      description: Sent to a player with the cards they just drew from the draw pile.
+      type: object
+      required: [type, id, cards]
+      properties:
+        type:
+          type: string
+          enum: [eventDemo.contexts.game.application.notification.models.YourNewCardNotification]
+        id:
+          type: string
+          format: uuid
+        cards:
+          type: array
+          items:
+            $ref: "#/components/schemas/Card"
+
+    PlayerHavePassNotification:
+      description: Sent to the other players when a player draws a card and passes their turn.
+      type: object
+      required: [type, id, playerId]
+      properties:
+        type:
+          type: string
+          enum: [eventDemo.contexts.game.application.notification.models.PlayerHavePassNotification]
+        id:
+          type: string
+          format: uuid
+        playerId:
+          $ref: "#/components/schemas/PlayerId"
+
+    PilesShuffledNotification:
+      description: Sent to all players when the discard pile is reshuffled into the draw pile.
+      type: object
+      required: [type, id]
+      properties:
+        type:
+          type: string
+          enum: [eventDemo.contexts.game.application.notification.models.PilesShuffledNotification]
+        id:
+          type: string
+          format: uuid
+
+    PlayerWinNotification:
+      description: Sent to all players when a player wins the game.
+      type: object
+      required: [type, id, playerId]
+      properties:
+        type:
+          type: string
+          enum: [eventDemo.contexts.game.application.notification.models.PlayerWinNotification]
+        id:
+          type: string
+          format: uuid
+        playerId:
+          $ref: "#/components/schemas/PlayerId"
@@ -3,7 +3,6 @@ package eventDemo.configuration
 import io.ktor.server.config.ApplicationConfig

 data class Configuration(
-  val redisUrl: String,
  val jwtSecret: String,
  val postgresql: Postgresql,
  val rabbitmq: RabbitMQ,
@@ -25,7 +24,6 @@ data class Configuration(
 val ApplicationConfig.configuration
  get() =
    Configuration(
-      redisUrl = getProperty("redis.url"),
      jwtSecret = getProperty("jwt.secret"),
      postgresql =
        Configuration.Postgresql(
@@ -7,8 +7,6 @@ import org.koin.core.module.Module
 import org.koin.core.scope.Scope
 import org.koin.core.scope.ScopeCallback
 import org.koin.dsl.bind
-import redis.clients.jedis.JedisPooled
-import redis.clients.jedis.UnifiedJedis
 import javax.sql.DataSource

 fun Module.configureDIDataSource(config: Configuration) {
@@ -26,11 +24,6 @@ fun Module.configureDIDataSource(config: Configuration) {
      }
  } bind DataSource::class

-  // Redis (for Projections)
-  single {
-    JedisPooled(config.redisUrl)
-  } bind UnifiedJedis::class
-
  // RabbitMQ (for EventBus)
  factory {
    ConnectionFactory().apply {
@@ -12,11 +12,6 @@ jwt {
    secret = ${?JWT_SECRET}
 }

-redis {
-    url = "redis://localhost:6379"
-    url = ${?REDIS_URL}
-}
-
 postgresql {
    url = "jdbc:postgresql://localhost:5432/event-demo"
    url = ${?POSTGRESQL_URL}
@@ -7,7 +7,5 @@ object Tag {

  object RabbitMQ : Tag()

-  object Redis : Tag()
-
  object Concurrence : Tag()
 }
@@ -6,12 +6,18 @@ import com.tngtech.archunit.library.Architectures.layeredArchitecture
 import org.junit.jupiter.api.Test

 /**
- * Vérifie le respect des frontières de l'architecture hexagonale (ports & adapters).
+ * Vérifie le respect des frontières de l'architecture hexagonale (ports & adapters),
+ * pour chaque bounded context sous `eventDemo.contexts`.
 *
- * Convention attendue :
- *   eventDemo.contexts.uno.domain
- *   eventDemo.contexts.uno.application
- *   eventDemo.contexts.uno.infrastructure
+ * Les contexts ne sont pas listés en dur : ils sont déduits des classes réellement
+ * présentes sous `eventDemo.contexts.*`, de sorte que l'ajout d'un nouveau context
+ * (nouveau dossier `eventDemo.contexts.<xxx>`) soit automatiquement couvert par ce test,
+ * sans modification de ce fichier.
+ *
+ * Convention attendue, pour un contexte donné :
+ *   eventDemo.contexts.<context>.domain
+ *   eventDemo.contexts.<context>.application
+ *   eventDemo.contexts.<context>.infrastructure
 *
 * Règles imposées :
 *   – domain         → ne dépend d'aucune autre couche (ni application, ni infrastructure)
@@ -19,15 +25,32 @@ import org.junit.jupiter.api.Test
 *   – infrastructure → ne dépend que de domain et application
 */
 class HexagonalArchitectureTest {
-  private val basePackage = "eventDemo.contexts.uno"
+  private val rootPackage = "eventDemo.contexts"

  private val classes =
    ClassFileImporter()
      .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)
-      .importPackages(basePackage)
+      .importPackages(rootPackage)
+
+  // Premier segment de package après "eventDemo.contexts." (ex. "auth", "game", ...),
+  // recalculé à chaque exécution à partir des classes importées.
+  private val contexts: Set<String> =
+    classes
+      .map { it.packageName }
+      .filter { it.startsWith("$rootPackage.") }
+      .map { it.removePrefix("$rootPackage.").substringBefore('.') }
+      .toSet()

  @Test
  fun `respecte les couches de l'architecture hexagonale`() {
+    check(contexts.isNotEmpty()) {
+      "Aucun context trouvé sous `$rootPackage` : le test ne vérifie rien, " +
+        "vérifiez que le package racine est correct."
+    }
+
+    contexts.forEach { context ->
+      val basePackage = "$rootPackage.$context"
+
      @Suppress("ktlint:standard:chain-method-continuation")
      layeredArchitecture()
        .consideringAllDependencies()
@@ -39,4 +62,5 @@ class HexagonalArchitectureTest {
        .whereLayer("Infrastructure").mayOnlyAccessLayers("Domain", "Application")
        .check(classes)
    }
+  }
 }
@@ -1,21 +0,0 @@
-package eventDemo.contexts.game.intrastructure.persistence.connectors
-
-import eventDemo.Tag
-import eventDemo.testHelpers.testKoinApplicationWithConfig
-import io.kotest.core.spec.style.FunSpec
-import io.kotest.matchers.equals.shouldBeEqual
-import redis.clients.jedis.UnifiedJedis
-
-class RedisTest :
-  FunSpec({
-    tags(Tag.Redis)
-
-    test("test connection with jedis") {
-      testKoinApplicationWithConfig {
-        get<UnifiedJedis>().also {
-          it.set("test", "test")
-          it.get("test") shouldBeEqual "test"
-        }
-      }
-    }
-  })
@@ -1,7 +1,6 @@
 package eventDemo.testHelpers

 import org.koin.core.Koin
-import redis.clients.jedis.UnifiedJedis
 import javax.sql.DataSource

 fun DataSource.cleanEventSource() {
@@ -17,11 +16,6 @@ fun DataSource.cleanEventSource() {
  }
 }

-fun UnifiedJedis.cleanProjections() {
-  flushAll()
-}
-
 fun Koin.cleanDataTest() {
  get<DataSource>().cleanEventSource()
-  get<UnifiedJedis>().cleanProjections()
 }
Author	SHA1	Message	Date
flecomte	505cfe38f0	chore: add CLAUDE.md Tests / build (push) Successful in 7m19s Details Tests / test (push) Failing after 10m44s Details Tests / lint (push) Successful in 13m49s Details	2026-08-06 19:52:48 +02:00
flecomte	85bcdcadb8	chore: remove unused redis	2026-08-06 19:42:32 +02:00
flecomte	e67c475c38	chore: auto test new context in HexagonalArchitectureTest	2026-08-06 19:33:38 +02:00
flecomte	07983dc5b0	fix: fix HexagonalArchitectureTest	2026-08-06 19:23:47 +02:00
flecomte	5e9587b93f	docs: clean	2026-08-06 19:10:32 +02:00
flecomte	fd62f2574d	docs: update openapi	2026-08-05 00:43:12 +02:00
flecomte	828bd0639e	docs: clean docs	2026-08-05 00:19:03 +02:00