# heroiclabs/nakama architecture

> Architecture diagram of the GitHub repository heroiclabs/nakama, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/heroiclabs/nakama
- Repository: https://github.com/heroiclabs/nakama

## Overview

#### 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: [`server/core_account.go`](https://github.com/heroiclabs/nakama/blob/master/server/core_account.go) (Domain operations), [`main.go`](https://github.com/heroiclabs/nakama/blob/master/main.go) (Server binary), [`server/db.go`](https://github.com/heroiclabs/nakama/blob/master/server/db.go) (Database layer), [`server/api.go`](https://github.com/heroiclabs/nakama/blob/master/server/api.go) (Client API handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Startup &amp; Delivery"]
  node_main["Server binary<br/>Go entry point<br/>[main.go]"]
  node_flags["Flags &amp; config<br/>startup configuration<br/>[flags.go]"]
  node_migration_command["Migration command<br/>command path<br/>[migrate.go]"]
  node_deployment["Docker deployment<br/>container delivery"]
end

subgraph group_api["API Boundaries"]
  node_client_contract["Client API contract<br/>gRPC + HTTP gateway<br/>[apigrpc.proto]"]
  node_client_handlers["Client API handlers<br/>endpoint handlers<br/>[api.go]"]
  node_console_contract["Console API contract<br/>admin API schema<br/>[console.proto]"]
  node_console_server["Console server &amp; UI<br/>admin endpoints<br/>[console.go]"]
end

subgraph group_core["Server Core"]
  node_auth_sessions["Auth &amp; sessions<br/>identity boundary"]
  node_domain_core["Domain operations<br/>business logic<br/>[core_account.go]"]
  node_rank_scheduler["Leaderboard scheduler<br/>rank &amp; schedule worker"]
  node_operations["Metrics &amp; shutdown<br/>operations lifecycle<br/>[metrics.go]"]
end

subgraph group_realtime["Realtime &amp; Runtime"]
  node_websocket["WebSocket ingress<br/>socket transport<br/>[socket_ws.go]"]
  node_socket_pipeline["Socket pipeline<br/>realtime dispatcher<br/>[pipeline.go]"]
  node_stream_routing["Streams &amp; routing<br/>realtime coordination<br/>[stream_manager.go]"]
  node_match_execution["Matchmaking &amp; matches<br/>multiplayer execution<br/>[matchmaker.go]"]
  node_runtime["Extension runtime<br/>game logic boundary<br/>[runtime.go]"]
  node_language_runtimes["Go, JS &amp; Lua hosts<br/>runtime implementations<br/>[runtime_go.go]"]
end

subgraph group_data["Persistence &amp; Integrations"]
  node_database[("Postgres-compatible DB<br/>external database")]
  node_db_layer["Database layer<br/>connection &amp; errors<br/>[db.go]"]
  node_sql_schema["Versioned SQL schema<br/>database migrations"]
  node_iap["Purchase validation<br/>external integration<br/>[iap.go]"]
end

node_main -->|"reads"| node_flags
node_main -->|"runs migration mode"| node_migration_command
node_main -->|"initializes"| node_db_layer
node_main -->|"coordinates lifecycle"| node_operations
node_deployment -->|"packages"| node_main
node_migration_command -->|"applies"| node_sql_schema
node_sql_schema -->|"defines"| node_database
node_db_layer -->|"connects"| node_database
node_client_contract -->|"binds to"| node_client_handlers
node_client_handlers -->|"authenticates through"| node_auth_sessions
node_client_handlers -->|"invokes"| node_domain_core
node_console_contract -->|"binds to"| node_console_server
node_console_server -->|"administers"| node_domain_core
node_auth_sessions -->|"authorizes"| node_domain_core
node_websocket -->|"validates sessions"| node_auth_sessions
node_websocket -->|"forwards messages"| node_socket_pipeline
node_socket_pipeline -->|"routes via"| node_stream_routing
node_socket_pipeline -->|"dispatches match traffic"| node_match_execution
node_match_execution -->|"executes custom logic"| node_runtime
node_runtime -->|"hosts"| node_language_runtimes
node_runtime -.->|"extends"| node_domain_core
node_domain_core -->|"persists through"| node_db_layer
node_domain_core -->|"validates purchases"| node_iap
node_rank_scheduler -->|"maintains ranks &amp; tournaments"| node_domain_core
node_rank_scheduler -->|"uses"| node_db_layer

