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

# Architecture

> The request flows, security boundaries, and lifecycle behind MusterBox integrations.

This page describes the verified flows behind a MusterBox integration. It is
the map you should keep in mind while reading the SDK and engine pages.

## Session lifecycle

```mermaid theme={"dark"}
sequenceDiagram
    participant G as Game (browser/native)
    participant S as MusterBoxSdk
    participant B as MusterBox backend
    G->>S: initialize(config)
    G->>S: start()
    G->>S: authenticate({identifier, password} | token)
    S->>B: POST /api/v1/user/login
    B-->>S: accessToken, refreshToken, expiresIn, user
    S-->>G: PlayerContext
    G->>S: openSession({environment, matchId})
    S->>B: POST /api/v1/game-sdk/{gameId}/sessions
    B-->>S: sessionId, token, expiresAt, context
    S-->>G: context {tournamentId, matchId, participantId, slot}
    G->>S: submitResult(...) / submitEvent(...)
    S->>B: POST /api/v1/game-sdk/{gameId}/results (x-session-token)
    B-->>S: ResultDecision {decision, reason, ...}
```

## Mutual-claim result finalization

A match finalizes only when **both** participants independently claim the same
outcome. Each result submission consumes a single-use session token bound to
that user and match.

| Decision                            | Meaning                                                              |
| ----------------------------------- | -------------------------------------------------------------------- |
| `pending`                           | Awaiting the opponent's claim                                        |
| `replay`                            | Mutual `DRAW` in a single-elimination match; the match stays running |
| `game_advance`                      | Claims agree; bracket advanced                                       |
| `game_advance_pending_finalization` | Claims agree; bracket finalization deferred                          |
| `dispute`                           | Claims conflict, or the winner could not be mapped to a slot         |

## Security boundaries

```text theme={"dark"}
Trusted boundary ───────────────┐
                                │
 MusterBox backend ─────────────┤  identity owner
   - validates game keys        │  session owner
   - issues/revokes sessions    │  match authority
   - custody with MPC wallets   │
                                │
 Untrusted boundary ────────────┘
 Browser / device / game binary
   - never verifies tokens
   - never signs for wallets
   - never the sole authority on results
```

### The SDK never

* verifies token signatures (the backend is the identity owner),
* holds or signs wallet private keys (custody uses multi-party computation),
* invents endpoints (all paths live in SDK core and mirror the backend
  controllers),
* decides a match outcome (it only submits the player's claim).

## Event plane

Events are buffered and flushed in batches over the event plane. The SDK
subscribes to session, wallet, and status events and exposes them through a
polling API. See [Events & realtime](/sdk/events).

## Environment integrity

Before a purchase, the SDK runs on-device checks (root/jailbreak, debugger,
suspicious accessibility, screen capture, …). Any detected risk blocks the
purchase client-side and reports an `ENV_COMPROMISED` security event. The
computed level is one of `SAFE`, `WARN`, `COMPROMISED`. See
[Environment integrity & anti-tamper](/guides/environment-integrity-and-anti-tamper).