How heroiclabs/nakama works
Purpose and executable entry points
Nakama is a Go distributed backend for social and realtime games/apps. The primary binary starts from main.go; command/configuration flags are defined in flags/flags.go and flags/vars.go. It supports schema migration as a command path via migrate/migrate.go, then runs the server against CockroachDB or another Postgres-wire-compatible database.
Public and administrative API boundary
Client request/response APIs are specified in apigrpc/apigrpc.proto, with committed Go gRPC and HTTP/JSON gateway bindings in apigrpc/apigrpc_grpc.pb.go and apigrpc/apigrpc.pb.gw.go. Client endpoint handlers are organized by domain under server/api.go, server/api_authenticate.go, and server/api_match.go.
Administrative Console APIs similarly derive from console/console.proto; server implementations are in server/console.go and domain-specific server/console_*.go. The embedded browser Console assets are served from console/ui.go and console/ui/dist/.
Core domain and persistence layer
server/core_*.go contains reusable business operations behind API handlers, covering accounts, social graph, storage, wallets, notifications, purchases/subscriptions, leaderboards, and tournaments; representative paths are server/core_account.go, server/core_storage.go, and server/core_leaderboard.go. Database connectivity and database-specific error translation sit at server/db.go and server/db_error.go. Versioned SQL migrations establish the persistent contract in migrate/sql/20180103142001_initial_schema.sql through subsequent migration files.
Authentication, sessions, and request pipeline
Authentication endpoints create and validate identity/session state through server/api_authenticate.go, server/core_authenticate.go, and JWT support in server/jwt.go. Session lifecycle is coordinated by server/session_cache.go, server/session_registry.go, and WebSocket session handling in server/session_ws.go. This boundary protects client and socket operations before they enter shared business logic.
Realtime multiplayer and messaging
WebSocket traffic enters via server/socket_ws.go and is dispatched through server/pipeline.go plus domain pipeline stages such as server/pipeline_match.go and server/pipeline_rpc.go. Realtime state is coordinated by the stream/tracker and message-routing layer (server/stream_manager.go, server/tracker.go, server/message_router.go). Matchmaking and authoritative match execution are separated into server/matchmaker.go, server/match_registry.go, and server/match_handler.go; parties have parallel registries/handlers.
Runtime extensibility
Custom game logic is loaded and exposed through a language-neutral runtime layer in server/runtime.go and server/runtime_config.go. Native Go, JavaScript/TypeScript, and Lua implementations are hosted by server/runtime_go.go, server/runtime_javascript.go, and server/runtime_lua.go; Lua execution relies on the vendored engine under internal/gopher-lua/. Runtime code can register RPCs, hooks, match logic, and server-side integrations, forming an intentional extension boundary around core services.
Scheduling, caches, operations, and delivery
Leaderboard/tournament rank and schedule work is maintained by server/leaderboard_cache.go, server/leaderboard_scheduler.go, and server/core_tournament.go. Metrics and shutdown coordination reside in server/metrics.go and server/shutdown.go. Deployment targets are Docker images defined by build/Dockerfile and Compose environments such as docker-compose.yml; the material external dependency is CockroachDB/Postgres-compatible storage. Purchase validation integrations are represented by iap/iap.go and iap/iap_samsung.go.
Main entry points: core_account.go Domain operations · main.go Server binary · db.go Database layer · api.go Client API handlers
Components 22
Startup & Delivery
- Server binary · Starts migration or the distributed backend server.
main.go - Flags & config
flags/flags.go - Migration command
migrate/migrate.go - Docker deployment
build/Dockerfile
API Boundaries
- Client API contract · Generated bindings expose client APIs over gRPC and HTTP/JSON.
apigrpc/apigrpc.proto - Client API handlers
server/api.go - Console API contract
console/console.proto - Console server & UI · Serves administrative APIs and embedded browser assets.
server/console.go
Server Core
- Auth & sessions · Authenticates requests and coordinates JWT, session cache, registry, and WebSocket sessions.
server/api_authenticate.go - Domain operations · Reusable account, social, storage, wallet, notification, purchase, leaderboard, and tournament operations.
server/core_account.go - Leaderboard scheduler
server/leaderboard_scheduler.go - Metrics & shutdown
server/metrics.go
Realtime & Runtime
- WebSocket ingress
server/socket_ws.go - Socket pipeline · Dispatches socket messages to match, RPC, and other domain stages.
server/pipeline.go - Streams & routing · Tracks stream presence and routes realtime messages.
server/stream_manager.go - Matchmaking & matches · Separates matchmaking, match registry, and authoritative handlers.
server/matchmaker.go - Extension runtime · Registers RPCs, hooks, match logic, and integrations.
server/runtime.go - Go, JS & Lua hosts
server/runtime_go.go
Persistence & Integrations
- Postgres-compatible DB · CockroachDB or another Postgres-wire-compatible store.
- Database layer
server/db.go - Versioned SQL schema
migrate/sql/20180103142001_initial_schema.sql - Purchase validation
iap/iap.go
Connections 25
- Server binary → Flags & config: reads
- Server binary → Migration command: runs migration mode
- Server binary → Database layer: initializes
- Server binary → Metrics & shutdown: coordinates lifecycle
- Docker deployment → Server binary: packages
- Migration command → Versioned SQL schema: applies
- Versioned SQL schema → Postgres-compatible DB: defines
- Database layer → Postgres-compatible DB: connects
- Client API contract → Client API handlers: binds to
- Client API handlers → Auth & sessions: authenticates through
- Client API handlers → Domain operations: invokes
- Console API contract → Console server & UI: binds to
- Console server & UI → Domain operations: administers
- Auth & sessions → Domain operations: authorizes
- WebSocket ingress → Auth & sessions: validates sessions
- WebSocket ingress → Socket pipeline: forwards messages
- Socket pipeline → Streams & routing: routes via
- Socket pipeline → Matchmaking & matches: dispatches match traffic
- Matchmaking & matches → Extension runtime: executes custom logic
- Extension runtime → Go, JS & Lua hosts: hosts
- Extension runtime → Domain operations: extends
- Domain operations → Database layer: persists through
- Domain operations → Purchase validation: validates purchases
- Leaderboard scheduler → Domain operations: maintains ranks & tournaments
- Leaderboard scheduler → Database layer: uses