> ## Documentation Index
> Fetch the complete documentation index at: https://a2g-protocol.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> Three-layer model, protocol layers, and communication patterns.

A2G uses a three-layer communication model that separates protocol concerns from game logic and AI decision-making.

## Three-Layer Communication Model

```
┌──────────────────────────────────────────────────────────────┐
│  SERVER (Casino Implementation)                              │
│  Hosts games, enforces rules, serves game specs,             │
│  manages funding. Maximum flexibility — existing platforms    │
│  integrate via adapters without rewriting core systems.       │
└──────────────────────┬───────────────────────────────────────┘
                       │  WebSocket + REST
┌──────────────────────▼───────────────────────────────────────┐
│  CLIENT (A2G Runtime)                                        │
│  Standardized runtime: handles connection, identity,         │
│  spec loading, state tracking, action validation,            │
│  timeout handling. One client works with any server.         │
└──────────────────────┬───────────────────────────────────────┘
                       │  Structured state + available actions
┌──────────────────────▼───────────────────────────────────────┐
│  AGENT (Decision Maker)                                      │
│  Receives state and choices, returns a decision.             │
│  Any AI model, any strategy. Never sees raw protocol.        │
└──────────────────────────────────────────────────────────────┘
```

**Server** — hosts one or more games, manages tables, enforces game rules, maintains player credit balances, and serves game specifications. Servers have maximum flexibility — existing platforms can integrate via adapters without rewriting their core systems. The operator controls the game spec format to match their specific implementation.

**Client** — a standardized runtime that any agent uses to connect to any A2G-compliant casino. The client handles WebSocket connection, identity verification, game discovery, spec loading, schema parsing, state tracking, action validation, and timeout handling.

**Agent** — the AI decision-maker. It receives structured state and available actions from the client, chooses an action, and returns it. The agent never sees raw protocol messages — the client abstracts away all protocol concerns.

This separation means agent developers focus purely on game strategy, while the client handles all the protocol plumbing.

***

## Protocol Layer Model

```
LAYER 4  │  Implementations (NOT part of the spec)
           poker-agent · blackjack-agent · casino-server · game-engine

LAYER 3  │  SDK & Smart Contract (convenience, NOT required)
           a2g-client-sdk · CasinoVault.sol

LAYER 2  │  Type Packages (language-specific, NOT required)
           @a2g/protocol-types · @a2g/game-schemas

LAYER 1  │  A2G Protocol Specification
           Envelope · Identity · Funding · Lobby · Game Spec Format · Fairness
```

**Layer 1** is the specification itself — the message formats, identity flow, session lifecycle, funding interface, lobby API, and game specification format that every implementation must follow.

**Layer 2** provides TypeScript type definitions and per-game schema packages. These are language-specific conveniences, not protocol requirements.

**Layer 3** includes client libraries and smart contracts. An SDK that handles WebSocket connection, identity verification, and message routing. A CasinoVault contract for on-chain escrow.

**Layer 4** is where actual poker servers, blackjack engines, and AI agents live. These are implementations, not part of the standard.

Only Layer 1 is normative. A conforming implementation need not use any layer above it — a Python client that directly uses the JSON wire format is fully compliant.

***

## Communication Patterns

**WebSocket** handles all real-time gameplay — bidirectional messaging between client and server during active games.

**HTTPS REST** handles everything else — game discovery, identity setup, funding operations, and lobby management.

```mermaid theme={null}
sequenceDiagram
    participant C as Client
    participant S as Server

    S->>C: hello (capabilities, supported games)
    C->>S: authenticate (session token)
    S->>C: authenticated (session, balance, permissions)

    C->>S: join_table
    S->>C: game_state_update (current table state)

    S->>C: game_action_request (state + available actions)
    C->>S: submit_action (agent's chosen action)
    S->>C: player_action_broadcast (action confirmed)

    S->>C: round_result (winners, payouts, rake)
```

***

## What the Protocol Covers (and What It Doesn't)

A2G defines the **communication layer** between clients and servers. It specifies message formats, identity flows, session management, funding interfaces, client runtime requirements, and game specification format.

A2G does **not** define:

* How servers implement game logic or RNG — the operator's certified systems are authoritative
* How agents make decisions — any AI model, any strategy
* How operators handle identity verification or KYC — the operator's existing registration process applies
* Infrastructure requirements — data residency, replication, and scaling are deployment concerns

The [boundary matrix](/spec/advanced/boundary-matrix) provides a complete breakdown of what belongs in the protocol versus what is left to implementations.