Skip to content

Glossary and where to look next

This page has two parts: the words that the architecture pages use, in one place, and a map from "I need to understand X" to the document that is the source of truth for X.

The Glossary in the Reference section defines the general terms (HTTP, Docker, JWT and so on). This page only adds terms that are specific to how otomo is built.

Architecture terms

Term Meaning Read more
Player plane / staff plane The two halves of otomo. The player plane serves games; the staff plane serves your team. They share no door and no token Big picture
Edge The nginx front door (TLS, path routing). Not the same as the gateway Big picture
Gateway / gateway_dev The player API gateway and the separate staff gateway Identity and sign-in
Access token / refresh token A 15-minute signed pass, and a single-use token that is swapped for the next one Identity and sign-in
Token family All refresh tokens descended from one login. Reusing a spent one revokes the family Identity and sign-in
JWKS The public keys a verifier uses to check a token's signature, picked by kid Identity and sign-in
Role (viewer, live_ops, admin) A staff permission level. Each includes the one before it Identity and sign-in
Service key (D4) A static random key one service presents to another's internal listener. One per caller role Identity and sign-in
Internal listener A port (:8081) that needs a service key, is not published and has no gateway route Big picture
Namespace A named JSON document in Config, either client or server audience Config and Patch
Draft / version The editable copy of a namespace, and a frozen numbered copy of it Config and Patch
Release An immutable set of namespace versions, packs and a minimum client version Config and Patch
Channel / head dev, staging or live, and the release each is serving Config and Patch
Pack A Godot .pck file, stored by its SHA-256 Config and Patch
Blob Any stored document or pack, named by its SHA-256 Config and Patch
Client / server manifest The list of a release's client-visible files, and its server-only documents Config and Patch
Bundle The server manifest's documents as one deterministic gzipped tar for a game server Config and Patch
ETag / conditional GET A content fingerprint sent back as If-None-Match; 304 means nothing changed Config and Patch
Recording A replay or similar blob a game server, or the host player of a peer-hosted match, uploads at run time; never part of a release Config and Patch
Party A group of players; also the lobby. Session owns it Matchmaking and game servers
Revision A party's change counter, used to reject out-of-date changes Matchmaking and game servers
Pool / lane A matchmaking rule set from matchmaking.rules; a lane is a pool plus identical lobby settings Matchmaking and game servers
Allocation One reservation of a game server, for a party or a whole match Matchmaking and game servers
Join ticket / credential A short-lived, single-use signed pass for one player and one server Matchmaking and game servers
Descriptor The object that tells a client where and how to connect to its match Matchmaking and game servers
Transport The way clients reach a match: otomo-udp (through the Gameplay Proxy) or photon (a room server) Matchmaking and game servers
Loadout A player's own pre-match selection, a document the game defines and Session stores Matchmaking and game servers
Game boundary The rule that a platform service may not know a game's word Matchmaking and game servers
Ledger The append-only, double-entry journal of money movements Economy and inventory
Faucet / sink System accounts that money comes from, and goes to Economy and inventory
Reward class A named payout in economy.rules. Callers name a class, never an amount Economy and inventory
Ceiling A cap on what one player can receive from a faucet in a rolling window Economy and inventory
Idempotency key A caller-chosen key so a retry returns the first result instead of repeating it Economy and inventory
Pity A per-player, per-pool counter that forces the target rarity after N misses Economy and inventory
Entitlement A reward owed to a player, claimable once, not before available_at Economy and inventory
Track / fact A ladder of claimable rungs, advanced by counters or by typed facts reported by a game server Economy and inventory
Reconciliation The check that every cached balance equals the sum of its ledger entries Economy and inventory
Enforcer A service that applies the ops gates to requests: Gateway, Auth and Session Live ops
Snapshot The one document Ops serves, holding maintenance and update-gate state, with a revision Live ops
Route class A tag on every route (session.read, economy.write...) that gates and exemptions refer to Live ops
Maintenance window A record in Ops with a mode (off, warning, hard), a time range and a notice Live ops
Update gate The rule that refuses builds older than a minimum (426 client_outdated) Live ops
Compose profile A switch (edge, tunnel, gameservers, site) that adds containers to the stack Deployment and operations
Alloy The log collector that feeds Loki Deployment and operations

Where to look next

Each area has a design document (why it is shaped this way), a service README (what is implemented and every setting) and sometimes an OpenAPI file (the machine-readable routes). They live in the repository, not on this site.

Topic Design Service README or other source of truth OpenAPI
Common conventions (error shape, metrics, listeners) design/00-common-stack.md
Gateways and route policy design/05-gateway-techspec.md services/gateway/README.md, services/gateway/ROUTE-POLICY.md, services/gateway_dev/README.md, services/gateway_dev/ROUTE-POLICY.md
Player identity design/06-auth-identity-contract.md, design/07-auth-techspec.md, design/26-auth-split-decision.md services/auth/README.md
Staff identity and the admin plane design/11-admin-plane-plan.md services/admin_auth/README.md, services/admin_auth/TESTING.md
Config (authoring) design/02-config.md, design/17-table-editor.md, design/18-concurrent-editing.md services/config/README.md
Patch (delivery) design/03-patch-minimal.md services/patch/README.md
Session, parties, lobby design/04-session-minimal.md, design/13-player-plane-plan.md services/session/README.md services/session/openapi/admin-players.yaml
Launch, allocator, proxy design/14-launch-handoff.md, design/15-allocator-and-edge-plan.md services/allocator/README.md, services/gameplay_proxy/README.md
Matchmaker and the milestone plan design/19-milestone-2-plan.md services/matchmaker/README.md
Transports and the match handoff design/22-transport-and-capability-modules.md, design/27-match-handoff-contract.md services/session/internal/matchhandoff
The game boundary design/29-game-boundary.md ci/scripts/game-boundary-checks.sh
Economy design/24-economy-and-session-behaviours.md, design/27-item-levels-and-external-periods.md, design/30-mission-facts.md services/economy/README.md
Chat services/chat/README.md
Update gate and maintenance design/23-update-gate.md, design/25-ops-gates.md services/ops/README.md, services/gatepolicy/README.md services/ops/openapi/admin-ops.yaml
Dashboard and observability design/01-dashboard.md services/dashboard/README.md, deploy/observability/
Admin website design/00-common-stack.md (WEB-1 to WEB-8) services/adminui/README.md, services/adminui/ROUTE-MAP.md
Every HTTP route and payload (a snapshot of M1) design/10-communication-schema.md
The Godot SDK design/12-godot-sdk-guide.md godot-plugin/README.md, SDK reference
Edge and TLS design/15-allocator-and-edge-plan.md services/edge/README.md, deploy/docs/EDGE-FRONTS.md
Deploying, releasing, secrets design/00-common-stack.md deploy/README.md
Backup and restore deploy/docs/BACKUP.md
Reaching the staff plane deploy/docs/ADMIN-ACCESS.md
CI ci/services/README.md, .github/workflows/
This wiki's build design/16-wiki-service.md services/wiki/README.md, Wikis and sites
Roadmap design/19-milestone-2-plan.md ROADMAP.md

Read the status line, then check the code

Design documents carry a status (decided, proposal, built on a branch) and a date, and some were written before later work landed. Service READMEs are the best record of what a service does today, but a few opening paragraphs lag behind their own "Scope" section. When a document and the code disagree, the code and its tests win, and the doc should be corrected. Design numbers 27 and 28 each name two documents. Some READMEs and code comments cite planning documents under plans/otomo/; those are not in this repository.