The platform is six apps in one repository, two data stores, and a language model on the studio's own server. Only the panel, the public website and the public docs can be reached from the internet; everything else talks inside the studio's cluster.
The apps
| App | Folder | What it does |
|---|---|---|
| Panel | apps/panel | The studio's web app at studio.blockoutgames.com: every page you use, and the door to the API |
| API | apps/api | Answers every read and write of the panel from the database; sign-in; the developer API |
| Collector | apps/worker | The background worker: reads Roblox, Rolimon's and GitHub on schedules and stores what it reads |
| Assistant | apps/ai | The chat assistant: plans an answer with the language model and reads data through the API |
| Website | apps/www | The public website at www.blockoutgames.com |
| Docs | apps/docs | This handbook and the developer API's reference, public at docs.blockoutgames.com |
The panel, the website and the docs are Next.js; the API, the collector and the assistant are NestJS services in TypeScript. Apps never import each other's code: what two share lives in packages/ (the contracts both sides check, the database schema, the Roblox client, the handbook, push, UI components).
The panel
The panel renders pages on its server and sends them to your browser. It holds no data of its own: it asks the API for everything, through its own /v1 proxy, carrying your session. It also forwards sign-in (/auth/*) and the developer API (/developer/*) to the API, so the API itself never faces the internet. Its service worker (/sw.js) only shows push notifications; it caches no page.
The public docs
Every page of this handbook is public at docs.blockoutgames.com, with nothing to sign in to. The docs app reads packages/handbook when it is built and writes every page then; its search answers from the same pages, and it never calls the studio's API. The panel has no docs of its own: its Docs opens the site, and the assistant reads the same pages and cites them on the site, so they always agree. The docs app also serves the developer API's OpenAPI 3.1 document and an interactive reference, whose "Try it" sends requests from the reader's browser to the panel's /developer/v1, which answers that one site's requests (CORS). See Trying the API from the docs.
The API
The API reads and writes Postgres, checks every request's session and permissions, applies rate limits, and keeps a read cache in Redis. It never calls Roblox to answer a page, except to look up a game nobody tracks yet (see The Roblox budget) and for owners' group, key and catalog actions. It runs two copies. It also serves this handbook: it reads the pages from disk, parses them into data and searches them.
The collector (worker)
One copy of the worker runs scheduled jobs from queues in Redis (BullMQ): snapshots, discovery, recommendations, Rolimon's, metrics, notifications, push, the GitHub collection and owned analytics. It writes to Postgres and tells the API's cache when data changed. History can only be collected at the time, so it is never stopped on purpose. See Collector and freshness.
The assistant app
The assistant app has no database. The API signs who is asking and passes the question on; the assistant plans with the language model, then reads data through the API as that person, so it can read only what they can. The model (Qwen3-30B-A3B) runs behind a LiteLLM gateway on the studio's own GPU server on the local network, not an outside service. See The assistant and AI infrastructure.
Postgres and TimescaleDB
One Postgres database holds everything: tracked games and their history, the studio's catalog, projects, contracts, points, people, sessions, notifications and the GitHub snapshots. TimescaleDB splits the large history tables (snapshots, sort readings, recommendations, run log) by time and compresses older parts, and keeps the hourly player means up to date. History tables are append-only: a snapshot is never edited. Every table is described in Data model.
Redis
Redis holds only what can be rebuilt, so losing it loses no data. If Redis is away, reads go straight to Postgres and limits fall back to each process.
- Job queues
The collector's BullMQ queues and schedules. See Jobs and queues.
- Read cache and data versions
The API's cached answers, and the counters that tell it new data arrived. See API and caching.
- Session lookups
Each session's lookup, cached at most 60 seconds, by the hash of its token.
- Rate-limit counts
Shared by both copies of the API, in one-minute windows.
- Answer slots
The assistant's places for answers: one per person, two in all.
- Heartbeat
The collector's status, written every 15 seconds, which the Collector page reads.
How a page request flows
Your browser asks the panel
studio.blockoutgames.comreaches the studio's cluster through Cloudflare's tunnel and its edge gateway.The panel checks your session
Without a session it sends you to sign in. With one, it renders the page on its server.
The panel asks the API
Each part of the page is one read on the API, through the panel's proxy, with your session.
The API checks and reads
It checks your session, role and rate limits, then answers from its Redis cache or from Postgres.
The page arrives
A part whose read failed says so in its own place; the rest of the page still shows.
Nothing on that path asks Roblox or GitHub. Their data was stored earlier by the collector.
Where it is hosted
Production runs on the studio's homelab Kubernetes cluster, in the blockout namespace. Cloudflare provides DNS, TLS and the tunnel for studio.blockoutgames.com (the panel) and www.blockoutgames.com (the website; the bare domain redirects there). The API, the collector, the assistant app, Postgres and Redis have no route from outside, and network policies refuse every connection not listed. The panel, the API and the website run two copies each, so a node can be drained without downtime; the collector, the assistant app, Postgres and Redis one each.
How a change is deployed
A merged pull request builds one image per app. A deployment pull request then pins those images; merging it is the deployment. ArgoCD applies it: the database migration runs first, and the apps roll out only if it succeeds. Rolling back is pinning earlier images the same way. The CI checks, sync waves and secrets are in Deployment and releases.
Backups
A nightly job dumps the database, keeping 14 days in the cluster and, when the backup bucket is set up, 60 days there. The cluster also snapshots the volumes daily. See Backups. History that was never collected cannot be restored: see Freshness and empty numbers.
How the code is organized
One repository holds every app and every shared package, built with pnpm and Turborepo.
- apps/
- panel/the studio's web app (Next.js)
- api/the API (NestJS)
- worker/the collector (NestJS, BullMQ)
- ai/the assistant app (NestJS)
- www/the public website (Next.js)
- docs/the public docs site at docs.blockoutgames.com (Next.js)
- status/the status page at status.blockoutgames.com (Next.js)
- packages/
- contracts/every request and answer shape, checked by both sides
- db/the Drizzle schema and migrations
- roblox/the Roblox client, its rate limiter and resilience
- handbook/this handbook's pages, parser and search
- credentials/sealing keys and signing the assistant's assertions
- push/Web Push
- config/shared TypeScript, lint, test and Next.js settings
- ui/the one component library and stylesheet every web app shares
- testing/fixtures, fakes and the seeded market
- infra/Docker for local work, Kubernetes manifests for production
- docs/the engineering vault
The API, the collector and the assistant are hexagonal: each feature is a module with its rules (domain), use cases (application), adapters to the database or outside services (infrastructure) and its jobs or HTTP routes (presentation). The panel follows Feature-Sliced Design with a views layer. Linters fail the build when an import breaks either pattern.
- apps/api/src/modules/games/
- domain/pure rules, no input or output
- application/use cases, and the ports they need
- infrastructure/Postgres, Redis and outside services behind those ports
- presentation/HTTP routes (or, in the worker, job handlers)
Related: Data model, API and caching, Jobs and queues, Security and privacy.
Updated