Fairplay Arena, explained from scratch

A guided tour of Project 1 for someone who has never built a Spring Boot service, never used Redis and is not sure what a "record" or a "transaction" is. Every idea is explained the first time it appears. Every code sample is copied from the real files; shortened places are marked with ..., and comments that I added to explain a line start with // ». The last sections turn all of it into answers you can say out loud in an interview.

How to use this page Read sections 0 to 4 in order: they give you the whole picture. Then read section 5 one subsection at a time, with the real file open next to it. Section 11 is the interview material; it makes sense only after the rest. If a word is new, section 13 is a glossary. This guide describes the code in arena/. The folder Code Explanation/ also holds an older, shorter reference page (code guide.html) that this file does not replace.

0. Where the project stands

The plan (Fairplay Arena — Implementation Specification.md, section 16) builds Arena in 12 steps. This folder is not a git repository, so there is no commit history to read. The status below comes from the code, the tests and handoff.md/todo.md. Everything marked built exists and is covered by tests. partly says exactly what is missing. not built exists only as a plan.

StepWhatStatus
1Bootstrap: Maven project, Spring Boot 4.1.2, MapStruct, JaCoCo, compose.yamldone
2Configuration (ArenaProperties, ClockConfig) and the database schema (V1, V2)done
3Error foundation: ErrorCode, ApiException, GlobalExceptionHandler, PageResponsedone
4Security and auth: JWT, refresh-token rotation, AccountSeeder, endpoints 1 to 3done (but see the failing test below)
5Players: profiles, stats, percentiles, search (endpoints 4 to 7)done
6Leaderboard: rating formula, Redis sync, rebuild, rank lookups (endpoints 11, 12)done
7Matches: recording with locking and idempotency (endpoints 8 to 10)done
8Moderation: state machine, guardrails, audit log, queue (endpoints 13 to 15)done
9Appeals (endpoints 16 to 18)done
10Observability: custom metrics, JSON logspartly: built, but the two tagged counters arena_moderation_actions and arena_appeals_decided only appear on /actuator/prometheus after their first use. The spec step asks for every arena_* meter to be visible from startup, so that check is not met.
11Delivery: Dockerfile, compose with an optional Prometheus + Grafana profile, CI workflowpartly: the Dockerfile and compose are built and reached UP in the previous session. The CI workflow has never run (nothing is pushed), and it only works if arena/ becomes the repository root. Grafana starts, but no dashboard is provided.
12Benchmark and READMEdone, with caveats (section 0.2)

0.1 The real test numbers, from a run I did today (2026-11-18)

I ran ./mvnw verify from arena/ with Docker running (the integration tests need it). Then I ran it again with -Dmaven.test.failure.ignore=true, so that Maven kept going and wrote the coverage report even with a failing test.

MeasureResult
Tests run71: 51 unit tests and 20 integration tests (in 9 integration classes)
Passed / failed70 passed, 1 error, 0 failures, 0 skipped
Plain ./mvnw verifyBUILD FAILURE (stops at the test step)
Line coverage (JaCoCo)89.56%: 1,047 of 1,169 lines. Measured in the second run (70 of 71 tests passing). The build's gate is 85% and it passed. Branch coverage is 65.9% (there is no gate on it).
Size78 main Java files (about 4,000 lines), 15 test files (about 1,700 lines)
The build is red today, and the notes say it is green handoff.md, todo.md, CLAUDE.md and arena/README.md all say "71 tests, green". That was true when they were written on 2026-11-17, and it is no longer true. The failing test is TokenServiceTest.issuesAccessTokenWithExpectedClaimsHeaderAndExpiryFromClock, with the message Jwt expired at 2026-11-17T10:15:00Z.

