Server Architecture

Required engineering server_architecture

Agent Prompt Snippet

Ensure the project has a server architecture document defining topology, scaling strategy, region deployment, and hosting infrastructure.

Purpose

A server architecture document is the single source of truth for how your game’s multiplayer backend is structured, deployed, and scaled. It describes whether the game uses dedicated servers, listen servers, or a hybrid model. It specifies how matchmaking routes players to server instances, how fleet orchestration platforms like Agones or Amazon GameLift allocate and reclaim capacity, and how autoscaling policies respond to demand across regions.

Without this document, backend engineers make topology decisions in isolation—one team provisions bare-metal in Frankfurt while another spins up spot instances in Virginia, each with incompatible session lifecycle assumptions. The matchmaking team targets server endpoints that don’t exist yet. The networking team tunes tick rates without knowing whether the server CPU budget can sustain them. QA discovers region-selection bugs in production because no document defined the selection algorithm.

The server architecture document prevents this divergence by forcing the team to commit answers to three questions early: What is the server model? How does capacity scale? How are players routed to the right instance in the right region? Every subsequent decision—networking protocol, session persistence, graceful shutdown behavior—flows from these answers.

This is a Required document for any multiplayer game with server-authoritative gameplay. A project that ships without it is a project where every infrastructure incident requires archaeology instead of a runbook lookup.

Who needs this document

Persona	Why they need it	How they use it
Backend Engineer	Needs to understand server lifecycle, process model, and deployment topology before writing game server code	References the document when implementing session allocation, heartbeat reporting, and graceful shutdown logic
Infrastructure / DevOps	Must provision, monitor, and scale the fleet; needs region strategy, instance types, and autoscaling thresholds	Uses the document to configure fleet orchestration (Agones, GameLift), write scaling policies, and set up regional deployments
Networking Engineer	Server tick rate and process model directly constrain netcode design; needs to align simulation rate with bandwidth budgets	Cross-references server architecture with the Networking Spec to ensure tick rate, send rate, and jitter buffer assumptions are consistent
Producer / Technical Director	Needs to understand infrastructure cost implications of server model choices and capacity commitments	Reviews the document during milestone planning to validate that server costs align with budget and player-count projections

What separates a good version from a bad one

Criterion 1: Server model choice is explicit and justified

✓ Strong: “We use dedicated servers running authoritative simulation at 60 Hz. Listen servers were rejected because our competitive ranked mode requires cheat-resistant authority and consistent tick rate regardless of host hardware. The dedicated model adds ~$0.12/match in compute cost, which is acceptable given our projected DAU.”

✗ Weak: “The game uses servers.” (Does not specify dedicated vs. listen, does not state tick rate, does not justify the choice. A new engineer cannot determine whether peer-to-peer fallback is expected or forbidden.)

Criterion 2: Fleet orchestration and scaling are defined with concrete thresholds

✓ Strong: “Fleet managed by Agones on GKE. Each GameServer pod runs one match instance (max 10 players). Autoscaler targets 20% buffer capacity per region. Scale-up trigger: buffer < 15% for 2 minutes. Scale-down trigger: buffer > 40% for 10 minutes. Minimum fleet size per region: 5 pods. Weekend peak pre-scaling: fleet doubles in US-East and EU-West at 17:00 local Friday.”

✗ Weak: “We autoscale based on demand.” (No thresholds, no buffer targets, no mention of pre-scaling for predictable peaks. The ops team cannot configure autoscaling from this description.)

Criterion 3: Region selection and matchmaking integration are specified

✓ Strong: “Players ping three candidate regions during the title screen. The matchmaking service receives the client’s region-latency map and assigns the match to the region that minimizes worst-case latency across all players in the lobby, with a hard cap of 120 ms. If no region satisfies the cap, the match is declined and players are re-queued.”

✗ Weak: “Players connect to the nearest server.” (Does not define how “nearest” is measured, does not specify the latency cap, does not describe fallback behavior. The matchmaking team and the client team will implement different interpretations.)

Criterion 4: Graceful shutdown preserves in-progress matches

✓ Strong: “On SIGTERM, the server stops accepting new match allocations, drains the current match to completion (up to 15-minute timeout), persists final match state to the session store, reports results to the ranking service, and then exits. During rolling deployments, the orchestrator marks old pods as unallocatable 10 minutes before termination.”

✗ Weak: “Servers shut down gracefully.” (Does not define the drain timeout, does not describe what happens to the active match, does not address state persistence. A rolling deployment will terminate live matches.)

Common mistakes

Choosing dedicated servers without costing them. Dedicated servers are the correct choice for competitive multiplayer, but they carry real per-match compute costs. A server architecture document that specifies dedicated servers without including a cost model per concurrent user is incomplete. When the finance team discovers the monthly bill, the architecture gets renegotiated under pressure, and the result is worse than if cost had been a first-class constraint.

Ignoring tick rate alignment with the networking spec. The server tick rate is not an independent variable—it directly determines the simulation step, the minimum update frequency the netcode can deliver, and the CPU budget per frame on the server. A server architecture document that specifies a 128-tick server while the networking spec assumes 60-tick updates creates a mismatch that surfaces as desyncs, excessive bandwidth, or wasted CPU. The two documents must be written together and cross-referenced.

Treating autoscaling as a solved problem. Game server scaling is not web server scaling. A web request takes milliseconds; a game match takes 10–30 minutes. You cannot terminate a server mid-match to scale down. Autoscaling policies must account for match duration, draining behavior, and buffer capacity. Documents that reference “standard autoscaling” without addressing these game-specific constraints will produce policies that either kill live matches or waste money keeping empty servers running.

No plan for regional failover. Specifying three deployment regions is not a failover plan. The document must describe what happens when an entire region becomes unavailable: Does matchmaking stop routing to it? Do in-progress matches migrate? Is there a manual intervention step? Without this, a regional outage becomes a total outage because no one knows the intended recovery path.

How to use this document

When to create it

Create the server architecture document during pre-production, after the game design has committed to a multiplayer model (competitive, cooperative, MMO) but before backend implementation begins. The server model choice affects networking, matchmaking, session management, and infrastructure cost—all of which are expensive to change after code is written. If you are evaluating dedicated vs. listen servers, this document is where that evaluation lives and where the decision is recorded.

Who owns it

The backend lead or server infrastructure engineer owns this document. They are responsible for keeping it current as fleet configuration, scaling policies, and region strategy evolve. The networking engineer is a required reviewer for any change that affects tick rate or session lifecycle. DevOps is a required reviewer for any change that affects fleet orchestration or deployment topology.

How AI agents should reference it

get_standard_docs(type="video_game", features=["multiplayer"])
→ server_architecture in documents[]
→ agent reads document to understand server model, fleet config, and scaling strategy
→ agent cross-references with networking_spec before modifying tick rate or session logic
→ agent flags changes that affect autoscaling thresholds or region topology

The prompt_snippet — “Ensure the project has a server architecture document defining topology, scaling strategy, region deployment, and hosting infrastructure” — tells the agent to verify all four areas are covered. If the agent is modifying game server code, it should confirm that changes are compatible with the documented server model and lifecycle.

How it connects to other documents

The server architecture document is upstream of most multiplayer infrastructure documents. The Networking Spec depends on it for tick rate, server authority model, and bandwidth budget per instance. The Session Management Spec depends on it for session lifecycle, state persistence, and how sessions map to server processes. The Scaling Runbook translates the autoscaling policies defined here into operational procedures. The Deployment Runbook implements the rolling update and graceful shutdown behavior specified here. Changes to the server architecture document should trigger a review of all four downstream documents.