Guidance:

• Set TRUST_FORWARDED_HEADERS=false if directly exposed (no reverse proxy).
• Set FORCE_SECURE_COOKIE=true when site is served over HTTPS (or behind TLS terminator).
• Adjust ReverseProxy__ApiAddress if service name/port differ in custom compose or Kubernetes.

The game runtime is governed by two concrete finite state machines defined in Room:

1. A top-level game FSM (RoomStatus + GameTrigger)
2. A phase (round step) FSM (Phase + PhaseTrigger) that is activated only while playing

Game-level lifecycle:

stateDiagram-v2
  [*] --> Waiting
  Waiting --> Playing : Start (host)
  Playing --> Finished : GameOver / FinisherCrossedLine
  Playing --> Finished : GameOver / NoActivePlayersLeft
  Playing --> Finished : GameOver / TurnLimitReached
  Finished --> [*]

Phase cycle (active only inside Playing):

stateDiagram-v2
  [*] --> CollectingCards
  CollectingCards --> CollectingParams : CardsReady
  CollectingParams --> Discarding : ParamsDone
  Discarding --> CollectingCards : DiscardDone / NextStep

To secure game actions without requiring users to register or log in, the system uses persistent JWTs.

1. First visit: The client calls the auth endpoint; the server generates a JWT and returns it (via an HttpOnly cookie) bound to that player.
2. Subsequent requests: The browser automatically sends the HttpOnly token cookie with every same-site API call.
3. Backend validation: The JWT bearer middleware (see Program.cs OnMessageReceived) extracts the token from the cookie and validates signature, (optional) issuer/audience, lifetime, then associates the player (subject claim) with the request. Game logic then additionally checks turn ownership to block out‑of‑turn or impersonated actions.

Inspired by patterns from other modern languages, the API avoids throwing exceptions for predictable domain errors. Instead, it returns strongly-typed result objects.

When an action fails for an expected reason (e.g., "It's not your turn," "The selected move is invalid," or "The game is already full"), the API returns a specific error type. This is achieved using the OneOf library, which allows a single endpoint to return a union of possible types (e.g., Success | NotYourTurn | RoomNotFound).

This forces the client to handle known failure scenarios explicitly, leading to a more robust and predictable user experience, and avoids polluting the server with exception-handling logic for non-exceptional situations.