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.
Related pages¶
- How otomo works: the big picture
- Glossary: the general terms.
- Wikis and sites: how to propose a change to these pages.
- Troubleshooting