Skip to content

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"

  1. The game sends GET /api/player/session/friends with Authorization: Bearer <access token> to https://play.example.com.
  2. edge terminates TLS. The path starts with /api/player/, so it passes the request to gateway. (The edge also strips cookies and, behind a tunnel, decides which client address to believe.)
  3. 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 auth publishes, applies the maintenance and update gates if they are switched on, and proxies to session.
  4. session verifies the token again, because no service trusts the gateway's word. It reads Postgres and Valkey and answers.
  5. 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"

  1. The browser, on the admin website, sends POST /api/admin/config/channels/staging/releases through the SSH tunnel to gateway_dev on 127.0.0.1:8090.
  2. gateway_dev verifies the staff token against admin-auth's keys and applies the coarse role bar for the route (for Config it is viewer, except publishing to live, which needs admin).
  3. 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 8080 is the service's API on the Docker network, 8081 is the internal API that needs a service key (where there is one), and 9090 is /healthz, /readyz, /metrics and profiling. None of these is published to the host.
  • One binary, several commands. serve is the default; migrate applies the database schema; some services have genkey for signing keys. In Compose, each service has a one-shot <name>-migrate container 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 4xx and 5xx is {"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.