> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zerodash.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How your platform, Zero-Dash and the game client fit together — and who owns which part.

The integration has three actors and two API surfaces. Once you can name them, every page on this site falls into place.

## Actors

<Columns cols={3}>
  <Card title="Your platform" icon="building-columns">
    Owns the player, the wallet and the session token. Implements the **wallet callbacks**.
  </Card>

  <Card title="Zero-Dash" icon="server">
    Owns the games, the round outcomes and the transaction ledger. Serves the **Customer API**.
  </Card>

  <Card title="Game client" icon="gamepad">
    Runs in the player's browser. Talks only to Zero-Dash, never to you.
  </Card>
</Columns>

<Note>
  The game client never touches your systems. It authenticates through Zero-Dash, which relays to you over the signed server-to-server callbacks. Your wallet is never exposed to a browser.
</Note>

## The two API surfaces

|              | [Customer API](/api-reference/customer/introduction) | [Wallet Callbacks](/api-reference/callbacks/introduction) |
| ------------ | ---------------------------------------------------- | --------------------------------------------------------- |
| Direction    | You → Zero-Dash                                      | Zero-Dash → You                                           |
| Server       | Zero-Dash                                            | You                                                       |
| Auth headers | `X-Operator`, `X-Zd-Signature`, `X-Zd-Timestamp`     | `X-Zd-Signature`, `X-Zd-Timestamp`                        |
| Signed by    | You                                                  | Zero-Dash                                                 |
| Verified by  | Zero-Dash                                            | **You**                                                   |
| IP allowlist | Optional, yours                                      | Required, ours                                            |

Both use the **same** signature algorithm. Write it once, use it in both directions — one to sign, one to verify. See [Request signature](/security/signature).

## A game round, end to end

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant G as Game client
    participant Z as Zero-Dash
    participant O as Your wallet

    rect rgba(229,251,7,0.10)
    Note over G,O: Session opens — once per game launch
    G->>Z: Open session (launch token)
    Z->>O: GET /player?gameId&token
    O-->>Z: 200 accountId, displayName, balance
    end

    rect rgba(229,251,7,0.10)
    Note over G,O: Every round — repeated
    G->>Z: Place bet
    Z->>O: POST /debit  (transactionId, gameRoundId, stake)
    O-->>Z: 200 balance after debit
    Z-->>G: Bet accepted
    G->>Z: Round resolves
    alt Round settled normally
        Z->>O: POST /credit (referenceTransactionId, payout)
        Note right of O: payout is 0 on a loss —<br/>you still get the call
        O-->>Z: 200 balance after credit
    else Round could not be settled
        Z->>O: POST /rollback (referenceTransactionId, stake)
        O-->>Z: 200 stake returned
    end
    end
```

Three invariants hold for every round:

<CardGroup cols={3}>
  <Card title="One debit" icon="1">
    A round starts with exactly one `/debit`, identified by `transactionId`.
  </Card>

  <Card title="One settlement" icon="2">
    Followed by exactly one `/credit` **or** one `/rollback`. Never both, never neither.
  </Card>

  <Card title="One round ID" icon="3">
    Both carry the same `gameRoundId`. That is your join key for reporting and reconciliation.
  </Card>
</CardGroup>

## Session resumption

Zero-Dash persists game sessions. If a player loses connectivity mid-round, closes the tab, or switches device, reopening the game resumes the round exactly where it stopped.

The practical consequence for you: **a settlement can arrive much later than the bet**, sometimes days later after retries. Your `/credit` and `/rollback` handlers must not assume the player is still online. See [Errors and retries](/wallet/errors-and-retries).

## What you build

<Steps>
  <Step title="A signed HTTP client" icon="key">
    Calls the Customer API with the three auth headers.
  </Step>

  <Step title="Five HTTPS endpoints" icon="wallet">
    `/player`, `/debit`, `/credit`, `/rollback` and the transaction lookup. Signature-verified, IP-restricted, idempotent.
  </Step>

  <Step title="A launch handler" icon="gamepad">
    Turns a player clicking a game tile into a launch URL and a new tab.
  </Step>

  <Step title="A catalogue sync" icon="images">
    Caches [List games](/api-reference/customer/list-games) and renders the artwork.
  </Step>
</Steps>