Why: the test fixes its clock at 2026-11-17T10:00:00Z, so the token it makes expires 15 minutes later. But the test then decodes the token with NimbusJwtDecoder...build(), whose default validator checks expiry against the real clock. So the test could only pass before 10:15 UTC on 17 November 2026. It is a time-dependent test bug, not a bug in the product: the running application never uses a fixed clock. A fix is small (make the test's decoder use the same fixed clock, or skip the timestamp check in that test), but I did not change any code, because this task is the guide. Until it is fixed, a CI run would also fail. I added a line to todo.md about it.

0.2 How sure am I about each claim?

ClaimHow I know
71 tests, 70 pass, coverage 89.56%Run today.
Swagger lists exactly 18 operationsAsserted by SecurityIntegrationTest, which passed today.
13 of the 18 are securedDerived from code: five methods carry @SecurityRequirements (3 auth + 2 leaderboard), so 18 - 5 = 13. The number "13" is also in handoff.md.
docker compose up --build reaches UPFrom handoff.md (previous session). Not re-run today.
Benchmark: Redis p95 63.5 ms vs database p95 18.0 sFrom arena/README.md. Not re-run today. Measured in one session on one Windows machine: three runs per source, and only the third summary is reported (the first two were not saved). The load generator (k6) shared the same Docker VM as the services. The 1,000,000-row data was deleted afterwards. Treat the numbers as one honest measurement, not as a repeatable benchmark.
CI worksUnverified. The workflow file exists but has never run.
The Telemetry (Project 2) and Judge (Project 3) services use ArenaI found no evidence in this repository that they have ever called it. Arena is exercised only by its own tests, the k6 script and a manual smoke test. The API is written so that they can.
Any figure in the spec that is not in this tableA target, not a result.

1. The story: what is this project for?

Imagine an online shooting game. Some players cheat with an aimbot (software that aims for them) or a speedhack. A cheat-fighting platform needs a place that remembers things: who the players are, what happened in each match, who is ranked first, who was flagged, who was banned and why, and whether a banned player has appealed. Fairplay Arena is that place. It is a web service (a "backend") with 18 endpoints. It has no screen; other programs and tools talk to it over HTTP.

Players

Register, log in, see their own profile and stats, see the leaderboard, and appeal a ban.

Moderators

Humans who review a queue of flagged players, ban or clear them, and decide appeals.

Service accounts

Programs. telemetry-sim records matches and flags suspicious players. judge-agent investigates and may ban. These are the other two Fairplay projects; they are described here, but they are not part of this repository.

An everyday analogy

Think of a sports league office. It keeps the registry of players (Postgres), a scoreboard on the wall that anyone can read in a second (Redis), a locked disciplinary logbook where entries can be added but never erased (the audit log), and an appeals desk. The scoreboard is only a quick copy: if it falls off the wall, the office repaints it from the registry. The registry is the truth.

Callersplayers, moderators, telemetry-sim, judge-agent (HTTP + JWT)
→
ArenaSpring Boot service, 18 endpoints under /api/v1
→
PostgreSQL 17the truth: players, matches, audit log, appeals
&
Redis 7leaderboard copy: fast ranks

Four promises the design keeps

  1. PostgreSQL is the truth; Redis is a disposable copy. Redis is updated only after the database commit succeeds, and it can be rebuilt from the database at any time. If Redis is wrong, nothing is lost.
  2. History can only grow. The table of moderation actions is "append-only", and this is enforced by a database trigger, not just by careful code. Even a bug in Arena cannot rewrite or erase it.
  3. Every account status change goes through one rulebook. A small class, AccountStateMachine, says which moves are legal (for example you can CLEAR only a flagged player). Nothing else is allowed to change a status.
  4. A machine cannot ban on weak evidence. A service account (the Judge, the Telemetry simulator) can send BAN only with a confidence of at least 0.80. Below that, the request is refused with 422. Doubtful cases must be sent as FLAG or NOTE for a human to look at.
The API is a contract Two other services depend on the exact paths, JSON field names, enum values, status codes and error codes of these 18 endpoints. The project rule (CLAUDE.md) is: never rename or add to them.

2. Ideas you need first

If you already know a topic, skip it. Each one is short on purpose, and each one is something this project really uses.

2.1 HTTP, REST and JSON

A program talks to Arena by sending an HTTP request: a method (GET = read, POST = create or act, PATCH = change part of something), a path such as /api/v1/players/me, optional headers (for example Authorization: Bearer ...) and an optional body. The answer is an HTTP response: a status code and a body. Status codes used here: 200 OK, 201 Created, 400 bad input, 401 not logged in, 403 not allowed, 404 not found, 409 conflict, 422 "I understood you, but the rules refuse it".

A REST API is just a tidy way to name things: nouns in the path (/players, /matches), verbs in the method. The body is JSON, a text format for data: {"username": "neo_42", "rating": 1000}. Arena stays stateless: it keeps no memory of you between requests. Every request proves who you are again with a token (2.7).

2.2 Spring Boot, beans and annotations

Spring Boot is a framework: it starts a web server, reads settings, connects to the database and wires your classes together, so you write only the business code. Three words to know:

Request flow inside Arena is always the same three layers: controller (reads the HTTP request, checks the role, calls the service) → service (the business rules and the transaction) → repository (talks to the database). Data travels in DTOs (data transfer objects): small records that describe exactly the JSON going in and out, kept separate from the database entities.

Settings live in application.yml. A value like ${JWT_SECRET} means "read the environment variable JWT_SECRET". ${DB_URL:jdbc:...} means "use DB_URL, or this default if it is not set". The arena.* block is read into a typed Java object, ArenaProperties, which also validates it at startup (a too-short JWT secret stops the app from starting).

2.3 Java you will meet

The project uses Java 21. You do not need to be an expert, but you should recognise these:

ThingWhat it meansExample in this project
recordA small immutable data holder. record LoginRequest(String username, String password) automatically gets a constructor, accessors (request.username()), equals and toString.all DTOs, ArenaProperties, LeaderboardEvents.RatingChanged
enumA fixed list of allowed values.AccountStatus, ModerationActionType, Role
interfaceA promise of which methods exist. Spring Data creates the implementation of a repository interface for you.PlayerRepository extends JpaRepository<Player, UUID>
genericsTypes with a type in angle brackets. List<String> is "a List of String".PageResponse<T>
Optional<T>"A value, or nothing", instead of null.findByTokenHash(...) returns Optional<RefreshToken>
lambda and streamx -> x.getId() is a tiny inline function. A stream chains map, filter, toList over a collection.MatchService sorts participant ids with a stream
text blockA multi-line string between """. Used for SQL and JSON.PERCENTILE_SQL_TEMPLATE, every test body
pattern matchingif (raw instanceof Object[] elements) checks the type and names the variable in one step.StatDistributionService, GlobalExceptionHandler.extractUri
unchecked exceptionAn error you do not have to declare. ApiException extends RuntimeException.throw new ApiException(ErrorCode.PLAYER_NOT_FOUND, "...")
finalOn a field: assigned once. The project rule is private final for every service field. On a class with a private constructor: a utility class that nobody instantiates.RatingCalculator, CurrentUser
Java 21 extrasList.getLast(), Math.clamp(value, min, max), ExecutorService in try-with-resources, virtual threads.LeaderboardRebuilder, StatDistributionService, a test, application.yml
LombokA compile-time tool that writes boilerplate. Only @Getter, @Setter, @NoArgsConstructor(access = PROTECTED) and @Slf4j (gives a log field) are allowed. Never @Data on a database entity.Player, MatchService
Clock injectionCode never calls Instant.now(); it asks an injected java.time.Clock. Tests can then pass a fixed clock.Instant.now(clock) everywhere

2.4 PostgreSQL, JPA, Flyway and transactions

PostgreSQL is a relational database: data lives in tables with typed columns; constraints (NOT NULL, UNIQUE, CHECK, REFERENCES a foreign key) make the database itself reject bad data. Arena leans on this heavily: for example headshots <= kills is a CHECK in the schema as well as a rule in Java.

JPA / Hibernate maps a Java class to a table. A class marked @Entity with @Table(name = "players") is one table; each field marked @Column is a column; @ManyToOne is a foreign key. A Spring Data repository is an interface; you declare findById or write a @Query in JPQL (SQL written over entity names) and Spring generates the code. Setting ddl-auto: validate means Hibernate checks at startup that the entities match the real schema and refuses to start if they do not; it never changes the schema.

Flyway owns the schema. Files in src/main/resources/db/migration named V1__init.sql, V2__... run once, in order, and Flyway remembers which have run. To change the schema you add V3; you never edit V1.

JdbcClient is Spring's plain-SQL helper. Arena uses JPA for ordinary reads and writes, and JdbcClient where the SQL is special: percentile cut points, the "latest action per player" queue, the database rank lookup and the leaderboard rebuild.

A transaction is a group of database changes that either all happen or none do ("commit" or "rollback"). Marking a service method @Transactional wraps it in one. @Transactional(readOnly = true) tells Spring it only reads. Two places use a TransactionTemplate instead (the same thing, done by hand in code) because they need control the annotation cannot give: MatchService must catch an error after its transaction has finished, and AuthService must commit a revocation in its own, separate transaction before an exception is thrown (see 5.5 and 5.3).

2.5 SQL tricks this project uses

2.6 Redis and the sorted set

Redis is an in-memory data store; reads take microseconds. Arena uses one structure, a sorted set (ZSET) under the key leaderboard:global. Each member is a player's UUID text and its score is the rating. Redis keeps members ordered by score, so it can answer "what is this member's rank?" in O(log N) time (roughly "a handful of steps even with a million members"). The commands used: ZADD (add or update), ZREM (remove), ZREVRANK (rank, highest first, 0-based), ZSCORE, ZCARD (count), ZREVRANGE ... WITHSCORES (a page), RENAME (atomically swap a key).

When two members have the same score, Redis orders them by the member text, byte by byte. In reverse order (highest first) the larger text comes first. The SQL rank query copies that rule exactly.

2.7 Login, JWT, refresh tokens, bcrypt and roles

2.8 Events and "after commit"

The service code publishes a small event object (RatingChanged(playerId, rating)) with ApplicationEventPublisher. Another class listens. The listener in LeaderboardSync is marked @TransactionalEventListener(phase = AFTER_COMMIT), which means: do not run until the database transaction has really committed. If the transaction rolls back, the event is simply dropped. That is how Redis never receives a rating that the database refused.

The price: if the application crashes in the tiny gap between the commit and the Redis write, Redis stays out of date until the next rebuild. The README lists a "transactional outbox" (a table of pending events) as a future fix. It is not built.

2.9 Locks, versions and threads

2.10 Errors as ProblemDetail

Every failed request gets the same JSON shape, RFC 7807 "problem details" (content type application/problem+json): type, title, status, detail, instance and a project-specific code such as CONFIDENCE_TOO_LOW. Clients are meant to switch on code, not on the human text. A stack trace is never returned.

2.11 JUnit, MockMvc, Testcontainers and AssertJ

2.12 Maven, JaCoCo, Docker, Prometheus

2.13 Language and framework things you will meet (cheat sheet)

You will seeIt meansExample here
@RestController, @RequestMapping, @GetMapping, @PostMappingA class that answers HTTP requests; the URL and method it answers.AuthController
@RequestBody, @PathVariable, @RequestParamTake a value from the JSON body, from the URL path, or from ?name=value.PlayerController.search
@Valid + @NotBlank, @Size, @Min, @PatternAutomatic input checks; a failure becomes 400 VALIDATION_FAILED.RegisterRequest
@AuthenticationPrincipal Jwt jwtHands the verified token to the method; CurrentUser.id(jwt) reads the player id.every "me" endpoint
@PreAuthorize("hasAnyRole('MODERATOR','SERVICE')")Role check before the method runs.ModerationController
@TransactionalRun the method in one database transaction.AuthService.register
@Entity, @Id, @Column, @ManyToOne, @Version, @Enumerated(STRING)Map a class and its fields to a table, a foreign key, an optimistic-lock counter, and an enum stored as text.Player
@ConfigurationProperties("arena")Read the arena.* settings into a typed record.ArenaProperties
@EventListener(ApplicationReadyEvent.class), @ScheduledRun once when the app is ready; run repeatedly on a timer.StatDistributionService.refresh
@TransactionalEventListener(AFTER_COMMIT)React to an event only after the commit succeeded.LeaderboardSync
@RestControllerAdvice, @ExceptionHandlerOne class that turns exceptions into JSON error responses.GlobalExceptionHandler
@MapperMapStruct generates a converter.PlayerMapper
@JsonInclude(NON_NULL)Leave out JSON fields that are null (for example email on other people's profiles).most DTOs
com.fasterxml.jackson.annotation vs tools.jackson.databindSpring Boot 4 uses Jackson 3, whose engine moved to tools.jackson.*. The tiny annotations package kept its old name, so @JsonInclude still imports from com.fasterxml...annotation. The project's own check only searches for the old databind package, and finds nothing.PageResponse vs ModerationService

3. Map of the repository

Almost all the real work is in arena/. The rest of the top folder is the plan, notes, and one unrelated leftover.

Project 1/ ├─ CLAUDE.md instructions for the coding assistant (not part of Arena) ├─ handoff.md, todo.md live status notes: read these first when you resume ├─ Fairplay Arena — Implementation Specification.md the plan and the API contract ├─ Code Explanation/ this guide, plus the older reference page "code guide.html" ├─ index.html, package.json, vite.config.ts, src/, public/, ... │ an EMPTY Google AI Studio React stub. Not connected to Arena. Ignore it. └─ arena/ THE PROJECT [built] ├─ pom.xml, mvnw, .mvn/ Maven build (Spring Boot 4.1.2, Java 21) ├─ Dockerfile, .dockerignore, compose.yaml, .env.example │ container image and the Postgres + Redis + Arena stack ├─ .github/workflows/ci.yml CI workflow [written, never run] ├─ ops/prometheus.yml tells Prometheus where to scrape metrics ├─ scripts/seed-1m-players.sql makes 1,000,000 players for the benchmark ├─ benchmark/rank-lookup.js the k6 load-test script ├─ README.md features, endpoint table, benchmark results └─ src/ ├─ main/resources/ │ ├─ application.yml every setting │ └─ db/migration/V1__init.sql, V2__audit_log_append_only.sql the schema [built] ├─ main/java/dev/fairplay/arena/ │ ├─ ArenaApplication.java starts Spring │ ├─ config/ typed settings, JWT, security rules, clock, Swagger [built] │ ├─ common/ error handling, CurrentUser, PageResponse [built] │ ├─ auth/ register, login, refresh, tokens, account seeding [built] │ ├─ player/ profiles, stats, percentiles, search [built] │ ├─ match/ record a match, match history [built] │ ├─ leaderboard/ rating formula, Redis sync and rebuild, ranks [built] │ ├─ moderation/ state machine, actions, queue, audit history [built] │ └─ appeal/ submit and decide appeals [built] └─ test/java/dev/fairplay/arena/ 15 test files, 71 tests [built]

Recommended reading order

  1. application.yml and V1__init.sql: the settings and the six tables. Everything else is built on these.
  2. moderation/AccountStateMachine.java: the shortest file with the most important rules.
  3. leaderboard/RatingCalculator.java: twenty lines of arithmetic.
  4. match/MatchService.java: the most interesting service (locking, idempotency, events).
  5. leaderboard/LeaderboardSync.java, LeaderboardService.java, LeaderboardRebuilder.java.
  6. auth/AuthService.java and TokenService.java, with config/JwtConfig.java and SecurityConfig.java.
  7. moderation/ModerationService.java, then appeal/AppealService.java.
  8. The tests, starting with support/AbstractIntegrationTest.java (section 7).

4. The journey of one match, from request to leaderboard

The telemetry service has just seen a 2-player match finish and tells Arena. This is POST /api/v1/matches, the busiest write path. The numbers below are the real order of events.

1. Clientsends JSON + Authorization: Bearer ...
→
2. Security filterSecurityConfig, JwtConfig
→
3. ControllerMatchController: @Valid, @PreAuthorize
→
4. ServiceMatchService: transaction, locks, ratings
→
5. CommitPostgreSQL
→
6. After commitLeaderboardSync → Redis ZADD
  1. Earlier, the caller logged in. POST /auth/login → AuthService.login checks the bcrypt hash and returns an access token (15 minutes) made by TokenService.issueAccessToken, plus a refresh token.
  2. The request arrives with the bearer token. The security filter chain built in SecurityConfig.api sees that /api/v1/matches is not in the public list, so it needs a valid login. The JwtDecoder from JwtConfig checks four things: the HS256 signature, the issuer fairplay-arena, that the token is not expired, and that typ equals "access". A refresh token used here fails (401). The roles claim becomes the authority ROLE_SERVICE.
  3. Spring routes to MatchController.recordMatch. First it parses the JSON into RecordMatchRequest and runs the @Valid checks (for example 2 to 100 participants, kills >= 0). Bad input stops here with 400 VALIDATION_FAILED. Then @PreAuthorize("hasRole('SERVICE')") runs: a PLAYER token gets 403 FORBIDDEN.
  4. The controller calls MatchService.recordMatch(request, recorderId) and gives it the id from the token (CurrentUser.id(jwt)).
  5. A transaction starts (a TransactionTemplate, so a unique-key error can be caught outside it). validateRequest checks the rules the annotations cannot: endedAt after startedAt, no duplicate player, placements exactly 1..N, headshots <= kills, shotsHit <= shotsFired. Failure: 400 VALIDATION_FAILED.
  6. Idempotency check. If a match with this externalId already exists, return it with created = false. The controller answers 200, not 201, and nothing changes.
  7. Lock the players. The participant ids are sorted, then findAllByIdInForUpdate runs SELECT ... FOR UPDATE ORDER BY id. Unknown id: 404 PLAYER_NOT_FOUND. A banned, appealed or non-player account: 422 PLAYER_NOT_ELIGIBLE.
  8. Insert the match (saveAndFlush). The database's UNIQUE (external_id) is checked now. If two requests raced, the loser fails here; see step 11.
  9. For each participant: RatingCalculator.delta gives the rating change, applyDelta adds it (never below 0), the player's running totals (kills, deaths, shots, reaction sum) are increased, a MatchParticipant row is built with ratingBefore and ratingAfter, and a RatingChanged event is published. The event waits.
  10. Save, count, log. saveAll(participants); the Micrometer counter arena.matches.recorded goes up by one; an INFO log line is written.
  11. Commit. The transaction ends and the locks are released. Only now do the waiting events run: LeaderboardSync.onRatingChanged calls ZADD leaderboard:global <rating> <playerId> for each participant. If Redis fails, the error is logged, arena.leaderboard.sync.failures counts it, and the HTTP answer is still a success, because the database already has the truth. Race loser: the unique violation surfaces as DataIntegrityViolationException after rollback; recordMatch catches it, loads the winner's match and returns it with created = false (200).
  12. The controller builds the response: 201 Created with a Location: /api/v1/matches/<id> header and the MatchResponse body.
  13. If anything threw an ApiException, GlobalExceptionHandler turned it into application/problem+json with the right status and code.
Later: a player asks for their rank GET /api/v1/leaderboard/players/{id} is public. By default (source=redis) LeaderboardService asks Redis (ZREVRANK, ZSCORE, ZCARD) and answers in a few milliseconds. With source=db it counts rows in PostgreSQL instead. Both exist so the benchmark can compare them, and a test proves they give the same answer.

5. Module by module, file by file

Each subsection gives the file's job, a real excerpt, a plain-words walkthrough, why it is written this way, pitfalls and what the tests prove. Trivial files are grouped in a table at the end (5.10).

5.1 Config and startup (config/, ArenaApplication)

ArenaProperties: every setting, validated

Job: turn the arena.* block of application.yml into a typed, validated Java object.

arena/src/main/java/dev/fairplay/arena/config/ArenaProperties.java
@Validated
@ConfigurationProperties("arena")
public record ArenaProperties(
        @NotNull @Valid Jwt jwt,
        @NotNull @Valid Rating rating,
        ...
) {
    public record Jwt(
            @NotBlank @Size(min = 32) String secret,
            @NotBlank String issuer,
            @NotNull Duration accessTokenTtl,
            @NotNull Duration refreshTokenTtl
    ) {}
    ...
    public record Moderation(
            @NotNull @DecimalMin("0.0") @DecimalMax("1.0") BigDecimal serviceBanMinConfidence
    ) {}
}

Walkthrough. @ConfigurationProperties("arena") says "fill this record from keys under arena:". Nested records (Jwt, Rating, ...) match the nested YAML. @Validated plus the constraint annotations make Spring check the values at startup. Duration reads text such as 15m or 7d. @ConfigurationPropertiesScan on ArenaApplication is what finds this record.

Why: failing fast is better than discovering a 3-character signing secret in production. Every other class receives this record instead of reading raw strings. Pitfall: if another property source sets one entry of a list (arena.accounts.services[0].password), Boot replaces the whole list from application.yml; it does not merge. So the test settings must also set services[n].username. This bit the project once (section 10). Tests: every integration test starts the app with these constraints active; TokenServiceTest builds the record by hand.

ClockConfig and the injected Clock

arena/src/main/java/dev/fairplay/arena/config/ClockConfig.java
@Bean
Clock clock() {
    return Clock.systemUTC();
}

One bean, so all code can say Instant.now(clock). Why: a test can build the same service with Clock.fixed(...) and get a predictable time. Pitfall: only your code uses this clock. A library, such as the JWT decoder's expiry check, still reads the real time, which is exactly what broke TokenServiceTest (section 0.1).

JwtConfig: signing and checking tokens

Job: build the encoder that signs tokens, the decoder that verifies them, and the converter that turns the roles claim into Spring authorities.

arena/src/main/java/dev/fairplay/arena/config/JwtConfig.java
@Bean
JwtDecoder jwtDecoder(SecretKey key, ArenaProperties props) {
    NimbusJwtDecoder decoder = NimbusJwtDecoder.withSecretKey(key)
            .macAlgorithm(MacAlgorithm.HS256)
            .build();
    OAuth2TokenValidator<Jwt> accessOnly = jwt ->
            "access".equals(jwt.getClaimAsString("typ"))
                    ? OAuth2TokenValidatorResult.success()
                    : OAuth2TokenValidatorResult.failure(
                            new OAuth2Error("invalid_token", "Not an access token", null));
    decoder.setJwtValidator(new DelegatingOAuth2TokenValidator<>(
            JwtValidators.createDefaultWithIssuer(props.jwt().issuer()),
            accessOnly));
    return decoder;
}

Walkthrough. The decoder is told: only HS256, signed with our secret key. Two validators are chained: the default pair (expiry plus issuer must be fairplay-arena) and a small lambda that insists typ is "access". The converter (further down in the file) sets authoritiesClaimName("roles") and prefix ROLE_, so the claim ["MODERATOR"] becomes the authority ROLE_MODERATOR, which is what hasRole('MODERATOR') checks.

Why the typ check: refresh tokens are random text, not JWTs, so they would fail the signature anyway. The extra check is defence in depth: if one day a different kind of JWT is signed with the same key, it cannot be used as a login. Tests: AuthIntegrationTest sends a refresh token as a Bearer token and expects 401 UNAUTHENTICATED; SecurityIntegrationTest sends a token minted with a clock in 2020 and expects 401.

SecurityConfig: who may call what

arena/src/main/java/dev/fairplay/arena/config/SecurityConfig.java
http.csrf(csrf -> csrf.disable())
        .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
        .authorizeHttpRequests(auth -> auth
                .requestMatchers(HttpMethod.POST, "/api/v1/auth/**").permitAll()
                .requestMatchers(HttpMethod.GET, "/api/v1/leaderboard", "/api/v1/leaderboard/**").permitAll()
                .requestMatchers(
                        "/actuator/health/**",
                        "/actuator/prometheus",
                        "/v3/api-docs/**",
                        "/swagger-ui/**",
                        "/swagger-ui.html").permitAll()
                .anyRequest().authenticated())
        .oauth2ResourceServer(rs -> rs
                .jwt(jwt -> jwt.jwtAuthenticationConverter(converter))
                .authenticationEntryPoint(entryPoint))

Walkthrough. Public: the three auth endpoints (POST only), the two leaderboard reads (GET only), health, metrics and the API docs. Everything else needs a valid token. CSRF protection is switched off and no session is created, because this is a token-based API with no browser cookies. The finer, per-role rules are @PreAuthorize on each controller method (@EnableMethodSecurity turns that on). The same file defines PasswordEncoder as BCryptPasswordEncoder.

Why two layers: URL rules answer "do you need to be logged in at all?"; @PreAuthorize answers "which role?". Pitfalls: (1) /actuator/prometheus is open for easy local scraping; the README warns to restrict it in production. (2) Because @PreAuthorize runs after the body is parsed and validated, a caller with the wrong role and an invalid body gets 400, not 403. A role test must send a valid body. This is in todo.md as an optional improvement. Tests: SecurityIntegrationTest checks 401 with no token, 403 for a PLAYER on endpoints 8 and 13, public leaderboard access, an expired token, and that Swagger lists exactly 18 operations.

5.2 Errors (common/error/)

Job: make every failure look the same: a ProblemDetail with a stable code.

arena/src/main/java/dev/fairplay/arena/common/error/ErrorCode.java
CONFIDENCE_REQUIRED(HttpStatus.valueOf(422), "Confidence required"),
CONFIDENCE_TOO_LOW(HttpStatus.valueOf(422), "Confidence too low"),
...
public URI typeUri() {
    return URI.create("https://fairplay.dev/errors/" + name().toLowerCase().replace('_', '-'));
}

An enum with 27 values; each carries an HTTP status and a title, and builds the type URI (CONFIDENCE_TOO_LOW becomes .../confidence-too-low). Code anywhere in the app throws new ApiException(ErrorCode.X, "message"); ApiException is a plain RuntimeException carrying the code.

arena/src/main/java/dev/fairplay/arena/common/error/GlobalExceptionHandler.java
@ExceptionHandler(ApiException.class)
ResponseEntity<ProblemDetail> handleApiException(ApiException ex, HttpServletRequest request) {
    ProblemDetail problem = buildProblem(ex.getErrorCode(), ex.getMessage(), request.getRequestURI());
    return ResponseEntity.status(ex.getErrorCode().getStatus())
            .contentType(PROBLEM_JSON)
            .body(problem);
}
...
static ProblemDetail buildProblem(ErrorCode errorCode, String detail, String instanceUri) {
    ProblemDetail problem = ProblemDetail.forStatusAndDetail(errorCode.getStatus(), detail);
    problem.setType(errorCode.typeUri());
    problem.setTitle(errorCode.getTitle());
    ...
    problem.setProperty("code", errorCode.name());
    return problem;
}

Walkthrough. @RestControllerAdvice makes this class catch exceptions thrown from any controller. There is one handler per kind: ApiException (our own), AccessDeniedException (403), ConstraintViolationException and several Spring MVC exceptions (400 with an errors list of {field, message}), ObjectOptimisticLockingFailureException (409 CONCURRENT_MODIFICATION), DataIntegrityViolationException, and a last-resort Exception handler (500, logs the stack trace, but returns only "Unexpected error"). The class extends Spring's ResponseEntityExceptionHandler and overrides its methods so that built-in errors (bad JSON, wrong method, unknown route) are also reshaped.

Two special cases. (a) handleDataIntegrity looks for the index name ux_players_username_lower or ux_players_email_lower inside the database message. If found it answers 409 USERNAME_TAKEN or EMAIL_TAKEN. That covers the race where two registrations pass the "does it exist?" check at the same moment, and the unique index decides. It is a string match on the database message, so renaming those indexes would silently turn these into 500s. (b) Errors from the security filters happen before Spring MVC, so @RestControllerAdvice never sees them. That is why ProblemAuthenticationEntryPoint (401) and ProblemAccessDeniedHandler (403) exist: they write the same JSON by hand with JsonMapper.

Tests: ErrorHandlingIntegrationTest checks an unknown route (404 NOT_FOUND), malformed JSON (400 MALFORMED_REQUEST), unknown player, a bad source value, and a 405, each as application/problem+json with a code. It uses an authenticated DELETE for the 405, because an anonymous one is stopped earlier with 401. Several other tests assert $.code too.

5.3 auth: register, login, refresh, tokens

AuthService: the three account operations

Job: create players, check passwords and hand out tokens, rotating refresh tokens safely. AuthController only forwards to it.

arena/src/main/java/dev/fairplay/arena/auth/AuthService.java (register)
@Transactional
public PlayerDetailResponse register(RegisterRequest request) {
    if (playerRepository.existsByUsernameIgnoreCase(request.username())) {
        throw new ApiException(ErrorCode.USERNAME_TAKEN, "Username is already taken");
    }
    ...
    Player player = new Player(
            UUID.randomUUID(),
            request.username(),
            request.email(),
            passwordEncoder.encode(request.password()),
            Role.PLAYER,
            AccountStatus.ACTIVE,
            ...
            props.rating().initial(),
            now);
    playerRepository.saveAndFlush(player);
    eventPublisher.publishEvent(new RatingChanged(player.getId(), player.getRating()));
    return playerService.toDetail(player, true);
}

Walkthrough. Check the username and email are free (case-insensitively), build the Player with a fresh UUID, a bcrypt hash, role PLAYER, status ACTIVE and the starting rating (1000 from arena.rating.initial), save it, and publish a RatingChanged event so the new player appears on the leaderboard once the commit succeeds. The role is always PLAYER; nothing in the API can create a moderator. Why saveAndFlush: it sends the INSERT immediately, so a duplicate that slipped past the "exists" check fails inside this method, where the exception handler turns it into 409. Test: registersPlayerAndJoinsLeaderboard checks the 201, the Location header, the rating 1000 and that Redis really holds a score of 1000.0 for the new id; rejectsDuplicateUsernameAndEmailCaseInsensitively registers NEO_42 against an existing neo_42.

arena/src/main/java/dev/fairplay/arena/auth/AuthService.java (refresh)
Instant now = Instant.now(clock);
// Expiry is checked before reuse: an expired token is a plain INVALID_REFRESH_TOKEN and must
// not trigger the mass revocation that a replayed (revoked but unexpired) token does.
if (!existing.getExpiresAt().isAfter(now)) {
    throw new ApiException(ErrorCode.INVALID_REFRESH_TOKEN, "Refresh token expired");
}
if (existing.getRevokedAt() != null) {
    UUID playerId = existing.getPlayer().getId();
    requiresNewTx.executeWithoutResult(status ->
            refreshTokenRepository.revokeAllActiveForPlayer(playerId, now));
    throw new ApiException(ErrorCode.REFRESH_TOKEN_REUSED, "Refresh token was already used");
}
...
existing.setRevokedAt(now);
existing.setReplacedBy(replacementId);

Walkthrough, in order. (1) Hash the presented token with SHA-256 and look the hash up; unknown means 401 INVALID_REFRESH_TOKEN. (2) If it is expired, the same code, and nothing else happens. (3) If it was already revoked, someone is replaying an old token: revoke every active token of that player, then answer 401 REFRESH_TOKEN_REUSED. (4) Otherwise create a replacement, mark the old one revoked (revokedAt) and point it at the new one (replacedBy), and return a new access token plus the new refresh token.

Why requiresNewTx: the reuse branch ends by throwing. A thrown exception makes the surrounding @Transactional roll back, which would also undo the mass revocation. So the revocation runs in its own, separate transaction (PROPAGATION_REQUIRES_NEW) that commits first. Why the expiry check comes first: an old token that is both expired and revoked is probably an honest client with a stale token, not a thief, and should not log out every session of that player.

Pitfalls. Login never looks at the account status: banned players must be able to log in, or they could not appeal. (My reading of the code: an unknown username returns before the bcrypt comparison, so the response is faster than for a wrong password; the JSON body is identical, but the timing could in theory reveal which usernames exist. I did not measure this.) Also, RefreshToken has no version column or lock, so I believe two simultaneous refreshes of the same valid token could both succeed. No test covers that; it is a gap I read in the code, not something I ran.

Tests: loginRotatesAndDetectsRefreshReuse: two logins, rotate the first token, replay it, and see REFRESH_TOKEN_REUSED; then the second session's token is also dead. expiredRefreshTokenIsInvalidAndDoesNotTriggerMassRevocation: an expired, revoked token gives plain INVALID_REFRESH_TOKEN, and the other session's token still works.

TokenService: making and hashing tokens

arena/src/main/java/dev/fairplay/arena/auth/TokenService.java
JwtClaimsSet claims = JwtClaimsSet.builder()
        .issuer(props.jwt().issuer())
        .subject(player.getId().toString())
        .issuedAt(now)
        .expiresAt(expiresAt)
        .claim("username", player.getUsername())
        .claim("roles", List.of(player.getRole().name()))
        .claim("typ", "access")
        .build();
...
public String generateRefreshToken() {
    byte[] bytes = new byte[32];
    SECURE_RANDOM.nextBytes(bytes);
    return BASE64_URL.encodeToString(bytes);
}
...
byte[] hashed = digest.digest(rawToken.getBytes(StandardCharsets.UTF_8));
return HexFormat.of().formatHex(hashed);

The access token is a signed JWT with the claims from 2.7 and a lifetime from arena.jwt.access-token-ttl. The refresh token is 32 random bytes from SecureRandom written as URL-safe Base64 (43 characters); only its SHA-256 hex hash (64 characters) is stored, in a CHAR(64) UNIQUE column. Why SHA-256 and not bcrypt for this one: the token already has 256 bits of randomness, so there is nothing to brute-force, and the hash must be fast and deterministic so it can be looked up. Tests: TokenServiceTest (2 tests): one checks claims, header and expiry; the other checks the 43-character shape, the 64-hex hash and the 7-day expiry. Today the first one errors (section 0.1); the second passes.

RefreshToken, RefreshTokenRepository, AccountSeeder

RefreshToken is the entity for table refresh_tokens (id, player, tokenHash, expiresAt, revokedAt, replacedBy). RefreshTokenRepository.findByTokenHash uses join fetch t.player to load the owner in the same query, and revokeAllActiveForPlayer is one bulk update that sets revokedAt on every token of a player that is not yet revoked.

arena/src/main/java/dev/fairplay/arena/auth/AccountSeeder.java
@Override
@Transactional
public void run(ApplicationArguments args) {
    ArenaProperties.AccountCredential mod = props.accounts().moderator();
    seedIfMissing(mod.username(), mod.password(), Role.MODERATOR);
    for (ArenaProperties.AccountCredential service : props.accounts().services()) {
        seedIfMissing(service.username(), service.password(), Role.SERVICE);
    }
}

An ApplicationRunner runs once at startup. It creates the moderator mod-admin and the service accounts telemetry-sim and judge-agent if they do not exist, taking passwords from the environment. Existing accounts are never touched, and seeded accounts are never placed on the leaderboard (no event is published, and their role is not PLAYER). Note: the tests truncate the players table before each test, which removes these accounts, so tests that need them create their own with TestDataFactory.

5.4 player: profiles, stats, percentiles, search

Player (the entity) and PlayerRepository

arena/src/main/java/dev/fairplay/arena/player/Player.java
@Version
@Column(nullable = false)
private Long version;
...
public boolean isEligibleForMatchAndRanking() {
    return role == Role.PLAYER
            && status != AccountStatus.BANNED
            && status != AccountStatus.APPEALED;
}

One row per account (players, the moderator and the services all live in players, told apart by role). It stores the running totals (totalKills, totalShotsFired, sumReactionMs and so on) instead of recalculating from every match. @Version is the optimistic-lock counter (2.9). isEligibleForMatchAndRanking() is the single definition of "may play and may be ranked", used by MatchService and LeaderboardService. Note that a FLAGGED player is still eligible: suspected is not banned.

PlayerRepository holds the queries. Two are worth noticing: findAllByIdInForUpdate (@Lock(PESSIMISTIC_WRITE) plus order by p.id) is the row-locking query used by match recording; and searchPlayers finds players by username prefix and optional status, ordered by rating.

PlayerService: stats and search

arena/src/main/java/dev/fairplay/arena/player/PlayerService.java
public static PlayerStats computeStats(Player player) {
    long kills = player.getTotalKills();
    long deaths = player.getTotalDeaths();
    double kdRatio = round4((double) kills / Math.max(deaths, 1L));
    double headshotRate = kills == 0 ? 0.0 : round4((double) player.getTotalHeadshots() / kills);
    long shotsFired = player.getTotalShotsFired();
    double accuracy = shotsFired == 0 ? 0.0 : round4((double) player.getTotalShotsHit() / shotsFired);
    Integer avgReactionMs = player.getMatchesPlayed() == 0
            ? null
            : (int) (player.getSumReactionMs() / player.getMatchesPlayed());
    return new PlayerStats(kills, deaths, kdRatio, headshotRate, accuracy, avgReactionMs);
}

Walkthrough. The stats are derived on every read from the totals, never stored. The guards avoid dividing by zero: deaths are floored at 1, rates are 0 when the denominator is 0, and the average reaction time is null (the JSON field disappears) before any match. round4 uses BigDecimal with HALF_UP to 4 decimals. Section 9 works one through with real numbers.

getMe shows your own e-mail; getById passes includeEmail = false, so other people's profiles omit it. updateMe refuses banned or appealed accounts with 403 ACCOUNT_SUSPENDED and changes only the fields that were sent. search lowercases the query and escapes the characters !, % and _ before using it in LIKE ... escape '!', so a user typing _ searches for a real underscore instead of "any character". Tests: PlayerIntegrationTest: /me includes e-mail while /{id} does not, PATCH works, a banned player is refused (ACCOUNT_SUSPENDED), and the search q=NEO_&status=FLAGGED finds only neo_2 while q=neo_ returns both, highest rating first.

StatDistributionService: "how do I compare with everyone?"

Job: turn a raw value (say a 0.504 headshot rate) into a percentile from 0 to 100 without scanning a million rows on each request.

arena/src/main/java/dev/fairplay/arena/player/StatDistributionService.java
@EventListener(ApplicationReadyEvent.class)
@Scheduled(fixedDelayString = "${arena.stats.refresh-interval}")
public void refresh() { ... }

static int percentile(double[] cutPoints, double value) {
    int lo = 0;
    int hi = cutPoints.length;
    while (lo < hi) {
        int mid = (lo + hi) >>> 1;
        if (cutPoints[mid] <= value) {
            lo = mid + 1;
        } else {
            hi = mid;
        }
    }
    return Math.clamp(lo - 1, 0, 100);
}

Walkthrough. refresh() runs once when the app is ready and then every 60 seconds. For each of three metrics (headshot rate, accuracy, average reaction time) it asks PostgreSQL for 101 cut points: percentile_cont over the players who are PLAYERs, not banned or appealed, with at least 5 matches. The three arrays are stored together in an immutable Distribution inside an AtomicReference, so a request thread always sees a complete snapshot, never a half-built one. percentile() is a binary search that counts how many cut points are <= value; the percentile is that count minus 1, kept between 0 and 100. For reaction time, lower is better, so the API reports reactionSpeed = 100 - percentile. Percentiles are null for a player with fewer than 5 matches, or before the first refresh.

The empty-database bug (a real surprise). On a brand-new database nobody qualifies, so percentile_cont returns NULL. Spring's JdbcClient rejects a null returned from a result extractor, and since refresh() runs at ApplicationReadyEvent, the whole app crashed at first startup. The unit tests could not see it; running the full stack did. The fix is visible in queryPercentiles: the extractor returns an Optional<double[]>, and the method ends with .orElse(null), so "no data yet" simply means "no percentiles yet". Tests: StatDistributionServiceTest (2 unit tests, with a mocked JdbcClient) feeds artificial cut points and checks the edges and the inversion; the integration test shows percentiles are absent after 4 matches and present after the 5th.

PlayerController, PlayerMapper

PlayerController has four endpoints (4 to 7). PATCH /me requires PLAYER; GET /players (search) requires MODERATOR or SERVICE; the page size is capped by @Max(100). PlayerMapper is a MapStruct interface: you declare the method and the generated class does the copying (it is excluded from the JaCoCo count).

5.5 match: recording a match and reading history

MatchService.recordMatch: one transaction, driven by hand

Job: store a finished match and update every participant's rating and totals, safely, even if the same match is sent twice or two requests race.

arena/src/main/java/dev/fairplay/arena/match/MatchService.java
public RecordResult recordMatch(RecordMatchRequest request, UUID recorderId) {
    try {
        return recordTx.execute(status -> doRecordMatch(request, recorderId));
    } catch (DataIntegrityViolationException ex) {
        Optional<Match> winner = matchRepository.findByExternalId(request.externalId());
        if (winner.isPresent()) {
            return new RecordResult(toResponse(winner.get()), false);
        }
        throw ex;
    }
}

Walkthrough. recordTx is a TransactionTemplate: "run this lambda inside a transaction". If it throws, the transaction rolls back and the exception comes out here, outside the transaction. The catch handles one specific case: two requests with the same externalId both passed the "already exists?" check; one inserted first, the other hit the unique constraint on matches.external_id. PostgreSQL marks that second transaction as aborted, so you cannot query inside it any more. After the rollback, the code looks up the winner's match and returns it with created = false, which the controller answers as 200 instead of a 500.

Why not @Transactional? With the annotation, the exception would leave the method together with the rollback and there would be no place to catch it inside the same method. Driving the transaction by hand makes the "catch after rollback" possible. This is the best example in the project of a choice that looks odd and has a short comment explaining it.

arena/src/main/java/dev/fairplay/arena/match/MatchService.java (inside doRecordMatch)
List<UUID> sortedIds = request.participants().stream()
        .map(ParticipantRequest::playerId)
        .sorted()
        .toList();

List<Player> lockedPlayers = playerRepository.findAllByIdInForUpdate(sortedIds);
...
for (ParticipantRequest pReq : request.participants()) {
    Player player = playersById.get(pReq.playerId());
    int ratingBefore = player.getRating();
    int delta = RatingCalculator.delta(participantCount, pReq.placement(), maxDelta);
    int ratingAfter = RatingCalculator.applyDelta(ratingBefore, delta);

    player.setRating(ratingAfter);
    player.setMatchesPlayed(player.getMatchesPlayed() + 1);
    player.setTotalKills(player.getTotalKills() + pReq.kills());
    ...
    eventPublisher.publishEvent(new RatingChanged(player.getId(), ratingAfter));
}
participantRepository.saveAll(savedParticipants);

Walkthrough. Collect the ids and sort them; ask the database for those rows with FOR UPDATE ... ORDER BY id. Now no other transaction can change those players until this one ends. Then, for each participant, compute the rating change, apply it, add the match numbers to the running totals, and publish the event that will update Redis after the commit. The player objects are "managed" by JPA: changing a field is enough, because Hibernate writes the changes when the transaction commits.

Why sorted? Imagine match A has players {1, 2} and match B has {2, 1} at the same moment. Without a fixed order, A could lock 1 and wait for 2 while B locks 2 and waits for 1: a deadlock. If both always lock in id order, the second simply waits for the first. Why lock at all? Two matches that include the same player would otherwise read the same old rating and one update would overwrite the other.

Pitfalls. (1) The validation rules (placements 1..N, headshots <= kills, ...) are in validateRequest because annotations cannot compare two fields. (2) The concurrency test passes, but whether a particular run actually reaches the unique-violation path depends on timing; todo.md says so. What the test proves for sure are the invariants: exactly one created result, exactly one row in matches, and each player's matchesPlayed equal to 1. (3) The rating system is intentionally simple: it depends only on placement and the number of participants, not on the opponents' ratings.

Tests (MatchIntegrationTest, 3 tests). recordsMatchUpdatesRatingsTotalsRedisAndIsIdempotent: a 2-player match gives ratings 1030 and 970, the replay returns 200 and nothing doubles, total_kills is 14, Redis scores are 1030.0 and 970.0, and the history shows participantCount = 2. validatesMatchRulesAndEligibility: bad placements, duplicate player and headshots > kills each give 400 VALIDATION_FAILED; a banned participant gives 422 PLAYER_NOT_ELIGIBLE. concurrentRequestsWithSameExternalIdCreateOneMatchAndReplayTheOther: two threads start together on a latch.

Match, MatchParticipant, repositories, controller

Match maps matches; MatchParticipant maps match_participants, whose primary key is two columns (match_id, player_id). In JPA that is an @EmbeddedId (MatchParticipantId, a small class with equals/hashCode) combined with @MapsId so the key and the two foreign keys share the same columns. MatchParticipantRepository.findPlayerMatches builds PlayerMatchResponse objects directly in JPQL (select new ...) and counts participants with a sub-select. MatchController has endpoints 8 to 10 and decides 201 versus 200 from result.created().

5.6 leaderboard: ratings, Redis, ranks

RatingCalculator: the formula

arena/src/main/java/dev/fairplay/arena/leaderboard/RatingCalculator.java
double numerator = participantCount + 1.0 - (2.0 * placement);
double denominator = participantCount - 1.0;
return (int) Math.round(maxDelta * (numerator / denominator));
...
public static int applyDelta(int currentRating, int delta) {
    return Math.max(0, currentRating + delta);
}

Walkthrough. With N players and a finishing place p (1 = best), the change is round(30 * (N + 1 - 2p) / (N - 1)). Winner: always +30. Last place: always -30. Middle places are spread evenly between. Examples from the tests: N=4 gives +30, +10, -10, -30; N=10, place 5 gives +3, place 6 gives -3. A rating never goes below 0. It is a pure class with only static methods and no Spring, so a unit test can check it in milliseconds. It throws IllegalArgumentException for fewer than 2 players or a place outside 1..N.

Pitfall: because Java's Math.round rounds half upwards, the changes are not always perfectly balanced: exercise 5 in section 12 shows places 2 and 8 of a 9-player match getting +23 and -22, so the changes do not cancel exactly (over all nine places the sum is +2). Tests: RatingCalculatorTest has 12 cases: 10 rows of (N, place, expected), the floor at 0 (10 - 30 gives 0; 50 - 30 gives 20), and the three invalid inputs.

LeaderboardEvents and LeaderboardSync: keeping Redis in step

arena/src/main/java/dev/fairplay/arena/leaderboard/LeaderboardSync.java
@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
public void onRatingChanged(RatingChanged event) {
    try {
        redisTemplate.opsForZSet().add(
                leaderboardKey,
                event.playerId().toString(),
                event.rating());
    } catch (Exception ex) {
        syncFailures.increment();
        log.warn("Failed to sync rating change to Redis for player {}", event.playerId(), ex);
    }
}

Walkthrough. There are only two events (RatingChanged, RemovedFromLeaderboard), both tiny records. Services publish them; this class listens after the commit. ZADD both adds a new member and updates an existing one. A failure is caught, logged and counted in arena.leaderboard.sync.failures, and not re-thrown, because the database commit already happened and failing the HTTP request would be misleading. Who publishes: registration (new player), match recording (every participant), a ban (RemovedFromLeaderboard) and an appeal that is overturned (RatingChanged again, so the player returns). Trade-off: after-commit is best-effort; see 2.8. Tests: covered through the flows that publish events: register, match, ban, overturn.

LeaderboardService: two ways to ask for a rank

arena/src/main/java/dev/fairplay/arena/leaderboard/LeaderboardService.java (database path)
SELECT COUNT(*) + 1
FROM players p
WHERE p.role = 'PLAYER'
  AND p.status IN ('ACTIVE', 'FLAGGED', 'REINSTATED')
  AND (p.rating > :rating
       OR (p.rating = :rating AND (p.id::text COLLATE "C") > :idText))

Walkthrough. Your rank is "one plus the number of players ahead of you". Someone is ahead if their rating is higher, or the rating is equal and their id text is larger (the same rule Redis uses for ties, byte by byte; COLLATE "C" forces the byte comparison). The Redis path asks ZREVRANK and adds 1, and also reads ZSCORE and ZCARD. Both paths first load the player and refuse (404 PLAYER_NOT_RANKED) anyone who is not eligible, so a banned player has no rank. Each lookup is timed with a Micrometer Timer called arena.leaderboard.rank.lookup, tagged source=redis or db; a Gauge reports the leaderboard size. getLeaderboard reads a page with ZREVRANGE ... WITHSCORES, then loads usernames with a single findAllById and keeps Redis's order.

Why keep the slow path? It is the "before" in the benchmark and the reference for the equality test. Tests: redisRankEqualsDbRankFor200PlayersWithForcedRatingTiesAndAfterRebuild creates 200 players over only 10 distinct ratings (many ties), checks Redis rank equals DB rank for every player, deletes the Redis key, rebuilds, and checks again. returnsTopPageAndReflectsBanAndOverturn: top page order, ban removes a player (total drops, rank gives PLAYER_NOT_RANKED), appeal and overturn bring the player back at rank 2 of 3.

LeaderboardRebuilder: repainting the scoreboard

arena/src/main/java/dev/fairplay/arena/leaderboard/LeaderboardRebuilder.java
long eligibleCount = playerRepository.countEligibleForLeaderboard(ELIGIBLE_STATUSES);
Long currentSize = redisTemplate.opsForZSet().zCard(leaderboardKey);
if (currentSize != null && currentSize == eligibleCount) {
    ...
    return;
}
...
redisTemplate.rename(tempKey, leaderboardKey);

Walkthrough. At startup (ApplicationReadyEvent, if arena.leaderboard.rebuild-on-startup is true): count eligible players in PostgreSQL and compare with Redis's ZCARD. If equal, skip. Otherwise build a temporary key leaderboard:global:rebuild by reading players in batches of 10,000 with keyset pagination (WHERE id > :lastId ORDER BY id LIMIT :limit), adding each batch with a pipelined call (many commands in one network round trip), then RENAME the temporary key over the real one. RENAME is atomic, so a reader sees the old set or the new one, never a half-built set. If nobody is eligible, it just deletes the main key. The README reports 22.6 s to rebuild 1,000,001 players on the benchmark machine.

Pitfalls (honest). (1) Only the count is compared, so a Redis set with the right number of members but wrong scores is not repaired until a rebuild is forced. todo.md lists this as an optional improvement. (2) My reading of the code: the rebuild reads a snapshot from PostgreSQL, so if a rating change is committed and written to Redis while the rebuild is running, the later RENAME could replace it with the older value. I did not test this. Tests: the rebuild is called directly in the 200-player test. The tests turn the startup rebuild off (rebuild-on-startup=false) so they control Redis themselves.

5.7 moderation: the state machine, actions, queue, audit log

AccountStateMachine: the rulebook

Job: say, for every pair of (action, current status), whether it is allowed and what the new status is. It is a plain Java class with no Spring and no database, which is the whole point.

arena/src/main/java/dev/fairplay/arena/moderation/AccountStateMachine.java
ALLOWED_FROM.put(ModerationActionType.FLAG, EnumSet.of(AccountStatus.ACTIVE, AccountStatus.REINSTATED));
ALLOWED_FROM.put(ModerationActionType.BAN, EnumSet.of(AccountStatus.ACTIVE, AccountStatus.FLAGGED, AccountStatus.REINSTATED));
ALLOWED_FROM.put(ModerationActionType.CLEAR, EnumSet.of(AccountStatus.FLAGGED));
ALLOWED_FROM.put(ModerationActionType.NOTE, EnumSet.allOf(AccountStatus.class));
...
public AccountStatus next(AccountStatus current, ModerationActionType action) {
    ...
    Set<AccountStatus> allowed = ALLOWED_FROM.get(action);
    if (allowed == null || !allowed.contains(current)) {
        throw new ApiException(
                ErrorCode.INVALID_STATE_TRANSITION,
                "Cannot apply " + action + " to a player in status " + current);
    }
    if (action == ModerationActionType.NOTE) {
        return current;
    }
    return TARGETS.get(action);
}
ActionAllowed fromNew status
FLAGACTIVE, REINSTATEDFLAGGED
BANACTIVE, FLAGGED, REINSTATEDBANNED
CLEARFLAGGEDACTIVE
NOTEany of the 5 statusesunchanged
APPEAL_SUBMITTEDBANNEDAPPEALED
APPEAL_UPHELDAPPEALEDBANNED
APPEAL_OVERTURNEDAPPEALEDREINSTATED

Walkthrough. There are 7 actions and 5 statuses, so 35 pairs. Exactly 14 are legal (the table adds up: 2+3+1+5+1+1+1). The other 21 throw ApiException(INVALID_STATE_TRANSITION), which the API shows as 409. Two details to notice: a FLAGGED player cannot be flagged again, and a player in APPEALED can only be upheld or overturned (not banned or cleared directly). NOTE never changes the status.

Why a pure class: it can be tested exhaustively in milliseconds, with no database, and "every status change goes through here" is easy to see and to review. Tests: AccountStateMachineTest builds a map of the 14 legal pairs, generates all 35 pairs from the enums, and for each checks either the expected new status or the INVALID_STATE_TRANSITION error. That is 35 test runs from one method.

ModerationService.applyAction

Job: apply one moderation action to one player, enforce who may do what, write one audit row and keep the leaderboard right.

arena/src/main/java/dev/fairplay/arena/moderation/ModerationService.java
} else if (actor.getRole() == Role.SERVICE) {
    if (request.source() != ActionSource.TELEMETRY && request.source() != ActionSource.JUDGE) {
        throw new ApiException(ErrorCode.INVALID_SOURCE, "Service accounts must use TELEMETRY or JUDGE");
    }
    if (request.action() == ModerationActionType.BAN) {
        if (request.confidence() == null) {
            throw new ApiException(ErrorCode.CONFIDENCE_REQUIRED, "Service BAN requires confidence");
        }
        if (request.confidence().compareTo(props.moderation().serviceBanMinConfidence()) < 0) {
            throw new ApiException(
                    ErrorCode.CONFIDENCE_TOO_LOW,
                    "Service BAN confidence must be at least " + props.moderation().serviceBanMinConfidence());
        }
    }
}
...
AccountStatus from = target.getStatus();
AccountStatus to = stateMachine.next(from, request.action());
...
if (to == AccountStatus.BANNED && from != AccountStatus.BANNED) {
    eventPublisher.publishEvent(new RemovedFromLeaderboard(target.getId()));
}

Walkthrough, in order. (1) Only FLAG, BAN, CLEAR and NOTE are accepted here; the three appeal actions are written by AppealService. (2) Load the actor and run guardrails (enforceGuardrails): a moderator must use source = HUMAN; a service must use TELEMETRY or JUDGE; a service BAN needs a confidence of at least arena.moderation.service-ban-min-confidence (0.80). Compare with BigDecimal.compareTo, so 0.80 passes and 0.79 does not. (3) Load the target; it must have role PLAYER (422 TARGET_NOT_A_PLAYER). (4) Ask the state machine for the new status. (5) If the status changed, update the player's status and timestamps. (6) Always insert one new ModerationAction row recording from-status, to-status, actor, source, reason, evidence (a list of strings stored as JSON), confidence and requiresHumanReview. (7) If the player was just banned, publish RemovedFromLeaderboard. (8) Count the action in the arena.moderation.actions metric (tagged with action and source) and log it.

Why the guardrail lives in the service, not the state machine: the state machine answers "is this move legal?" for anyone; the guardrail answers "may this actor make it on this evidence?". Keeping them apart keeps the state machine pure. Concurrency: the Player row has @Version. If two requests change the same player at once, one commits first; the other either fails on the version check (409 CONCURRENT_MODIFICATION) or, if it reads after the commit, fails the state machine (409 INVALID_STATE_TRANSITION). Either way it is a 409.

Tests (ModerationIntegrationTest, 2 tests). The long one walks a story: a moderator using source JUDGE gets 422 INVALID_SOURCE; a service ban with no confidence gets CONFIDENCE_REQUIRED; at 0.79 CONFIDENCE_TOO_LOW; a service FLAG with requiresHumanReview works; the queue filter shows 2 flagged players, or 1 with humanReviewOnly=true; CLEAR works; a second CLEAR from ACTIVE gives 409; a service ban at exactly 0.80 works; a NOTE leaves BANNED as it is; the history lists 4 entries newest first. The second test, parallelBansGiveExactlyOneSuccessAndOneConflict, fires two bans at the same player from two threads released together and asserts that exactly one fails with a conflict.

The audit log and its database trigger

arena/src/main/resources/db/migration/V2__audit_log_append_only.sql
CREATE FUNCTION forbid_audit_change() RETURNS trigger AS $$
BEGIN
    RAISE EXCEPTION 'moderation_actions is append-only';
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER trg_moderation_actions_append_only
    BEFORE UPDATE OR DELETE ON moderation_actions
    FOR EACH ROW EXECUTE FUNCTION forbid_audit_change();

Before any row of moderation_actions is changed or deleted, PostgreSQL runs the function, which always raises an error. Inserts are untouched. So history can grow but never be rewritten, even by buggy Arena code or by a hand-typed SQL statement from the application's database user. Limits: a database owner could still drop the trigger; this protects against mistakes and the application, not against someone with full database control. Test: AuditLogAppendOnlyTest (dissected in section 7).

ModerationAction (the entity) is built for this: its constructor takes every field, and the evidence column is jsonb, written with @ColumnTransformer(write = "?::jsonb") from a JSON string created by Jackson 3's JsonMapper.

ModerationQueueQuery: the review queue

arena/src/main/java/dev/fairplay/arena/moderation/ModerationQueueQuery.java
FROM players p
JOIN LATERAL (
    SELECT * FROM moderation_actions m
    WHERE m.player_id = p.id
    ORDER BY m.created_at DESC
    LIMIT 1
) a ON TRUE
WHERE p.status = 'FLAGGED'
  AND (:humanReviewOnly = FALSE OR a.requires_human_review)
ORDER BY p.status_changed_at ASC, p.id ASC

For every player whose status is FLAGGED, the lateral sub-select picks that player's newest action. The queue shows oldest flags first (so nothing waits forever) and can be limited to actions that asked for human review. It is hand-written SQL through JdbcClient, because expressing "latest row per group" in JPQL is awkward. A second query with the same body counts the total for paging.

ModerationController

Endpoints 13 to 15. POST .../actions returns 201 (@ResponseStatus(CREATED)) and needs MODERATOR or SERVICE; GET /queue needs MODERATOR only; GET .../history needs MODERATOR or SERVICE and returns pages newest first.

5.8 appeal: submit and decide

Job: let a banned player appeal once per ban, and let a moderator uphold or overturn it, keeping the status, the audit log and the leaderboard consistent.

arena/src/main/java/dev/fairplay/arena/appeal/AppealService.java
if (player.getStatus() != AccountStatus.BANNED) {
    throw new ApiException(ErrorCode.APPEAL_NOT_ALLOWED, "Only BANNED players may submit an appeal");
}
...
if (appealRepository.existsByBanActionId(banAction.getId())) {
    throw new ApiException(ErrorCode.APPEAL_ALREADY_EXISTS, "This ban has already been appealed");
}
...
if (to == AccountStatus.REINSTATED) {
    eventPublisher.publishEvent(new RatingChanged(player.getId(), player.getRating()));
}

Walkthrough. Submit (POST /appeals, role PLAYER): the player must be BANNED; find their latest BAN action; refuse if that ban already has an appeal (409 APPEAL_ALREADY_EXISTS, backed by a UNIQUE column in the schema); ask the state machine for BANNED -> APPEALED; save the Appeal as PENDING; write an APPEAL_SUBMITTED audit row. Decide (POST /appeals/{id}/decision, role MODERATOR): the appeal must still be PENDING (409 APPEAL_ALREADY_DECIDED). UPHOLD means APPEAL_UPHELD: the player goes back to BANNED and stays off the leaderboard. OVERTURN means APPEAL_OVERTURNED: the player becomes REINSTATED and a RatingChanged event puts them back on the leaderboard with their old rating. Both write an audit row and update two counters.

Why: an upheld ban cannot be appealed again, because the unique ban-action link remains. Appeal has its own @Version, so two moderators deciding the same appeal at once cannot both win. Pitfall: the appeal is tied to the latest ban action found by findFirstByPlayerIdAndActionOrderByCreatedAtDesc. Test: AppealIntegrationTest (one long test): an active player cannot appeal; ban, appeal, list pending; uphold keeps them banned and off the board; deciding twice gives 409; a second appeal on the same ban gives 409; a different player is banned, appealed and overturned, becomes REINSTATED and returns to the board.

5.9 The database schema (V1__init.sql)

Six tables, all primary keys are UUIDs made in Java. Timestamps are TIMESTAMPTZ (UTC).

TableHoldsConstraints worth knowing
playersevery account (players, moderator, services) with role, status, rating and running totalsunique lower-case indexes on username and email (ux_players_username_lower, ux_players_email_lower); CHECK on role and status values; rating >= 0; version for optimistic locking; index on (rating DESC, id)
refresh_tokenshashed refresh tokens, expiry, revocation, replaced_bytoken_hash CHAR(64) UNIQUE
matchesone row per recorded matchexternal_id UNIQUE (the idempotency key); CHECK (ended_at > started_at)
match_participantsone row per player per match, with before/after ratingprimary key (match_id, player_id); CHECK (headshots <= kills); CHECK (shots_hit <= shots_fired); avg_reaction_ms > 0
moderation_actionsthe append-only audit logtrigger from V2; confidence NUMERIC(4,3) between 0 and 1; evidence JSONB
appealsban appealsban_action_id UNIQUE (one appeal per ban); status CHECK; version

Why duplicate the rules in SQL and Java? Java gives a friendly error code; the database guarantees the rule even if some other program writes to it. The test base class TRUNCATEs these tables (not flyway_schema_history), so a new table must be added to that list.

5.10 Small files, grouped

File(s)What it does
ArenaApplication@SpringBootApplication, @EnableScheduling (turns on @Scheduled), @ConfigurationPropertiesScan. Excluded from coverage.
OpenApiConfigDescribes the API for Swagger and declares a global "Bearer JWT" security scheme (the lock icon). Public endpoints clear it with @SecurityRequirements.
common/web/CurrentUserOne static method: UUID.fromString(jwt.getSubject()). The rule: the id of "me" always comes from the token, never from the request body.
common/web/PageResponse<T>The paging envelope: content, page, size, totalElements, totalPages, built from Spring's Page.
All dto/ recordsThe exact JSON shapes (the contract). Requests carry validation annotations; responses use @JsonInclude(NON_NULL).
Role, AccountStatus, ActionSource, ModerationActionType, GameMode, AppealStatus, AppealDecisionEnums stored as text (@Enumerated(STRING)), matching the CHECK lists in the schema. Their values are part of the contract.
PlayerMapperMapStruct converter Player to summary or detail DTO.
LeaderboardController, AppealController, MatchController, ...Thin controllers: URL, role check, validation, then one service call. Swagger text is in @Operation/@Tag.
ProblemAuthenticationEntryPoint, ProblemAccessDeniedHandlerWrite 401 and 403 JSON for failures that happen inside the security filters (5.2).

6. Parts that exist only as a plan not built

Nothing in this table exists in the code. They are described so that you can answer "what would you do next?" without claiming anything that is not there.

IdeaWhat it would doWhere it would fitSource of the plan
Rate limitingLimit requests per IP and per account on login, register and appeal endpoints, to slow down password guessing and spam.A filter in front of SecurityConfig's chain, or a gateway in front of Arena.arena/README.md "What I'd Do Next". Also listed as a non-goal in CLAUDE.md for now.
Transactional outbox for RedisWrite "update Redis" as a row in a table in the same transaction as the rating change; a worker then applies it and retries until done. Closes the crash gap between commit and ZADD.Would replace the in-memory @TransactionalEventListener in LeaderboardSync.arena/README.md
Kafka events to the JudgePublish moderation and match events so the Judge agent can react without polling.New publisher classes next to MatchService and ModerationService.arena/README.md. Kafka is a stated non-goal for now.
Telemetry and Judge actually calling ArenaThe two other Fairplay services would use the service accounts and endpoints 8, 13 and 15.They live outside this repository; Arena only provides the accounts (AccountSeeder) and the API.Project spec. No call from them is exercised here.
Authorize before validatingReturn 403 (not 400) to a caller without the role even if their body is invalid.Duplicate the role rules as URL rules in SecurityConfig.todo.md (optional)
Rebuild that detects wrong scoresCompare more than the member count when deciding to skip a rebuild.LeaderboardRebuilder.rebuildtodo.md (optional)
Register tagged counters at startupMake arena_moderation_actions and arena_appeals_decided show on /actuator/prometheus from the first second.Services' constructors (as MatchService already does for its untagged counter).todo.md (optional); spec step 10
A running CI and a real repositorygit init, push, see the workflow go green, replace the placeholder badge URL.Repository root decision in todo.md, section "Before Pushing".todo.md
Grafana dashboards, screenshotsDraw the Prometheus metrics; add a Swagger screenshot and an architecture image to the README.ops/ and README.mdtodo.md
Frontend, social login, e-mail verification, password reset, admin UINot planned at all.-Non-goals in CLAUDE.md

7. The tests

7.1 How to run them

cd arena
./mvnw verify                                   # everything + the 85% coverage gate
./mvnw test                                     # tests only
./mvnw test -Dtest=AccountStateMachineTest      # one class
./mvnw test -Dtest=MatchIntegrationTest#recordsMatchUpdatesRatingsTotalsRedisAndIsIdempotent   # one method

Docker must be running for the integration tests (Testcontainers starts PostgreSQL and Redis). The unit tests (AccountStateMachineTest, RatingCalculatorTest, TokenServiceTest, StatDistributionServiceTest) need nothing. The whole ./mvnw verify took about 55 seconds in each of my two runs (Docker images were already downloaded); the slowest classes were the appeal test (21 to 23 seconds, the first to start the app and the containers) and the leaderboard test (about 18 seconds, which creates 200 players).

7.2 The helper classes

arena/src/test/java/dev/fairplay/arena/support/AbstractIntegrationTest.java
@SpringBootTest(properties = {
        "arena.jwt.secret=test-secret-that-is-at-least-32-chars-long",
        "arena.accounts.moderator.password=test",
        "arena.accounts.services[0].username=telemetry-sim",
        "arena.accounts.services[0].password=test",
        ...
        "arena.leaderboard.rebuild-on-startup=false"
})
@AutoConfigureMockMvc
public abstract class AbstractIntegrationTest {

    @ServiceConnection
    static final PostgreSQLContainer postgres = new PostgreSQLContainer("postgres:17-alpine");
    ...
    @BeforeEach
    void resetState() {
        jdbc.execute("TRUNCATE appeals, moderation_actions, match_participants, matches, refresh_tokens, players CASCADE");
        ...
    }
}

Walkthrough. Every integration test class extends this. It (1) starts the real app with test-only settings; (2) starts a PostgreSQL 17 and a Redis 7 container once and shares them across all test classes (the static block); @ServiceConnection tells Spring Boot to point the datasource and Redis at those containers automatically; (3) gives each test a MockMvc, a JdbcTemplate, a StringRedisTemplate and the TestDataFactory; (4) before every test, wipes all tables and flushes Redis, so tests cannot affect each other. The services list sets username as well as password for the reason in 5.1. The startup rebuild is off so a test controls Redis by itself.

TestDataFactory is a Spring bean that creates ready-made accounts: player("neo"), player(name, status, rating) (also adds eligible ones to Redis), moderator(), service("judge-agent"), bearer(player) (a ready Authorization header value, made by the real TokenService) and match(players...) (records a match through the real MatchService).

7.3 Test class → what it proves

Test classKindTestsWhat it proves
AccountStateMachineTestunit35All 35 (status, action) pairs: 14 legal ones give the right new status; the other 21 throw INVALID_STATE_TRANSITION.
RatingCalculatorTestunit12Exact deltas for N = 2, 4, 10; the floor at 0; invalid inputs rejected.
TokenServiceTestunit2Access-token claims, header and expiry; refresh token is 43 base64url characters with a 64-hex SHA-256 hash and a 7-day expiry. The first test fails today (section 0.1).
StatDistributionServiceTestunit2Percentiles are null below 5 matches or before data; edge and middle lookups; reaction speed is inverted.
AuthIntegrationTestintegration5Register adds to the leaderboard; duplicate username or e-mail refused case-insensitively; bad e-mail gives field errors; login, rotation and reuse detection; expired token is not a reuse.
SecurityIntegrationTestintegration2401 with no or expired token; 403 for the wrong role; public leaderboard; Swagger lists exactly 18 operations.
ErrorHandlingIntegrationTestintegration1404, 400, 404, 400, 405 all return application/problem+json with a code.
PlayerIntegrationTestintegration3E-mail shown only on /me; PATCH works and is blocked for banned players; percentiles appear after the 5th match; moderator search.
MatchIntegrationTestintegration3Ratings, totals and Redis updated; replay is idempotent; validation and eligibility; concurrent duplicate gives one match.
LeaderboardIntegrationTestintegration2Ban removes and overturn restores a player; Redis rank equals DB rank for 200 players with ties, before and after a rebuild.
ModerationIntegrationTestintegration2Guardrails, transitions, queue, history order; two simultaneous bans give one success and one conflict.
AuditLogAppendOnlyTestintegration1The database itself rejects UPDATE and DELETE on the audit log.
AppealIntegrationTestintegration1Whole appeal life cycle: one appeal per ban, decide once, uphold keeps the ban, overturn reinstates.
Total7151 unit + 20 integration. Today: 70 pass, 1 error.
What the tests do not cover I read all test files and searched them for these topics and found nothing: a test that makes Redis fail (the "catch, count, do not re-throw" path in LeaderboardSync), two simultaneous refreshes of one token, a rebuild running while ratings change, the /actuator/prometheus output, the Docker image, and the CI workflow. 89.6% of lines are covered, but only 65.9% of branches, so many "else" paths are unchecked.

7.4 One real test, dissected: the audit log

arena/src/test/java/dev/fairplay/arena/moderation/AuditLogAppendOnlyTest.java
// » ARRANGE: make a moderator, a target player, and one real audit row
Player mod = data.moderator();
Player target = data.player("audit_target");

UUID actionId = UUID.randomUUID();
moderationActionRepository.saveAndFlush(new ModerationAction(
        actionId,
        target,
        ModerationActionType.NOTE,
        ...
        Instant.now()));

// » ACT + ASSERT: try to change the row with raw SQL, and expect the database to refuse
assertThatThrownBy(() -> jdbc.update(
        "UPDATE moderation_actions SET reason = 'tampered' WHERE id = ?", actionId))
        .isInstanceOf(DataAccessException.class)
        .hasMessageContaining("moderation_actions is append-only");

assertThatThrownBy(() -> jdbc.update(
        "DELETE FROM moderation_actions WHERE id = ?", actionId))
        .isInstanceOf(DataAccessException.class)
        .hasMessageContaining("moderation_actions is append-only");

Arrange. The factory creates the two accounts the foreign keys need. saveAndFlush inserts a NOTE row immediately; an insert is allowed. Act. The test bypasses all Java business code and sends plain SQL through JdbcTemplate, which is the worst case: someone with the application's database login. Assert. Both statements must throw a DataAccessException whose message contains the text raised by the trigger. If someone deleted V2__audit_log_append_only.sql, this test would fail. Why a real database: an in-memory fake would not run a PostgreSQL trigger. A small honesty note: this test calls Instant.now() directly; the project rule (inject a Clock) is followed in the production code, not in this test.

7.5 Why real containers, and what is faked

Arena's own database and Redis are not faked: the tests run against real PostgreSQL 17 and Redis 7 in Docker, because the features under test (trigger, COLLATE "C" tie order, FOR UPDATE locks, percentile_cont, Redis sorted-set tie order) behave differently or do not exist in fakes. What is stand-in: the two other Fairplay services never run. Their role is played by test-created SERVICE accounts (data.service("telemetry-sim")) that call the API like they would. The only mock object is mock(JdbcClient.class) in the percentile unit test, which exercises the pure lookup code without a database.

8. Build and configuration files explained

8.1 pom.xml

arena/pom.xml
<rule>
    <element>BUNDLE</element>
    <limits>
        <limit>
            <counter>LINE</counter>
            <value>COVEREDRATIO</value>
            <minimum>0.85</minimum>

"For the whole project, the ratio of covered lines must be at least 0.85, or the build fails." ArenaApplication and the generated *MapperImpl classes are excluded from the count.

8.2 application.yml: the knobs

KeyValueMeaning
spring.threads.virtual.enabledtrueVirtual threads for requests.
spring.datasource.hikari.maximum-pool-size20At most 20 database connections.
spring.jpa.hibernate.ddl-autovalidateCheck, never change, the schema.
spring.jpa.open-in-viewfalseNo database session kept open during view rendering; lazy loading must happen inside services.
spring.mvc.problemdetails.enabledtrueSpring's built-in problem-details support.
server.error.include-stacktraceneverNever leak stack traces.
logging.structured.format.consoleecsOne JSON object per log line.
management.endpoints.web.exposure.includehealth,info,metrics,prometheusWhich actuator endpoints are exposed.
arena.jwt.*secret from env; issuer fairplay-arena; access 15m; refresh 7dToken settings.
arena.rating.*initial 1000; max-delta 30Starting rating; D in the formula.
arena.leaderboard.*key leaderboard:global; rebuild-on-startup true; batch 10000Redis key and rebuild settings.
arena.stats.*min-matches 5; refresh 60sWhen percentiles appear and how often they refresh.
arena.moderation.service-ban-min-confidence0.80The guardrail threshold.
arena.accounts.*moderator mod-admin; services telemetry-sim, judge-agentSeeded accounts; passwords come from the environment.

Environment variables the app needs outside Docker: JWT_SECRET, MODERATOR_PASSWORD, TELEMETRY_SERVICE_PASSWORD, JUDGE_SERVICE_PASSWORD. Optional with defaults: DB_URL, DB_USER, DB_PASSWORD, REDIS_HOST, REDIS_PORT. .env.example contains placeholders for the four required ones; .env (git-ignored) holds the real local values.

8.3 Docker, Compose, CI, ops, benchmark

FileWhat it does
DockerfileStage 1 (eclipse-temurin:21-jdk): copy pom.xml, download dependencies (cached layer), copy the source, build with -DskipTests. Stage 2 (eclipse-temurin:21-jre): create a non-root user arena, copy the jar, run it with -XX:MaxRAMPercentage=75.
compose.yamlPostgres 17 and Redis 7 with health checks; Arena starts only when both are healthy (depends_on ... service_healthy) and reads .env. Profile observability adds Prometheus (:9090) and Grafana (:3000). The Postgres password in compose is the placeholder arena.
.dockerignore, .gitignoreKeep .env, target/, .idea and benchmark/player-ids.json out of the image and out of git.
.github/workflows/ci.ymlOn push and pull request: Java 21 Temurin, ./mvnw -B verify, upload the JaCoCo report. Never run. It works only if arena/ is the repository root. It would fail today because of the red test.
ops/prometheus.ymlScrape arena:8080/actuator/prometheus every 5 s.
scripts/seed-1m-players.sqlInsert 1,000,000 players with ratings 500 to 2499 (you must replace <BCRYPT_HASH> first).
benchmark/rank-lookup.jsk6 script: 15 s warm-up at 50 virtual users, then 60 s at 200, each calling the rank endpoint for a random id from player-ids.json with source=db or redis; fails its threshold if the measured p95 is not under 2 s.

9. A worked example with real numbers

The numbers in 9.1 to 9.3 come from the real test MatchIntegrationTest.recordsMatchUpdatesRatingsTotalsRedisAndIsIdempotent; the results that the test checks (ratings 1030 and 970, 14 kills, Redis scores) are marked tested. The extra figures I computed by hand from the same code (stats, ranks) are marked hand-computed. Section 9.4 and 9.5 use made-up players and are illustrative.

9.1 Input

Two new players, p1 and p2, both at rating 1000, play one match. telemetry-sim sends:

Fieldp1p2
placement12
kills / deaths14 / 35 / 10
headshots61
shotsFired / shotsHit180 / 61100 / 20
avgReactionMs212260

The match: externalId = "sim-2026-11-17-0001", mode FFA, map Rust Yard, 10:00:00Z to 10:12:30Z.

9.2 What the code does with it

  1. Validation (validateRequest): 10:12:30 is after 10:00:00. Placements {1, 2} are exactly 1..2. 6 <= 14 and 1 <= 5 (headshots <= kills). 61 <= 180 and 20 <= 100 (hits <= fired). All pass.
  2. Lock both players (FOR UPDATE, ids sorted). Both are ACTIVE PLAYERs, so they are eligible.
  3. Rating change RatingCalculator.delta(N=2, placement, 30):
    p1: numerator = 2 + 1 - 2*1 = 1, denominator = 2 - 1 = 1, so round(30 * 1/1) = +30. applyDelta(1000, 30) = 1030.
    p2: numerator = 2 + 1 - 2*2 = -1, so round(30 * -1/1) = -30. applyDelta(1000, -30) = 970. tested
  4. Totals updated (p1 after the match): matchesPlayed = 1, totalKills = 14, totalDeaths = 3, totalHeadshots = 6, totalShotsFired = 180, totalShotsHit = 61, sumReactionMs = 212. tested for rating, matches played and kills.
  5. Events published: RatingChanged(p1, 1030) and RatingChanged(p2, 970). After the commit: ZADD leaderboard:global 1030 <p1> and ZADD leaderboard:global 970 <p2>. tested (the test reads 1030.0 and 970.0 from Redis).
  6. Response: 201, participants[0].ratingBefore = 1000, ratingAfter = 1030; participants[1].ratingAfter = 970. Sending the same body again gives 200 and the same numbers. tested

9.3 The derived stats (PlayerService.computeStats) hand-computed

StatFormulap1p2
kdRatiokills / max(deaths, 1)14 / 3 = 4.66675 / 10 = 0.5
headshotRateheadshots / kills6 / 14 = 0.42861 / 5 = 0.2
accuracyshotsHit / shotsFired61 / 180 = 0.338920 / 100 = 0.2
avgReactionMssumReactionMs / matchesPlayed (integer)212 / 1 = 212260 / 1 = 260
percentilesneed at least 5 matchesabsent (1 match)absent (1 match)

Rounding is HALF_UP to 4 decimals: 14/3 = 4.66666... becomes 4.6667; 6/14 = 0.428571... becomes 0.4286; 61/180 = 0.338888... becomes 0.3389.

9.4 A percentile lookup by hand from a unit test

From StatDistributionServiceTest: the 101 headshot cut points are 0.00, 0.01, ..., 1.00. A player has a headshot rate of 0.504. How many cut points are <= 0.504? They are 0.00 up to 0.50, which is 51 of them. The percentile is 51 - 1 = 50. For reaction time, cut points run 100, 102, ..., 300 ms; a player at 201 ms has 51 cut points at or below (100 to 200), so percentile = 50 and reactionSpeed = 100 - 50 = 50. A player at 90 ms is below every cut point, so the count is 0, the percentile is clamped to 0, and reactionSpeed = 100 (the fastest possible).

9.5 A tie-break by hand illustrative

Three ranked players: A at 1030, B at 1000 with id text f3..., C at 1000 with id text 2a....

PlayerRedis (ZREVRANK + 1)SQL (COUNT(*) + 1 of players ahead)
Arank 1 (highest score)nobody has a higher rating, no tie: 0 ahead, rank 1
Btie at 1000: larger text f3... comes first in reverse order: rank 2A is ahead (1030 > 1000); in the tie, nobody has a larger id than f3...: 1 ahead, rank 2
Crank 3A is ahead; in the tie, B's f3... is larger than 2a...: 2 ahead, rank 3

This is exactly what the 200-player test checks with real random ids.

9.6 The benchmark numbers, with a sanity check from README, one run

Sourcep50p95Throughput
db15.62 s18.01 s12.6 req/s
redis33.07 ms63.53 ms5,764 req/s

Ratios: 18.01 s / 0.06353 s is about 283, and 5,764 / 12.6 is about 457: the README's "about 280x at p95" and "about 460x the throughput". Sanity check (rough): with 200 virtual users that wait for each answer before asking again, "throughput x time per request" should be near 200. For db: 12.6 x 15.6 s is about 197. It fits. What it does not prove: the machine was one desktop; the load generator shared the Docker VM with the services; the server-side timer showed only about 1.5 s for the DB path because it does not include waiting for one of the 20 database connections (the 200 users compete for 20). The README itself says the table shows the third of three runs. These are real measurements, but from one session on one machine.

10. Decisions and deviations

The code comments labelled DECISION: were removed when the code was cleaned up (handoff.md); the explanations stayed. This table is built from the remaining comments, handoff.md, todo.md and a comparison with the spec.

WhatThe plan saidWhat was doneWhy
Duplicate externalId racingIf externalId exists, return 200. Nothing about two simultaneous requests.recordMatch runs a TransactionTemplate and catches DataIntegrityViolationException outside it, then returns the winner's match (200).The loser's transaction is aborted by PostgreSQL, so the lookup must happen after rollback. Before the fix the loser got a 500. Found in review; has a test.
Refresh-token check orderUnknown or expired gives INVALID_REFRESH_TOKEN; then reuse gives REFRESH_TOKEN_REUSED (spec section 8).The first code checked reuse first. Now expiry is checked first.An expired, revoked token is an honest stale client, not a thief, and should not revoke every session. Test added.
Empty database at startupPercentiles are null before the first refresh.queryPercentiles returns Optional<double[]> and ends with orElse(null).percentile_cont returns NULL with no eligible rows, and JdbcClient rejects a null extractor result, which crashed the app at first start. Found only by running the full stack.
Test setting for the services listThe spec's test snippet set only services[n].password.username is set as well, in the code and in the spec's copy.Boot replaces a whole list when another source sets indexed entries; username became null and no integration test could load.
Role-denial tests send a valid bodyA PLAYER calling a moderator endpoint gets 403.The tests send a valid body. The behaviour (400 for an invalid body) was left as it is; changing it is an optional item in todo.md.@Valid runs before @PreAuthorize. Fixing it needs duplicate role rules in SecurityConfig.
springdoc version3.1.x for Boot 4.1 (spec table).3.2.0.It was tested: /v3/api-docs lists exactly 18 operations, checked by SecurityIntegrationTest.
Rebuild checks only countsIf ZCARD equals the eligible count, skip.As the spec says.Simple and cheap. Known limit: wrong scores with the right count are not repaired (optional item in todo.md).
Tagged metrics appear lazilyEvery arena_* meter visible on /actuator/prometheus (build step 10).The two tagged counters only appear after first use.Micrometer creates a tagged counter on the first increment. Not yet changed (optional).
Public endpoints clear the Swagger lockNot specified.@SecurityRequirements on the 5 public methods.So Swagger UI shows the padlock only on secured operations. A comment says so.
Open /actuator/prometheusExposed for scraping.No authentication.Simple local scraping. README warns to restrict it in production.
Login ignores account status"Accounts in any status may log in" (spec section 8).As the spec says.Banned players must be able to log in to appeal.
Percentiles via cached cut pointsCache 101 cut points per metric, refresh on a schedule.As the spec says (60 s).Computing over a million rows per request would be too slow. Trade-off: values can be up to 60 s old.
Time-dependent TokenServiceTestTests control time with a fixed Clock.The fixed clock controls the token, but the decoder still uses the real clock, so the test fails after 10:15 UTC on 2026-11-17.A mistake in the test, found today. Not fixed yet.

11. Interview preparation

Interviewers for a project like this rarely ask you to recite code. They ask why, and then they follow up on your answer. The pattern that works: state the decision, give the reason, name the trade-off, and say how you checked it. Click each question to reveal a sample answer in plain words. Say it in your own words; do not memorise. Every answer below uses only things that are built and that I verified in the code or in the test run described in section 0.

How to say "I have not measured that" with confidence Say what the design aims at, say what you did measure, and say what is missing. Example: "The design is meant to make rank lookups fast. I measured it in one session on my own machine: Redis p95 was 63 ms against 18 s for the database path. That is one experiment on a shared Docker VM, so I would call it a clear difference, not a precise number." Never fill a gap with a number you do not have.

11.1 Your pitch

30 seconds.

"Fairplay Arena is the backend of an anti-cheat platform, written in Java 21 with Spring Boot 4, PostgreSQL and Redis. It has 18 REST endpoints for players, matches, a Redis leaderboard, moderation with an append-only audit log, and ban appeals. The parts I care most about are a pure state machine for account status, a database trigger that makes the audit log tamper-proof, and Redis that is updated only after the database commits and can be rebuilt from Postgres. The tests run against real Postgres and Redis in Docker."

3 minutes.

"The problem: a cheat-detection system needs one trusted place to remember players, match results, rankings, flags, bans and appeals. Arena is that place. Detection and the AI judge are separate projects; Arena gives them service accounts and an API, and that API is a fixed contract.

The architecture is controller, service, repository, with PostgreSQL as the source of truth and a Redis sorted set as a fast copy for the leaderboard. Four decisions shape it. One: every account status change goes through a small pure class, AccountStateMachine, so all 35 action-and-status pairs can be unit-tested. Two: the moderation history table has a PostgreSQL trigger that rejects updates and deletes, so even a bug cannot rewrite it. Three: a service account, such as an automated judge, can only ban with a confidence of 0.80 or more; otherwise it must flag for a human. Four: Redis is updated in an after-commit listener, so a rolled-back transaction never reaches it, and a rebuild from the database repairs any drift.

Recording a match locks the players in sorted id order to avoid deadlocks, is idempotent on an external id, and also survives two requests racing on the same id. Tokens are short-lived JWTs, and refresh tokens are hashed, rotated, and revoke the whole family if an old one is replayed.

For quality: 71 tests, with integration tests on real PostgreSQL and Redis through Testcontainers, and a coverage gate at 85%; I measured 89.6% line coverage. One test currently fails because of a date-dependent mistake in the test itself, which I know how to fix. I benchmarked rank lookups with a million players in one session on one machine (three runs per source, only the last summary saved): Redis was far faster than the database path, but I would call it one experiment, not a precise figure. What is not built: rate limiting, an outbox for the Redis sync, Kafka, and any real integration with the other two services."

Adjust for what is true today. If the failing test has been fixed by the time you read this, drop that sentence. If you ran the benchmark again, say so. Never claim the CI is green until you have seen it run.

11.2 Design and architecture

Why is PostgreSQL the source of truth and Redis only a copy?

I wanted a leaderboard that answers a rank question in milliseconds, but I did not want to risk losing or corrupting ratings. PostgreSQL has transactions and constraints, so it holds the truth. Redis' sorted set gives rank in O(log N), so it holds a copy. If Redis is wrong or empty, LeaderboardRebuilder rebuilds it from the database, and the application can run with source=db as well. The trade-off is that the copy can lag or drift, and I have to keep it in sync. I checked this with a test that gives 200 players only 10 distinct ratings, compares the Redis rank with the database rank for every player, deletes the Redis key, rebuilds, and compares again. That is also why I kept a slow database rank query (source=db) next to the Redis one: it is the baseline for the benchmark and the reference that proves Redis returns the same rank, ties included. The cost is a little extra code.

Why is the account state machine a separate, pure class?

The rules about which action is allowed from which status are the heart of moderation, and they are easy to get subtly wrong. Putting them in one class with no Spring and no database means I can test every combination in milliseconds, and it is easy to see that every status change goes through one place. The trade-off is one more class and a lookup table. The check is AccountStateMachineTest, which generates all 7 actions times 5 statuses, 35 pairs, and asserts either the expected new status for the 14 legal pairs or INVALID_STATE_TRANSITION for the other 21.

Why a database trigger for the audit log instead of just not writing update code?

Because "we never write update code" is a promise about today's code, and a trigger is a guarantee about the data. The trigger in V2__audit_log_append_only.sql rejects any UPDATE or DELETE on moderation_actions, from Arena or from anyone with the application's login. The trade-off is that a database owner can still drop the trigger, so it protects against mistakes and the application, not against a determined admin; and it makes corrections impossible, so a mistake must be fixed by adding a new row. I verified it with AuditLogAppendOnlyTest, which tries raw UPDATE and DELETE and expects the "append-only" error.

Why sort the participant ids before locking them?

To prevent deadlocks. If one match locks players 1 then 2 while another locks 2 then 1, each can wait for the other forever. If every transaction locks in id order, the second simply waits for the first. I do it with a stream sort and a query that has FOR UPDATE ... ORDER BY id. The trade-off is that concurrent matches with overlapping players wait for each other, which costs some throughput, but the ratings stay correct. I did not run a test that provokes a deadlock; the concurrency test I have is about the same externalId, so I would describe the ordering as a design guarantee backed by reasoning, not by a failing-then-passing test.

You use both pessimistic and optimistic locking. Why two kinds?

Different situations. Match recording changes several players' ratings together and the conflicts are likely, so I lock the rows up front with FOR UPDATE. Moderation actions and appeal decisions are rarer and touch one player or appeal, so I use a @Version column and let the loser fail with 409 CONCURRENT_MODIFICATION. The trade-off is two mechanisms to understand. I checked the optimistic path with parallelBansGiveExactlyOneSuccessAndOneConflict: two threads ban the same player at once and exactly one fails.

Why update Redis in an after-commit event listener rather than inside the service?

If I wrote to Redis inside the transaction and the transaction then rolled back, Redis would show a rating the database never accepted. With @TransactionalEventListener(phase = AFTER_COMMIT) the listener runs only after a successful commit, so a rolled-back transaction leaves Redis untouched. The trade-off is a small window: if the process crashes between the commit and the Redis write, Redis is stale until the next rebuild, and there is no retry. A transactional outbox would close that window; I list it as a next step but have not built it. In the listener, a Redis error is logged, counted in arena.leaderboard.sync.failures and not re-thrown, because the database already committed.

11.3 Key technologies

How do Redis sorted sets handle ties, and how did you make the SQL agree?

When scores are equal, Redis orders members by the member text, byte by byte, so in reverse order the larger text ranks first. My SQL counts the players ahead as those with a higher rating, or an equal rating and a larger id text, and it compares the text with COLLATE "C" so PostgreSQL also compares raw bytes instead of using language rules. The trade-off is that the tie order is "by id text", which is arbitrary and not "who got there first". I verified it with the 200-player test with only 10 distinct ratings, so many ties.

Why Flyway, and what does ddl-auto: validate do?

Flyway makes the schema a versioned, reviewable part of the code: V1 creates the tables, V2 adds the trigger, and changes are new files. With ddl-auto: validate Hibernate only checks that my entities match the real schema and refuses to start if they do not, so it never changes the database by itself. The trade-off is that I must write SQL by hand and keep entities in sync, but surprises show up at startup instead of in production. Every integration test starts the app against a fresh PostgreSQL, so it exercises these migrations each time.

Why JWT access tokens plus hashed refresh tokens?

An access token is a signed JWT that lives 15 minutes, so the server needs no session lookup to know who you are. Because it is short-lived, a stolen one is useful only briefly. The refresh token lasts 7 days, is 32 random bytes, and is stored only as a SHA-256 hash, so a leaked database does not give anyone a usable token. Each refresh rotates the token. The trade-off is more moving parts than a plain session cookie, and no way to revoke an access token before it expires. Tests cover rotation, reuse detection, the expired case and refusing a refresh token as a bearer token.

Why use JdbcClient and raw SQL in a few places when you have JPA?

Some queries are awkward or impossible in JPQL: percentile_cont for percentile cut points, JOIN LATERAL for "latest action per flagged player", the COLLATE "C" rank query, and the keyset-paginated rebuild. For ordinary reads and writes I use JPA because it is shorter and gives optimistic locking. The trade-off is that raw SQL is not checked at compile time, so I rely on integration tests that run it against a real PostgreSQL.

You enabled virtual threads. Did that make Arena faster?

I enabled them with spring.threads.virtual.enabled so that a request waiting for the database does not hold up a heavy operating-system thread. But I did not measure virtual threads against normal threads, so I cannot claim a speed-up. What I did observe in the benchmark is that the database path queued: 200 simulated users competed for the 20 connections in the Hikari pool, so the pool, not the thread type, was the limit. That is the README's explanation, and the server-side timer, which excludes the wait, supports it: about 1.5 s on the server against about 15 s at the client.

11.4 Failure handling and reliability

What happens if two requests record the same match at the same moment?

Both can pass the "does this externalId exist?" check. One inserts first; the other then hits the unique constraint on matches.external_id. PostgreSQL aborts the second transaction, so I cannot query inside it. I drive the transaction with a TransactionTemplate and catch DataIntegrityViolationException after the rollback, then load the winner's match and return it with 200. Before the fix the loser got a 500. The trade-off is slightly unusual code, with a comment explaining it. The test starts two threads on a latch and asserts exactly one creation, exactly one row, and each player's matchesPlayed equal to 1. I should add that whether a given run actually reaches the violation path depends on timing, so the test is an invariant check, not a guaranteed reproduction.

What if Redis is down, or the app crashes after the commit?

If Redis is down during an update, the listener logs a warning and increments arena.leaderboard.sync.failures, and the API call still succeeds because the database is correct. Redis then lags. A restart rebuilds the sorted set if its size differs from the number of eligible players. The trade-offs: no automatic retry, and the rebuild compares only counts, so wrong scores with a matching count are not detected. I have not written a test that makes Redis fail, so that branch is untested; I am relying on the code being short and on the rebuild as the repair.

How does the leaderboard rebuild work, and what is its weakness?

It counts eligible players in PostgreSQL and compares with Redis ZCARD; if they match it skips. Otherwise it reads players in batches of 10,000 with keyset pagination (WHERE id > :lastId ORDER BY id), writes them to a temporary key with pipelined commands, and then RENAMEs the temporary key over the real one, which is atomic, so readers see the old set or the new set, never half. The weaknesses: it compares only counts, and from reading the code I believe a rating change committed during the rebuild could be overwritten by the older snapshot; I have not tested that. The README reports 22.6 s to rebuild about a million players on my machine.

What happens when someone replays an old refresh token?

If the token is unknown or expired, the answer is 401 INVALID_REFRESH_TOKEN and nothing else happens. If it exists, is unexpired, but was already revoked, someone is reusing a rotated token, which is a sign of theft, so I revoke all active refresh tokens of that player and return 401 REFRESH_TOKEN_REUSED. The revocation runs in a separate REQUIRES_NEW transaction, because the method then throws and the outer transaction rolls back, which would undo the revocation. The trade-off is that a harmless double-submit by a buggy client logs the user out everywhere. The test replays an old token and then shows that the player's other session is dead too.

11.5 Security and safety

How do you stop an automated service from banning someone on weak evidence?

In ModerationService.enforceGuardrails: a SERVICE account must use source TELEMETRY or JUDGE, and a BAN from a service needs a confidence of at least 0.80 from configuration, otherwise 422 CONFIDENCE_REQUIRED or CONFIDENCE_TOO_LOW. A doubtful case must be a FLAG or NOTE with requiresHumanReview, which lands in the moderator queue. The trade-off is that the threshold is one number, and Arena trusts the confidence the caller reports; it cannot verify it. Arena's rule is a floor that holds even if the calling service is buggy. The test checks no confidence, 0.79 (rejected) and 0.80 (accepted).

How are passwords and tokens stored?

Passwords are hashed with bcrypt (default strength) and never stored in clear. Refresh tokens are stored as SHA-256 hashes. The signing secret and the account passwords come from environment variables, validated at startup (the secret must be at least 32 characters), and the repository has only placeholder values in .env.example. One check from the spec, searching the whole repository for passwords, cannot be run yet because the folder is not a git repository.

How do you stop a player acting as someone else or reading other people's e-mail?

For "me" operations the player id always comes from the verified token (CurrentUser.id(jwt)), never from the request body. Roles are enforced with @PreAuthorize on each controller method, and getById builds the response without an e-mail, which @JsonInclude(NON_NULL) then leaves out. The test shows /me contains the e-mail and /players/{id} does not, and that a PLAYER calling a service-only or moderator-only endpoint gets 403.

What are the security gaps you know about?

No rate limiting on login, register or appeals; /actuator/prometheus is open for local scraping; an invalid body sent by a caller with the wrong role gets 400 instead of 403; and from reading the code I think two simultaneous refreshes of one token could both succeed, and an unknown username might answer slightly faster than a wrong password. I have not tested the last two. I would fix them in that order of value: rate limiting first, then the refresh race.

11.6 Testing

Why Testcontainers instead of an in-memory database?

Because the behaviour I care about only exists in real PostgreSQL and Redis: the trigger, COLLATE "C" tie ordering, FOR UPDATE locks, percentile_cont, and Redis sorted-set ordering. An in-memory fake could pass while production fails. The cost is that Docker must be running and the first class takes about 21 to 23 seconds to start the app and the containers; the whole ./mvnw verify still took about 55 seconds in my runs. Each test starts from truncated tables and a flushed Redis.

How did you test concurrency, and how much do you trust those tests?

Two tests start two threads and release them together with a CountDownLatch: one races two requests with the same externalId, the other races two bans on one player. I assert the invariants that must hold, one winner, one row, one conflict. I trust them for the invariants, but not as proof that the race path was hit on every run, since the outcome depends on timing. I would not say the concurrency is "proven"; I would say it is checked and reasoned about.

What does 89.6% coverage tell you, and what does it not?

It says that 1,047 of 1,169 lines were executed by the tests in my run, and the build fails below 85%. It does not say the assertions are good, and branch coverage is only 65.9%, so many "else" paths are not exercised. For example, the Redis failure path and the simultaneous-refresh case have no test. I treat coverage as a floor that catches forgotten code, not as a quality score.

11.7 Java, language and code quality

Why records for DTOs, constructor injection and an injected Clock?

Records give immutable data with almost no code, which suits JSON request and response shapes and typed settings. Constructor injection with private final fields makes a class easy to build by hand in a test and makes missing dependencies a compile or startup error. Injecting a Clock means time is a parameter instead of a hidden global. The trade-off is slightly more typing. The limit I learned: the clock only controls my code; a library's own expiry check still uses real time, which is exactly the bug in my failing test.

Why TransactionTemplate in one service and @Transactional everywhere else?

@Transactional is shorter and fine when the whole method either succeeds or fails together. In recordMatch and in the refresh-token reuse branch I need to act after a transaction has ended or in a separate one: catch a unique-key violation after rollback, or commit a revocation even though the method then throws. A TransactionTemplate lets me do that explicitly. The trade-off is less common code, so each use has a comment saying why.

Why only certain Lombok annotations, and no @Data on entities?

Generated equals, hashCode and toString on JPA entities interact badly with lazy loading and proxies: they can trigger extra queries or compare the wrong things. So the project allows only @Getter, @Setter, @NoArgsConstructor(access = PROTECTED) and @Slf4j. The one entity that needs equals, the composite key MatchParticipantId, has it written by hand. This is a convention enforced by review, not by a tool.

What changed with Spring Boot 4 that you had to deal with?

Several imports moved: Jackson 3 uses tools.jackson.databind.json.JsonMapper while its annotations stay under com.fasterxml.jackson.annotation, test annotations such as @AutoConfigureMockMvc live in new packages, Testcontainers 2 dropped the generic PostgreSQLContainer<?>, and springdoc needs the 3.x line. I kept Boot 4 and fixed the imports rather than downgrading. The project's check, that nothing imports com.fasterxml.jackson.databind, returns nothing.

11.8 Honesty questions

What is missing or unfinished?

Rate limiting, a transactional outbox for the Redis sync, Kafka events, a running CI, Grafana dashboards, and any real integration with the telemetry and judge projects: none are built. The build is not green today: ./mvnw verify runs 71 tests, 70 pass and one errors, a test that depends on the day it was run (the application code is not affected; with failures ignored, JaCoCo reported 89.56% line coverage and the 85% gate was met). I would fix that test and re-run before claiming green. The two tagged metrics are not visible from startup. The repository is not under git yet and has files that I would remove before publishing (an unrelated React stub, notes, the spec). I would say all of that plainly, and I would say which parts I consider finished: the 18 endpoints, the state machine, the audit log, the leaderboard and its sync, and the tests around them. I would not claim that the CI works, because that workflow has never run.

Tell me about a bug or a surprise.

Three. First, the app crashed at startup on an empty database because a percentile query returned NULL and JdbcClient rejects that; found only by running the whole stack, fixed with an Optional. Second, every integration test failed to load because Spring Boot replaces a whole list property when a test sets one indexed entry, so a service's username became null; fixed by setting usernames in the tests too. Third, today I found that TokenServiceTest only passed within 15 minutes of a fixed date, because the decoder checks expiry against the real clock. I have not changed it yet; the fix is to give that test's decoder the same fixed clock. The lesson: a green build on one day is not proof, and a fixed clock only controls code that uses it.

What performance have you measured?

One benchmark: rank lookups with 1,000,000 players, run with k6 at 200 virtual users for 60 seconds after a warm-up. The Redis path had p95 63.5 ms and about 5,764 requests per second; the database path had p95 18.0 s and about 12.6 requests per second. I would not quote that as general performance: it was one session on one desktop, with three runs per source of which only the third summary was saved, k6 shared the Docker VM with Arena, and I deleted the data afterwards. What I can say confidently is that the Redis path is orders of magnitude faster than counting rows, and why: O(log N) in memory against a count over a million rows through a 20-connection pool.

What would you do differently or next?

In order: fix the time-dependent test; add rate limiting on login, register and appeals; replace the in-process after-commit listener with a transactional outbox so a crash cannot leave Redis stale; make the rebuild compare scores, not just counts; register the tagged metrics at startup; run the benchmark in several separate sessions and save every summary. Also push the code to a real repository and see the CI go green. I would not add Kafka or a front end until the first three were done.

"How did you build this, and can you explain every choice?" This one you must answer from your own experience, so there is no sample answer. What the repository records: the work followed a written specification in 12 steps, a full run against real containers exposed two real bugs, and the code was cleaned up afterwards. If you used an AI assistant, say so plainly and say what you did yourself (reviewing, running the stack, deciding what to fix). Then show that you can explain the choices in this section without notes. todo.md gives the same advice: be upfront, and be able to explain every design choice unprompted.

12. How to practise reading the code

Reading is not enough; you need to predict, break and fix. Eight exercises, from easiest to hardest. There is no git history in this folder, so before you break anything, copy the file you are about to change (for example to AccountStateMachine.java.bak) and put it back afterwards. All commands run from arena/ with Docker running.

Exercise 1: predict, then check

Without running anything: what does stateMachine.next(AccountStatus.FLAGGED, ModerationActionType.FLAG) return? Answer to check against the code: it throws ApiException with INVALID_STATE_TRANSITION (a flagged player cannot be flagged again). Open AccountStateMachineTest and confirm that the map of legal pairs has no entry for it. Run ./mvnw test -Dtest=AccountStateMachineTest; you should see 35 passing.

Exercise 2: break a rule on purpose (unit level)

In AccountStateMachine, add AccountStatus.FLAGGED to the set for FLAG. Predict which test fails and how many. Check: AccountStateMachineTest, exactly one of the 35 cases (FLAGGED + FLAG now returns a status instead of throwing). Put the file back.

Exercise 3: break the guardrail (integration level)

In ModerationService.enforceGuardrails, change compareTo(...) < 0 to <= 0. Predict what happens to a service ban at exactly 0.80 and which test notices. Check: the ban at 0.80 is now refused with CONFIDENCE_TOO_LOW, and ModerationIntegrationTest.appliesAllowedTransitionsRejectsInvalidAndEnforcesGuardrails fails at the step "Service BAN at 0.80 -> 201". Run it with ./mvnw test -Dtest=ModerationIntegrationTest. This shows why the test uses the boundary values 0.79 and 0.80.

Exercise 4: change a setting

In application.yml change arena.rating.max-delta from 30 to 20. Predict first: will RatingCalculatorTest still pass? Will MatchIntegrationTest? Check: RatingCalculatorTest still passes, because it calls the two-argument delta, which uses the constant DEFAULT_MAX_DELTA = 30. MatchIntegrationTest.recordsMatchUpdatesRatingsTotalsRedisAndIsIdempotent fails: it expects 1030 and 970, but the service reads the setting, so it produces 1020 and 980. Lesson: the same rule exists as a default constant and as a setting. Restore the file.

Exercise 5: recompute a number by hand

Use the formula round(30 * (N + 1 - 2p) / (N - 1)) for a 9-player match. Compute places 2 and 8. Check: place 2 is 30 * 6/8 = 22.5, which Java's Math.round turns into +23; place 8 is 30 * (-6)/8 = -22.5, which becomes -22 (Math.round rounds halves toward positive infinity). So the two changes do not cancel. For all nine places the changes are 30, 23, 15, 8, 0, -7, -15, -22, -30, which add up to +2: a little rating is created by rounding. Then add a row to RatingCalculatorTest's @CsvSource (9, 2, 23 and 9, 8, -22) and run it.

Exercise 6: draw a sequence diagram

On paper, draw the actors Client, AuthController, AuthService, RefreshTokenRepository, requiresNewTx and PostgreSQL. Draw the call POST /auth/refresh with a token that was already used (revoked, not expired). Mark: where the outer transaction begins, where the inner REQUIRES_NEW transaction begins and commits, where the exception is thrown, and where the outer transaction rolls back. Explain why the revocation survives the rollback. Compare with 5.3.

Exercise 7: explain it aloud

Set a timer for two minutes and explain, without notes, "why is Redis updated after commit, and what can go wrong?" Use the pattern decision → reason → trade-off → how it was checked. Then compare with the answer in 11.2. Repeat for "why a trigger for the audit log" and "what happens when two requests record the same match".

Exercise 8: fix the failing test

Open TokenServiceTest.issuesAccessTokenWithExpectedClaimsHeaderAndExpiryFromClock. Find the line where the decoder is built, and the line that decodes. Predict why the failure message says Jwt expired at 2026-11-17T10:15:00Z although the token was made with a fixed clock. Then decide how to make the test independent of the real date (for example by giving the decoder a timestamp validator that uses the same fixed clock, or by turning the timestamp validation off for this test; check the Spring Security API before you pick). Run ./mvnw test -Dtest=TokenServiceTest and then the whole ./mvnw verify. Update the numbers in handoff.md, todo.md, CLAUDE.md and in section 0 of this guide when it is green.

A 5-step method for any unfamiliar file

  1. Place it. Read the package and the class name: which layer is it (controller, service, repository, entity, DTO, config)? What is it named after?
  2. Read the constructor and the fields. What does it depend on? Those names are the other files you may need to open.
  3. List the public methods and write one sentence for each, in your own words, before reading their bodies.
  4. Follow one happy path line by line, then follow each throw to see which error code it produces and when.
  5. Open its test and confirm your sentences. Anything the test does not cover, mark as "unverified" in your notes.

13. Glossary

TermMeaning here
Access tokenA short-lived (15 min) signed JWT that proves who you are on each request.
ActuatorSpring Boot's built-in health and metrics endpoints (/actuator/health, /actuator/prometheus).
AimbotCheat software that aims for the player. Why this platform exists.
AnnotationA @Label on a class or method that tells a framework what to do with it.
Append-onlyRows may be added but never changed or deleted. Enforced for moderation_actions by a trigger.
AppealA banned player's request for a moderator to review the ban. At most one per ban.
AssertJTest library with readable checks: assertThat(x).isEqualTo(y).
Audit logThe table moderation_actions: a permanent record of every status change and note.
BeanAn object created and managed by Spring.
Bearer tokenA token sent as Authorization: Bearer <token>.
bcryptA slow, salted, one-way password hash.
Branch coverageThe share of if/else paths that tests took (65.9% here, not gated).
ClaimA named value inside a JWT, such as sub or roles.
CIContinuous integration: a server that builds and tests every push. Written here, never run.
Collation (COLLATE "C")The rule for ordering text. "C" means plain byte order.
Commit / rollbackMake a transaction's changes permanent / undo them all.
ConfidenceA number 0 to 1 sent with a service ban: how sure the caller is.
Constructor injectionA class receives its dependencies as constructor parameters.
Contract (API)The fixed paths, fields, enums, codes that other services rely on.
ControllerThe class that receives HTTP requests and calls a service.
CSRFA browser attack on cookie sessions; switched off because Arena uses bearer tokens.
DeadlockTwo transactions each waiting for a lock the other holds.
DTOData transfer object: a record describing JSON going in or out.
EligibleA PLAYER who is not BANNED or APPEALED: may play and be ranked.
EntityA Java class mapped to a database table.
EnumA fixed set of named values.
Event (Spring)A small object published to listeners, such as RatingChanged.
externalIdThe caller's own id for a match; unique, so retries are safe.
FlagMark a player as suspicious (FLAG action, status FLAGGED). Not a ban.
FlywayTool that runs numbered SQL migration files once, in order.
GuardrailA rule that stops a caller from doing something risky (the 0.80 ban threshold).
Hash (SHA-256)A one-way fingerprint of data. Refresh tokens are stored only as hashes.
HikariThe database connection pool (20 connections here).
HS256JWT signing with HMAC-SHA-256 and one shared secret.
IdempotentSafe to repeat: doing it twice equals doing it once.
JaCoCoTool that measures line coverage and enforces the 85% gate.
JdbcClientSpring's helper for running plain SQL.
JPA / HibernateMaps Java objects to tables.
JSONText format for data used in requests and responses.
JWTJSON Web Token: signed, readable claims.
k6A load-testing tool, used for the benchmark.
Keyset paginationPaging with WHERE id > :last instead of OFFSET.
Lateral joinA join whose right side can use values from the current left row.
LeaderboardRanking of eligible players by rating.
LombokCompile-time tool that generates getters, setters and a logger.
MapStructGenerates object-to-object mapping code.
MicrometerThe metrics library behind /actuator/prometheus.
MockMvcSends fake HTTP requests to the app inside a test.
Optimistic lockingA version column; the loser of a race fails at update time.
PercentileWhere a value sits among all players, 0 to 100.
Pessimistic lockingLock rows first with SELECT ... FOR UPDATE.
p50 / p95 / p99The time under which 50% / 95% / 99% of requests finished.
PipeliningSending many Redis commands in one round trip.
PostgreSQLThe relational database holding the truth.
ProblemDetailThe standard JSON error shape (RFC 7807) with an extra code.
Prometheus / GrafanaCollector of metrics / dashboard tool.
RecordA Java class for immutable data with generated accessors.
RedisFast in-memory data store used for the leaderboard.
Refresh tokenA long-lived random token used only to get new access tokens; rotated on use.
RepositoryAn interface for database access, implemented by Spring Data.
REQUIRES_NEWRun in a brand-new transaction that commits on its own.
RESTStyle of web API: nouns in paths, verbs as HTTP methods.
RolePLAYER, MODERATOR or SERVICE.
Service accountA non-human account (telemetry-sim, judge-agent) with role SERVICE.
Source (action source)Who made a moderation action: HUMAN, TELEMETRY, JUDGE, SYSTEM.
Source of truthThe one place whose data wins if copies disagree (PostgreSQL).
State machineA fixed table of allowed moves between states.
StatelessThe server remembers nothing between requests.
Swagger UI / OpenAPIAn interactive page and a machine-readable description of the API.
TestcontainersStarts real services in Docker for tests.
ThroughputRequests handled per second.
TransactionA group of database changes that succeed or fail together.
TriggerA database function that runs automatically on insert, update or delete.
UUIDA 128-bit random identifier, generated in Java here.
Virtual threadA very light Java thread, cheap to block.
VU (virtual user)One simulated user in a load test.
ZSETRedis sorted set: members ordered by a numeric score.