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. Cross-service communication, data ownership and transaction rules are recorded in docs/adr.

Running locally

docker compose up --build

The whole backend starts single-instance with every Spring service on its prod profile and 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, separate fast/slow Python engine checks, all five Docker image builds, Compose validation, a production-profile stack smoke test, compiler/Ruff linting, CodeQL, dependency review, and a full-history secret scan. Dependency review blocks newly introduced vulnerabilities rated high or critical.
• 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

Every Java service requires exactly one explicit dev, test, or prod profile. The prod profiles fail fast on a missing/known-development secret, datastore or service endpoint, external URL, or trusted-proxy setting. Forwarded headers are processed only in prod; backend HTTP ports remain private behind the gateway. 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.