Checkers

An online multiplayer draughts platform: Spring Boot microservices behind a single API gateway, a Python rule engine spoken to over gRPC, real-time play over STOMP WebSockets, and versioned platform contracts enforced in CI.

Architecture

Service	Tech	Responsibility
api-gateway	Spring Cloud Gateway	the only public entry point: HTTP/WS routing, edge JWT + token blacklist, rate limiting, CORS, aggregated Swagger
user-service	Spring Boot + PostgreSQL	accounts, JWT auth, OAuth2 (Google/Facebook), ELO ratings, audit log
game-service	Spring Boot + Redis + PostgreSQL	authoritative game state and clocks, turn flow, WebSocket push, durable game archive and history
matchmaking-service	Spring Boot + Redis	PvP queues and ELO-based pairing with a widening window
game-engine-service	Python + gRPC	rules for 8 draughts variants, move validation, AI search

Clients speak REST and STOMP WebSocket to the gateway; services speak gRPC to each other over an internal network with per-server auth tokens. Every boundary is a versioned contract in checkers-contracts — protobuf (checkers.v1, Buf breaking-change checks), JSON Schema for auth/WS/error payloads, and committed OpenAPI snapshots with REST compatibility checks. Full design notes live in each service's README.md.

Running locally

docker compose up --build

The whole backend starts single-instance on real stores (PostgreSQL + Flyway, password-protected Redis), with health-checked startup ordering. The gateway on http://localhost:8083 is the only public entry point — service and gRPC ports stay on the internal network. Database ports (5432, 5433) and Redis ports (6379–6381) are published to the host purely for debugging.

Aggregated API docs (Swagger UI for all three REST services, proxied through the gateway):

http://localhost:8083/swagger-ui.html

How this repository is run

• dev is the integration branch; main moves only through release pull requests and is tagged (see Releases).
• Every pull request passes the full pipeline: contract validation (Buf + JSON Schema + OpenAPI compatibility), build & tests of all four Java services with 100% line and branch coverage gates, Python engine tests, all five Docker image builds, and a full-history secret scan.
• Dependencies are managed by Dependabot with grouped weekly updates; deliberately pinned platforms (Java 21 LTS, the Python/protobuf/grpcio lockstep) are documented in .github/dependabot.yml.
• The roadmap lives in issues and milestones.

Production notes

The prod profiles fail fast: a missing secret, database host, or CORS origin stops startup instead of falling back to a development default. Per-service configuration (JWT contract, gRPC token matrix, OAuth2 setup, mail delivery) is documented in each service's README.md. Known, deliberate debt before a production deployment: the shared HS256 JWT secret (asymmetric signing/JWKS is planned), plaintext internal gRPC (mTLS is deferred to the Kubernetes phase), and single-instance scaling assumptions tracked in the Scale-out & production readiness milestone.