mancala/docs/specs/quarkus-backend/design.md

# Quarkus backend: design

See `requirements.md` for what is built; requirement ids (R1.1, …) are referenced below. The behaviour being ported is
described in `keycloak-auth`, `game-history` and `game-clock`; this document covers how the Java backend is built.

## Decisions

| Decision | Reason |
|---|---|
| Quarkus 3.40 (latest stable; 4.0 is in beta), Java 25, JVM mode | R1. Java 25 is the current LTS. Native images would need reflection config for the JSON models and buy little for one long-running process. |
| A port of the rules to Java (`app.playmancala.engine`) instead of running `mancala.js` in the JVM (GraalJS) | The engine is about 500 lines with no dependencies; a port is simpler to run, debug and test than an embedded JS runtime. The clients keep using the TypeScript engine for display. |
| Engine parity is tested against games recorded with the TypeScript engine | R2.2. A Node script plays seeded random games (including illegal moves) with `packages/mancala.js` and writes every move and the resulting game JSON to a fixture; a Java test replays them. Run the script again after changing the rules. |
| All game state is owned by one thread, the **game loop** | The Node backend relies on running on one thread: `GameManager`, the stores, matchmaking, live previews and the WebSocket registry have no locks. A single-threaded scheduled executor keeps that model, so the game logic carries over line by line without races. WebSocket events, timers and API reads that touch live games run on it. A few hundred games are far from what one thread handles. |
| Blocking I/O never runs on the game loop (except the restore at startup) | Postgres writes run on the recorder's own thread, Valkey writes on a store thread that keeps them in order (a game's `SET` must not overtake its `DEL`), and token checks on a worker. Results that change state are posted back to the loop. Snapshots are copied on the loop, so serialising them elsewhere is safe. |
| Plain JDBC with the existing SQL and the existing migration runner (`schema_migrations`, advisory lock) | R5.1. Flyway or Liquibase would have to be baselined on databases the Node backend already migrated. Two migrations and a 40-line runner do not justify it. Hibernate adds nothing for two tables written once per game. |
| `quarkus-redis-client` (blocking `RedisDataSource`) for Valkey | Valkey speaks the Redis protocol. Short connect and command timeouts make calls fail fast while Valkey is down, like `enableOfflineQueue: false` did. |
| `quarkus-websockets-next` endpoint at `/`, a thin adapter over a framework-free `RtmtServer` | R3.1. The endpoint only forwards open, text and close events to the game loop; `RtmtServer` holds the protocol (auth handshake, timeouts, sockets per user, ping) and is unit-tested with fake sockets and a manual clock. |
| jose4j for Keycloak tokens, not `quarkus-oidc` | Tokens arrive in a WebSocket message, not only in an HTTP header, so they are verified in code. jose4j (managed by the Quarkus BOM) fetches and caches the realm's JWKS like `jose` did. The checks are unchanged: RS256, issuer, `sub`, `exp`, `typ = Bearer`, `azp` in `KEYCLOAK_CLIENT_IDS`. |
| Explicit JSON models (records) with `@JsonInclude(NON_NULL)` only on optional fields | R3.2, R5. TypeScript leaves out `undefined` but keeps `null`; e.g. `result: null` and `{ game: null }` must stay while `name` and `leftUserId` are left out. |
| `DATABASE_URL` becomes `DATABASE_JDBC_URL`, `DATABASE_USERNAME`, `DATABASE_PASSWORD` | R7.1. The JDBC driver does not take `postgres://user:pass@host/db`; parsing it ourselves is not worth it. Compose builds the new variables from the same `MANCALA_DB_PASSWORD`. |
| The project is built in `apps/backend-quarkus` and replaces `apps/backend` in the last task | Every commit on the branch has a working backend, and the two can be compared side by side; the final move keeps the path that the Dockerfile, compose and CI refer to. |
| `mvn quarkus:dev` debug port moved to 5006 | Quarkus dev mode listens for a debugger on 5005, the backend's port. |

## Layout

```
apps/backend/
  pom.xml
  Dockerfile                     multi-stage: Maven + Temurin 25 JDK, then Temurin 25 JRE
  scripts/record-engine-games.js writes the engine parity fixture from packages/mancala.js
  src/main/resources/
    application.properties
    db/migrations/001_games.sql, 002_clock.sql
  src/main/java/app/playmancala/
    engine/      Board, Pit, PitType, GameStep, MoveHistoryItem, MancalaGame, GameState, GameRule,
                 CommonMancalaGame and the four rules (port of packages/mancala.js)
    model/       wire types: AuthUser, PlayerInfo, PlayerSummary, UserConnectionInfo, GameUsersConnectionInfo,
                 GameClock, Seat, GameResult, EndReason, GameEndMessage, MoveRecord, GameRecord,
                 FinishedGameSummary, LiveGameSummary, ClientGame, Channels; Json (the shared ObjectMapper)
    loop/        GameLoop (the game thread), Scheduler (what the logic needs from it), Cancellable
    auth/        TokenVerifier, KeycloakTokenVerifier (made from config by TokenVerifierProducer), InvalidTokenException
    rtmt/        Rtmt (interface used by the game logic), RtmtServer, RtmtSocket, RtmtEndpoint (Quarkus)
    game/        BackendGame, GameStore, MatchMaker, GameManager, GameClocks, GameClockScheduler,
                 GameSerialization (LiveGameSnapshot), GameRecorder, LiveGames, PublicIds, CrashLog
    history/     GameHistoryRepository, PostgresGameHistoryRepository, Migrations, GameHistoryService
    live/        LiveGameStore, ValkeyLiveGameStore, Cache, ValkeyCache
    http/        GameResource (every route), BearerAuth, ErrorMapper (503 for failures)
    Backend.java wiring and startup (a @Startup bean)
```