click node_main "https://github.com/heroiclabs/nakama/blob/master/main.go"
click node_flags "https://github.com/heroiclabs/nakama/blob/master/flags/flags.go"
click node_migration_command "https://github.com/heroiclabs/nakama/blob/master/migrate/migrate.go"
click node_deployment "https://github.com/heroiclabs/nakama/blob/master/build/Dockerfile"
click node_client_contract "https://github.com/heroiclabs/nakama/blob/master/apigrpc/apigrpc.proto"
click node_client_handlers "https://github.com/heroiclabs/nakama/blob/master/server/api.go"
click node_console_contract "https://github.com/heroiclabs/nakama/blob/master/console/console.proto"
click node_console_server "https://github.com/heroiclabs/nakama/blob/master/server/console.go"
click node_auth_sessions "https://github.com/heroiclabs/nakama/blob/master/server/api_authenticate.go"
click node_domain_core "https://github.com/heroiclabs/nakama/blob/master/server/core_account.go"
click node_rank_scheduler "https://github.com/heroiclabs/nakama/blob/master/server/leaderboard_scheduler.go"
click node_operations "https://github.com/heroiclabs/nakama/blob/master/server/metrics.go"
click node_websocket "https://github.com/heroiclabs/nakama/blob/master/server/socket_ws.go"
click node_socket_pipeline "https://github.com/heroiclabs/nakama/blob/master/server/pipeline.go"
click node_stream_routing "https://github.com/heroiclabs/nakama/blob/master/server/stream_manager.go"
click node_match_execution "https://github.com/heroiclabs/nakama/blob/master/server/matchmaker.go"
click node_runtime "https://github.com/heroiclabs/nakama/blob/master/server/runtime.go"
click node_language_runtimes "https://github.com/heroiclabs/nakama/blob/master/server/runtime_go.go"
click node_db_layer "https://github.com/heroiclabs/nakama/blob/master/server/db.go"
click node_sql_schema "https://github.com/heroiclabs/nakama/blob/master/migrate/sql/20180103142001_initial_schema.sql"
click node_iap "https://github.com/heroiclabs/nakama/blob/master/iap/iap.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_flags,node_migration_command,node_deployment toneBlue
class node_client_contract,node_client_handlers,node_console_contract,node_console_server toneAmber
class node_auth_sessions,node_domain_core,node_rank_scheduler,node_operations toneMint
class node_websocket,node_socket_pipeline,node_stream_routing,node_match_execution,node_runtime,node_language_runtimes toneRose
class node_database,node_db_layer,node_sql_schema,node_iap toneIndigo
```

## Components

### Startup & Delivery

- [Server binary](https://github.com/heroiclabs/nakama/blob/master/main.go): Go entry point · Starts migration or the distributed backend server. · `main.go`
- [Flags & config](https://github.com/heroiclabs/nakama/blob/master/flags/flags.go): startup configuration · `flags/flags.go`
- [Migration command](https://github.com/heroiclabs/nakama/blob/master/migrate/migrate.go): command path · `migrate/migrate.go`
- [Docker deployment](https://github.com/heroiclabs/nakama/blob/master/build/Dockerfile): container delivery · `build/Dockerfile`

### API Boundaries

- [Client API contract](https://github.com/heroiclabs/nakama/blob/master/apigrpc/apigrpc.proto): gRPC + HTTP gateway · Generated bindings expose client APIs over gRPC and HTTP/JSON. · `apigrpc/apigrpc.proto`
- [Client API handlers](https://github.com/heroiclabs/nakama/blob/master/server/api.go): endpoint handlers · `server/api.go`
- [Console API contract](https://github.com/heroiclabs/nakama/blob/master/console/console.proto): admin API schema · `console/console.proto`
- [Console server & UI](https://github.com/heroiclabs/nakama/blob/master/server/console.go): admin endpoints · Serves administrative APIs and embedded browser assets. · `server/console.go`

### Server Core

- [Auth & sessions](https://github.com/heroiclabs/nakama/blob/master/server/api_authenticate.go): identity boundary · Authenticates requests and coordinates JWT, session cache, registry, and WebSocket sessions. · `server/api_authenticate.go`
- [Domain operations](https://github.com/heroiclabs/nakama/blob/master/server/core_account.go): business logic · Reusable account, social, storage, wallet, notification, purchase, leaderboard, and tournament operations. · `server/core_account.go`
- [Leaderboard scheduler](https://github.com/heroiclabs/nakama/blob/master/server/leaderboard_scheduler.go): rank & schedule worker · `server/leaderboard_scheduler.go`
- [Metrics & shutdown](https://github.com/heroiclabs/nakama/blob/master/server/metrics.go): operations lifecycle · `server/metrics.go`

### Realtime & Runtime

- [WebSocket ingress](https://github.com/heroiclabs/nakama/blob/master/server/socket_ws.go): socket transport · `server/socket_ws.go`
- [Socket pipeline](https://github.com/heroiclabs/nakama/blob/master/server/pipeline.go): realtime dispatcher · Dispatches socket messages to match, RPC, and other domain stages. · `server/pipeline.go`
- [Streams & routing](https://github.com/heroiclabs/nakama/blob/master/server/stream_manager.go): realtime coordination · Tracks stream presence and routes realtime messages. · `server/stream_manager.go`
- [Matchmaking & matches](https://github.com/heroiclabs/nakama/blob/master/server/matchmaker.go): multiplayer execution · Separates matchmaking, match registry, and authoritative handlers. · `server/matchmaker.go`
- [Extension runtime](https://github.com/heroiclabs/nakama/blob/master/server/runtime.go): game logic boundary · Registers RPCs, hooks, match logic, and integrations. · `server/runtime.go`
- [Go, JS & Lua hosts](https://github.com/heroiclabs/nakama/blob/master/server/runtime_go.go): runtime implementations · `server/runtime_go.go`

### Persistence & Integrations

- **Postgres-compatible DB**: external database · CockroachDB or another Postgres-wire-compatible store.
- [Database layer](https://github.com/heroiclabs/nakama/blob/master/server/db.go): connection & errors · `server/db.go`
- [Versioned SQL schema](https://github.com/heroiclabs/nakama/blob/master/migrate/sql/20180103142001_initial_schema.sql): database migrations · `migrate/sql/20180103142001_initial_schema.sql`
- [Purchase validation](https://github.com/heroiclabs/nakama/blob/master/iap/iap.go): external integration · `iap/iap.go`

## Connections

- 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
