The API (apps/api) answers every read and write the panel makes, signs people in, serves this handbook and the developer API that game servers call. It is a NestJS app in TypeScript, two copies in production, reachable only through the panel's proxy. Every request goes through the same guards in the same order, and most reads are answered from a Redis cache that new data invalidates within about 30 seconds.
How the API is organised
Each feature is a module under apps/api/src/modules/, hexagonal like the worker's: its rules (domain), its use cases and the ports they need (application), adapters to Postgres, Redis or outside services (infrastructure), and its HTTP routes (presentation). What every module shares is under apps/api/src/shared/. A linter fails the build when an import crosses the layers the wrong way.
- apps/api/src/
- modules/one folder per feature
- games/market reads: games, history, genres, the market overview
- auth/sign-in, sessions, the session guard, membership checks
- assistant/the front door to the assistant app
- developer/game API keys, feedback, the developer API's reads
- handbook/this handbook: list, page, search
- notifications/the inbox, preferences, push devices
- system/the collector status and admin pages
- shared/
- cache/the read cache, its policies and interceptor
- http/validation pipe, error contract, request ids
- database/the read and write pools
- redis/the fail-fast Redis client
- modules/one folder per feature
The other modules are contracts, creators, credentials, dashboard, discovery, github, home, player-hours, portfolio, radar, studio-site and watchlist. Every request and answer shape is a schema in packages/contracts, checked on both sides.
What every request goes through
The session guard
Refuses (403) a change marked cross-site or from another origin, resolves the session from its token hash (Redis, else Postgres), refuses (403) a change without the
x-requested-with: scrywaveheader, and refuses members on an owner-only route, all before any body is read. See Authentication and permissions.The rate-limit guard
Counts the request against your limits per person and per address (below).
Validation
Every path parameter, query and body goes through one pipe with a schema from
@repo/contracts. A body with a field the schema does not name is refused; ids in paths are plain decimal digits; pages and ranges are fixed lists.The read cache
A cached
GETis answered from Redis when nothing has changed since it was last read; otherwise the use case reads Postgres and the answer is stored.The answer
JSON, with
X-Request-Id, security headers, andCache-Control: no-storeon every private route so no browser or proxy keeps it.
The read cache: how repeated reads are answered from Redis
A GET route opts in with @CacheRead(policy), and a global interceptor applies it. The answer is stored as the JSON the route would have sent, under a key made of the route, a hash of the path, of the query as the route reads it (defaults filled in, parameters it ignores left out), of the person when the policy is personal, and the current data versions of the domains it reads.
- market
/v1/market*,/v1/games, a game, its history and sort ranks,/v1/genres,/v1/rolimons,/v1/radar,/v1/sorts*,/v1/creators/*. Fresh 60 s, then served stale once for up to 300 s while one refresh runs. Shared by everyone.- github
Every
GET /v1/github/*. Fresh 120 s, stale up to 600 s. Shared, except Members and a member's page, which are per person because owners see two-factor status.- studio
/v1/studio/*, the studio games on Discovery and a game's hours of the week. Reads the studio and market versions. Fresh 60 s, stale up to 300 s; a game's hub, its bans, a project's detail and your points are per person.- developerMarket
The developer API's market reads, keyed by path and query, never by key, after the key is checked on every request. Fresh 60 s, stale up to 300 s.
- site
The public website's
/public/site. Fresh 60 s.
How new data invalidates the cache (data versions)
Freshness is a counter, not a clock. Each domain, market, github and studio, has a version in Redis (data:v:<domain>). A bump changes every key that holds that domain's version, so the next read goes to Postgres; old entries are never hunted down and simply expire.
- market bumped by
The worker, after a snapshot batch, metrics recompute, sort reading, recommendations, creators, icons or Rolimon's run that handled anything.
- github bumped by
The worker, after every GitHub collection run, successful or not.
- studio bumped by
The worker after owned analytics stored rows or a game was released; the API after a game server's feedback is stored.
- all bumped by
The API, after any successful change (POST, PUT, PATCH, DELETE) outside sign-in, your own settings, notifications, the assistant and the developer API.
The worker bumps one domain at most once every 30 seconds (DATA_VERSION_INTERVAL_MS), with one trailing bump for changes inside the window, so snapshot batches every few seconds do not empty the cache all the time. A bump never fails a job; if Redis is away, entries expire on their own clock.
Many readers of one key at once
Requests for a key that arrive while it is being read wait for that read and share its answer, never its failure: if the read fails, each waiter reads for itself, uncached. This is also why a cost charged per person, such as looking up an untracked game on Roblox, is charged in a guard before the cache.
Cache headers: X-Cache and ETag
- X-Cache
hit,stale(served once while one refresh runs),miss,shared(joined a read under way) orbypass(Redis not in use).- ETag
A strong validator of the body on cached routes. Send it back as
If-None-Matchand an unchanged answer is304with no body.- X-Request-Id
The request's id, also in every error body and log line, so a failure the panel shows can be found in the logs.
GET /v1/collector reports the cache's hits, stale answers, misses, shared reads, errors and hit rate.
When Redis is not there
Without Redis, or with API_CACHE=off, every read goes to Postgres; identical reads arriving together still share one query. With Redis configured but down, commands fail at once, the read goes to Postgres, and the cache leaves Redis alone for five seconds. Rate limits then count per process, and requests go through rather than fail.
API rate limits
| What | Limit per person, per minute | Setting |
|---|---|---|
| Reads | 600 | API_RATE_LIMIT_READ |
| Writes | 120 | API_RATE_LIMIT_WRITE |
| Searches, exports, assistant questions | 60 | API_RATE_LIMIT_EXPENSIVE |
| Calls that reach Roblox or GitHub | 20 | API_RATE_LIMIT_EXTERNAL |
Each client address may make twice a person's limit. Counts are kept in Redis in one-minute windows shared by both copies. A game's servers, with its API key, get 120 requests a minute per key and 1,200 for every key together. Sign-in has its own limits per address: 20 starts and returns, 30 account changes and 600 reads a minute.
Size and time limits
- BodyKiB
256, JSON only (
API_BODY_LIMIT_BYTES); larger is413.- AddressKiB
2, query included; longer is
414.- Request timeseconds
20 by default (30 to 60 on a few slow routes); past it,
503 timeout.- Statement timeseconds
8 on reads, 15 on everything else, set on each database connection.
- Connections
8 for reads and 4 for writes, per copy.
Errors: one shape for every refusal
Every refusal has one body, { "error": { "code", "message", "requestId", "issues"? } }. code is stable for code, message is a sentence for a person, issues names fields. No answer carries a stack trace, SQL, a table name or a value the request sent.
| Status | code | When |
|---|---|---|
| 400 | validation_failed | A parameter, query or body failed its schema |
| 401 | unauthenticated | No session that counts |
| 403 | forbidden | Not an owner or not this record's lead, a cross-site change |
| 404 | not_found | Not tracked, not yours, or no such route |
| 409 | conflict | Already exists, or another change got there first |
| 422 | constraint_violated | A value breaks a rule the database enforces |
| 429 | rate_limited | Over a rate limit; Retry-After says when |
| 503 | timeout | The request or a statement ran past its time |
| 503 | unavailable | Postgres cannot be reached, or the API is stopping |
| 500 | internal | Anything else; the request id finds it in the logs |
Conventions every answer follows
- Times
ISO 8601 in UTC, such as
2026-09-29T22:51:21.000Z.- Growth
A ratio:
0.5is +50%.- Unknown
null, never0. See Empty is never zero.- Ids
Universe ids are numbers; GitHub and public place ids are decimal strings.
Related: Architecture, Authentication and permissions, Data model, The developer API.
Updated