The game logic (`engine`, `game`, `history` services, `rtmt.RtmtServer`) is plain Java built with constructors, as
the TypeScript classes were, so unit tests build it with fakes. `Backend` creates it from CDI-managed infrastructure
(datasource, Redis client, config) and exposes what the HTTP resources and the WebSocket endpoint need.

## Engine

A line-by-line port. Classes keep their TypeScript names and methods, so a change to one engine is easy to repeat in
the other. The JSON of `MancalaGame` matches `JSON.stringify` of the TypeScript object, because clients rebuild it
with `MancalaGame.createFromMancalaGame`:

```json
{ "id", "board": { "pits": [{ "index", "stoneCount" }], "playerPitCount", "initialStoneCountInPits" },
  "player1Id", "player2Id", "turnPlayerId", "state", "gameRules": [{}, {}, {}, {}],
  "history": [{ "boardSnapshot", "gameSteps": [{ "index", "type", "data" }], "playerId", "moveIndex" }],
  "currentHistoryItem" }
```

Errors keep their TypeScript messages (`IndexOutOfRange …`, `StoneNotFound …`, `Player cannot move reason : …`);
they are `IllegalStateException`s.

## Threads

```
WebSocket event loop ──open/text/close──▶ game loop (1 thread) ──▶ GameManager, LiveGames, MatchMaker, RtmtServer
                                              │   ▲
             token check (worker) ◀───────────┘   └── timers: clock check 1 s, ping 2 s, auth timeout, preview push
HTTP worker ──call(read live state)──▶ game loop, waits for the result; reads saved games itself
game loop ──snapshot──▶ store thread ──▶ Valkey (ordered)
game loop ──record──▶ recorder thread ──▶ Postgres (retry every 30 s), then cache invalidation
```

`Scheduler` is the part of the game loop the logic uses: `execute`, `schedule(delay)`, `scheduleAtFixedRate` and
`now()`. Tests use `ManualScheduler`, which runs tasks at once and timers when the test advances its clock, in
place of Jest's fake timers. Every task is wrapped so an exception is logged and never stops a repeating timer.

`GameRecorder` and the live game store take an `Executor`; tests pass a direct one, so saves finish before the test
looks, in place of `flushPromises`.

## WebSocket

`RtmtEndpoint` (`@WebSocket(path = "/")`) handles `@OnOpen`, `@OnTextMessage` and `@OnClose` as `@NonBlocking` and
only posts them to the game loop, keeping the order of a socket's events. It wraps the connection as an
`RtmtSocket` (`id`, `query`, `send`, `close(code, reason)`, `isOpen`). Sends are asynchronous and never block the
loop.

`RtmtServer` ports `rtmt_websocket.ts`: per socket an `alive` flag, the user id once authenticated and the auth
timeout; per user the set of sockets and the `AuthUser`. Message JSON is parsed on the loop. A token is checked on a
worker and the outcome handled on the loop, where a socket closed in the meantime is ignored.

## HTTP

Quarkus REST resources, blocking (run on worker threads). Reads of live games go through `GameLoop.call`, and the
client game is serialised on the loop because it refers to the live `MancalaGame`. `BearerAuth` checks the
`Authorization` header and answers 401. Any other exception becomes 503, as the Express error handler did. CORS and
the access log are Quarkus HTTP settings.

## Startup

`Backend` (`@Startup`) builds everything, then queues on the game loop, before any WebSocket event can be queued:
wait up to 5 s for Valkey, restore live games, start the clock check, the ping and the recorder's retries.
Migrations run on their own thread and are retried every 30 s until Postgres is reachable. A restore that takes long
(Postgres down: each check waits for the pool's 5 s timeout) delays socket events but loses none.

## Configuration

| Variable | Default | Quarkus property |
|---|---|---|
| `PORT` | `5005` (`6000` in the image) | `quarkus.http.port` |
| `KEYCLOAK_ISSUER`, `KEYCLOAK_JWKS_URL`, `KEYCLOAK_CLIENT_IDS`, `LEGACY_USERKEY_AUTH` | as before | `mancala.auth.*` |
| `GAME_CLOCK_MS` | `300000` | `mancala.game-clock-ms` |
| `VALKEY_URL` | `redis://localhost:6379` | `quarkus.redis.hosts` |
| `DATABASE_JDBC_URL` | `jdbc:postgresql://localhost:5433/mancala` | `quarkus.datasource.jdbc.url` |
| `DATABASE_USERNAME`, `DATABASE_PASSWORD` | `mancala` | `quarkus.datasource.username`, `.password` |

Tests use Quarkus Dev Services with the compose images (`postgres:17.6`, `valkey/valkey:9.1.2`); the unit tests need
no Docker.

## Testing

- Unit (no Docker): engine and parity fixture, game manager, live games, clock scheduler, token verifier (local key
  pair and JWKS), `RtmtServer` with fake sockets.
- `@QuarkusTest` (Docker): Postgres repository and migrations, Valkey store and cache (including an unreachable
  Valkey), HTTP API, and the WebSocket endpoint with a real client and a test token verifier.
- Manual, in Chrome with `playwright-core` against the local stack (R8.2): two players log in as guests and play a
  game to the end while a third user spectates and the home page shows the live preview; a player reloads mid-game;
  the backend is restarted mid-game and the game goes on with the clocks intact; the finished game appears in recent
  games and replays; a short `GAME_CLOCK_MS` ends a game on time.