How otomo works: the big picture¶
Otomo is a self-hosted backend for live-service games. It is the set of servers that sits behind a Godot game and handles everything that is not gameplay: delivering content updates, signing players in, keeping friends and parties, matching players into games and handing them a game server, running the in-game economy, and letting your staff run the live game.
This page is the map. It shows the two halves of the system, draws every service, follows a request through it, and lists what each service is for and who calls it. The other pages in this section go deep on one area each; the last section of this page links to them.
Who this section is for
These pages are for engineers who will run, debug or change otomo. If you only want to connect a game, start with What is otomo? and How otomo fits together, which explain the same system without assuming you will open the code.
What otomo does¶
| Job | What it means for a game | Where it lives |
|---|---|---|
| Content delivery | New settings, text and Godot resource packs reach players without a new build | Config and Patch |
| Identity | A player gets an account and a signed login pass; staff get their own, separate accounts | Auth and admin-auth |
| Social | Profiles, presence, friends, blocks, follows, parties that double as lobbies | Session |
| Matchmaking and servers | A party or a queue of strangers becomes a match on a dedicated game server | Matchmaker, Allocator, Gameplay Proxy |
| Economy | Wallets, items, shop, gacha, rewards for matches and missions, all in an auditable ledger | Economy |
| Live ops | Close the game for maintenance, force players to update, publish announcements, inspect a player | Ops, Config, the admin website |
| Observability | Metrics, logs and alerts across all of it | Dashboard, Prometheus, Loki |
Otomo is game-agnostic: no service knows a game's words, such as the name of an item or
a mode. A game describes itself in documents (see
Config, Patch and content delivery) and otomo enforces them.
The rule and its reasoning are in design/29-game-boundary.md.
The two planes¶
Everything in otomo belongs to one of two planes, and the planes never share a door.
| Player plane | Staff (admin) plane | |
|---|---|---|
| Who uses it | Players' games, through the Godot SDK | Your team, through the admin website |
| Front door | edge then gateway (HTTPS), and the Gameplay Proxy (UDP) |
gateway_dev only |
| Reachable from | The internet | The host's loopback address, through an SSH tunnel |
| Identity | auth issues player tokens (audience otomo:player) |
admin-auth issues staff tokens (audience otomo:staff) with a role |
| Paths | /auth/, /patch/, /api/player/ |
/admin-auth/, /admin/, /api/admin/ |
A player token is refused on every staff route and a staff token on every player route. The two gateways are separate programs for the same reason: the player gateway does not even contain the staff route table. See Identity and sign-in.
The architecture diagram¶
The wiki build has no diagram plugin, so the diagrams here are text. Read arrows as "calls".
PLAYER PLANE STAFF PLANE
(public internet) (loopback + SSH tunnel)
Godot client Staff browser
| HTTPS | UDP :27000 | http://localhost:8090
v v v
+------+ +---------------+ +-------------+
| edge | |Gameplay Proxy | | gateway_dev |
+--+---+ +-------+-------+ +------+------+
| /auth /patch | forwards after ticket check | /admin-auth /admin /api/admin
| /api/player v |
v +-----------+ +---------+---------+-----------+
+---------+ | gs-1 gs-2 | v v v v
| gateway | | (Godot | +------------+ +-------+ +--------+ +---------+
+----+----+ | servers) | | admin-auth | | admin | | config | |dashboard|
| +-----+-----+ +------------+ | -ui | +---+----+ +----+----+
| ^ register,heartbeat +-------+ | |
| | | blobs | queries
+----+-----+----------+----------+---+-------------+ v v
v v v v v +--------+ Prometheus
+------+ +-------+ +---------+ +-----------+ +---------+ | patch | + Loki
| auth | | patch | | session | | matchmaker| | economy |<--------------------- | (reads |
+------+ +-------+ +----+----+ +-----+-----+ +----+----+ rules via Config | Config)|
| | ^ +--------+
| v |
+-------> allocator ------+ ops: maintenance + update-gate snapshot,
(servers, read by gateway, auth and session
tickets) chat: channels and messages, internal only
Shared underneath: Postgres (one database per service) and Valkey (session, queue, events)
Three things the picture cannot show well:
- Services also call each other. Session calls the Allocator and Economy, the Matchmaker calls the Allocator, Session and Economy, game servers call the Allocator, Config, Economy, Matchmaker and Patch. Those calls use internal listeners and service keys, never the gateways. The table below lists them.
- Config and Patch share data, not requests. Config writes releases to its database and a blob folder; Patch reads both read-only.
- The Allocator has no public door at all. Only Session, the Matchmaker, game servers and the Gameplay Proxy can reach it.
Following one request¶
A player request: "list my friends"¶
- The game sends
GET /api/player/session/friendswithAuthorization: Bearer <access token>tohttps://play.example.com. - edge terminates TLS. The path starts with
/api/player/, so it passes the request togateway. (The edge also strips cookies and, behind a tunnel, decides which client address to believe.) - gateway works from a fixed route table. It limits the rate per client address (20
requests a second by default), checks the token's signature, issuer, audience and expiry
against the keys
authpublishes, applies the maintenance and update gates if they are switched on, and proxies tosession. - session verifies the token again, because no service trusts the gateway's word. It reads Postgres and Valkey and answers.
- The answer returns the same way. Every error uses one JSON shape with a
request_id, which is also in each service's log line.
A staff request: "publish a release to staging"¶
- The browser, on the admin website, sends
POST /api/admin/config/channels/staging/releasesthrough the SSH tunnel togateway_devon127.0.0.1:8090. - gateway_dev verifies the staff token against
admin-auth's keys and applies the coarse role bar for the route (for Config it isviewer, except publishing tolive, which needsadmin). - config verifies the token a second time and applies its own, finer role table (this
route needs
live_ops), writes the release in one database transaction, then notifies Patch.
Game traffic: "play the match"¶
Game traffic is not HTTP. After matchmaking, the client sends one UDP datagram with its join ticket to the Gameplay Proxy on port 27000. The proxy checks the ticket's signature, expiry and single use, then forwards that client's packets to the right private game server and the replies back. See Matchmaking and game servers.
The service map¶
Every row is a container in deploy/compose.yaml. Ports are inside the Docker network unless
the Published column says otherwise.
Player plane¶
| Service | Job | Called by | Published |
|---|---|---|---|
edge |
nginx front door: TLS, routes /auth/, /patch/, /api/player/ to the gateway, /docs/ to the wiki, / to a game site |
The internet | 80 and 443 (profile edge) |
gateway |
Player API gateway: token check, rate limits, route table, gates | edge |
127.0.0.1:8080 by default |
auth |
Player accounts, device login, refresh tokens, signing keys, player JWKS | gateway |
No |
patch |
Serves release manifests, content blobs and recordings; the server manifest internally | gateway, gateway_dev, Session, Matchmaker, Chat, Ops, game servers |
No |
session |
Profiles, presence, friends, follows, parties, lobby, loadout, rank, the event long-poll | gateway, gateway_dev, Allocator, Matchmaker, Chat, Economy |
No |
matchmaker |
Queue of waiting parties, forms matches, tells Economy a match happened | gateway, Allocator, game servers, Chat |
No |
allocator |
The game-server pool, reservations, join tickets | Session, Matchmaker, game servers, Gameplay Proxy | No |
gameplay-proxy |
The one public UDP door to game servers | Players' games | UDP 27000 |
gs-1, gs-2 |
Your Godot dedicated servers (profile gameservers) |
Gameplay Proxy | No |
economy |
Ledger, wallets, items, shop, gacha, tasks, entitlements | gateway, gateway_dev, Session, Matchmaker, Chat, game servers |
No |
chat |
Channels and messages for adapters; no player-facing listener | Game-specific adapters | No |
Staff plane¶
| Service | Job | Called by | Published |
|---|---|---|---|
gateway_dev |
Staff gateway: admin routes, the admin website, staff login | The staff browser | 127.0.0.1:8090 |
admin-auth |
Staff accounts, roles, passwords, TOTP, invites, staff JWKS | gateway_dev, and every service that verifies staff tokens |
No |
admin-ui |
The admin website (a static single-page app) | gateway_dev |
No |
config |
Namespaces, drafts, versions, packs, releases, channels, audit | gateway_dev, game servers, Economy |
No |
dashboard |
A query layer over Prometheus and Loki, plus the merged audit feed and the game-server release view (the Allocator's per-server report against the channel head read from Patch with the caller's staff token) | gateway_dev |
No |
ops |
Maintenance state and the update-gate snapshot | gateway_dev, and the enforcers (gateway, auth, session) |
No |
Shared infrastructure¶
| Service | Job |
|---|---|
postgres |
One cluster, one database and one login role per service, so a service cannot read another's data. The one exception is Patch, which reads Config's database as a read-only role |
valkey |
Fast shared memory: Session's presence and events, the Matchmaker's queue index, Chat |
registry |
A private Docker image registry on 127.0.0.1:5000 |
prometheus, loki, alloy, node_exporter, cadvisor, postgres_exporter |
Metrics and logs; see Deployment and operations |
wiki-docs, wiki-site |
This documentation and an optional game site, built by services/wiki |
edge-proxy, cloudflared |
The edge behind a tunnel, for hosts that cannot own ports 80 and 443 (profile tunnel) |
gatepolicy is not a service. It is a Go library that Gateway, Auth, Session, Ops and Config
share so they all make the same maintenance and update-gate decision. services/cli is a
placeholder with no behaviour yet.
How the services are built¶
Every Go service follows the same conventions, which makes the code predictable:
- Three listeners. Port
8080is the service's API on the Docker network,8081is the internal API that needs a service key (where there is one), and9090is/healthz,/readyz,/metricsand profiling. None of these is published to the host. - One binary, several commands.
serveis the default;migrateapplies the database schema; some services havegenkeyfor signing keys. In Compose, each service has a one-shot<name>-migratecontainer that must finish before the service starts. - Fail at boot. A service with a wrong setting prints every problem and exits, instead of starting half-configured. Compose's restart policy is the retry loop.
- One error shape. Every
4xxand5xxis{"error": {"code", "message", "request_id"}}. See Error codes. - Metrics and logs. Prometheus metrics named
<service>_<thing>_<unit>and one JSON log line per request.
What is not on this branch¶
Planned
Sign-in with Steam and Google, a public protocol reference and a command-line client are on
the roadmap (ROADMAP.md). They are not part of what this section describes.
Related pages¶
- Identity and sign-in: the two token domains, roles and service keys.
- Config, Patch and content delivery: how content gets from a designer to a player and a game server.
- Matchmaking and game servers: from "Play" to a running match.
- Economy and inventory: the ledger and everything built on it.
- Live ops: maintenance, the update gate and what staff can do today.
- Deployment and operations: the stack, releases, backups and monitoring.
- Glossary and where to look next: terms and the design documents behind each topic.
- How otomo fits together: the same system for a game developer.