Architecture Overview #

Nakama is a monolithic stateful server that exposes real-time and non-real-time APIs from multiple subsystems. Nakama’s subsystems cover a variety of tasks, with the major subsystems discussed below.

Authorization #

Nakama’s authorization system handles user authentication, session state, and authorization. This system is responsible for securely linking users to relevant data. The system:

  • Establishes trusted client connections with signed JSON Web Tokens (JWTs)
  • Links users accounts to social sign-ins
  • Embeds custom data properties for edge caching

Cluster management #

Cluster management is a feature of Nakama Enterprise.

By relying on conflict-free replicated data types and gossip-based peer-to-peer connections, Nakama’s cluster management system provides built-in service discovery.

With this system, a Nakama cluster can gracefully respond to the loss of individual nodes or distributing load to new nodes brought online to handle surges in traffic. The system reacts to changes in the cluster’s topology and records changes in client connections to each node, to support flexible and efficient scaling.

Console and metrics #

Nakama’s built-in console and metrics system provides essential tools for DevOps professionals. The console provides a standalone interface to inspect a node’s status and data, while metrics exports data via Prometheus to your team’s preferred external monitoring and analytics tools.

Database #

Nakama’s database system manages long-term persistence. While Nakama’s in-memory system provides fast read and write access to a variety of data, Nakama’s database component is a methodical bookkeeper, ensuring that long-lived data is stored efficiently and reliably.

When it comes to persistence, Nakama is ready for many deployment scenarios, supporting any PostgreSQL wire-compatible database. In a canonical configuration, Nakama runs alongside CockroachDB for scalable, geographically distributed, and durable data storage.

External interfaces #

Nakama’s external interface system exposes socket and request interfaces. Games built with Nakama can use both interfaces, but may only need one or the other, depending on the game design and other details specific to your game’s experience.

The socket interface is the primary entry point for real-time activity such as chat and real-time multiplayer. The socket interface runs on WebSockets and rUDP, with a choice of binary (protocol buffers) or text (JSON) payloads.

The request interface, which runs on gRPC and HTTP, is the primary entry point for non-real-time activity, such as user account management.

In-memory data #

Nakama’s in-memory data system takes the place of an external in-memory data store, such as Redis. Under the hood, Nakama uses Bluge to unlock full-text search on arbitrary JSON fields, providing a range of lightning-fast searches.

The Nakama in-memory data system can be used for sophisticated and efficient matchmaking searches for matches with suitable labels (e.g. open-to-join) or players with common attributes (e.g. magic skill level X).

Management #

Nakama’s management system handles match lifecycle activities, scheduling for leaderboards and tournaments, matchmaking, and hosting server-authoritative multiplayer resources.

Most critically, this system manages the resources consumed by client activities and your game’s custom server-side logic.

Message routing #

Nakama’s message routing system makes sure that real-time client messages reach the correct nodes across the cluster, transparently. The message routing system tracks the whole cluster’s set of socket connections to clients and routes incoming messages to the right nodes, regardless of the cluster’s topology. The message routing system supports all of Nakama’s real-time features, such as chat and status.

Presence #

The presence tracking system builds on authorization to represent a player’s live activity in the game. The player’s presence is recorded uniquely as a combination of the user, the session, and the node to which they’re connected.

By way of presence, developers can help players set generic statuses (such as available or busy), free-form status messages to friends (e.g. “Looking for a party to join!”), or compose more complex interactions (e.g. inviting friends to spectate the player’s current match).

Streams #

Nakama uses the streams system to efficiently share data between clients. Streams are Nakama’s core representation of any real-time activity, such as chat, notifications, and matches.

If data needs to be distributed to clients live, streams are the way it gets there. Individual player sessions join and leave streams, like subscribing and unsubscribing to a continuous flow of messages.