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

# How it works

> End-to-end flow of the PlayWave platform

## System components

PlayWave consists of 4 components that communicate with each other.

<Columns cols={2}>
  <Card title="PlayWave Launcher" icon="desktop">
    Windows app installed at PC cafes. Authenticates the PC cafe IP via HMAC and launches games with an OTT token.
  </Card>

  <Card title="PlayWave Server" icon="server">
    Backend API that manages sessions, billing, and settlements. Communicates with the PC cafe auth server for IP verification and charge tracking.
  </Card>

  <Card title="Game Server" icon="gamepad">
    The Roblox game server with PlayWave integrated. Verifies OTT, sends heartbeats, and reports session end to the PlayWave Server via API Key auth.
  </Card>

  <Card title="PC Cafe Auth Server" icon="building">
    External infrastructure partner providing PC cafe IP verification and play-time billing APIs.
  </Card>
</Columns>

### How they connect

<Steps>
  <Step title="Launcher → PlayWave Server" icon="arrow-right">
    The launcher sends PC info with **HMAC signature** to the PlayWave Server for authentication and OTT issuance.
  </Step>

  <Step title="Launcher → Roblox" icon="arrow-right">
    The launcher starts the game with the **OTT embedded in LaunchData**, passing the session to the Roblox client.
  </Step>

  <Step title="Game Server → PlayWave Server" icon="arrow-right">
    The Game Server calls PlayWave Server API with **API Key auth** to verify OTT, send heartbeats, and end sessions.
  </Step>

  <Step title="PlayWave Server → PC Cafe Auth" icon="arrow-right">
    The PlayWave Server calls the external PC cafe auth API to **verify IP addresses** and **manage billing sessions**.
  </Step>
</Steps>

## Full flow

```mermaid theme={null}
sequenceDiagram
    participant L as 🖥️ PlayWave Launcher
    participant API as 🔷 PlayWave Server
    participant Roblox as 🎮 Roblox Client
    participant GS as 🖥️ Game Server

    Note over L, API: Phase 1 — Session start & PC cafe auth
    L->>API: POST /session/start (IP + HMAC auth)
    API->>API: Extract external IP → verify PC cafe
    API-->>L: session_token + game list

    Note over L, Roblox: Phase 2 — Game selection & OTT issue
    L->>API: POST /ott (select game)
    API-->>L: OTT (one-time token, 1 min TTL)
    L->>Roblox: Launch game (OTT in LaunchData)

    Note over Roblox, GS: Phase 3 — OTT verification & benefit grant
    Roblox->>GS: Join game (with LaunchData)
    GS->>API: POST /session/verify (OTT + user ID)
    API-->>GS: game_session_id + is_pc_cafe
    GS-->>Roblox: Apply PC cafe benefits

    Note over GS, API: Phase 4 — Heartbeat (every 2 min)
    loop Every 2 min
        GS->>API: PATCH /session/heartbeat (game_session_id)
        API-->>GS: OK + cumulative play time
    end

    Note over GS, API: Phase 5 — Session end
    alt Normal exit
        GS->>API: DELETE /session/end (game_session_id)
    else Abnormal exit
        Note over GS, API: Auto-terminate after 4 min without heartbeat
    end
```

## 5 phases in detail

### Phase 1 — Session start

When a PC cafe user launches the PlayWave launcher:

1. The launcher collects the PC's internal IP and hardware info
2. Sends a session start request to the PlayWave Server with HMAC signature
3. The PlayWave Server extracts the external IP from the HTTP request and verifies if it's a PC cafe
4. On success, returns a session token and a list of supported games

### Phase 2 — OTT issue & game launch

When the user selects a game:

1. The launcher requests an OTT (One-Time Token) from the PlayWave Server
2. The PlayWave Server generates a UUID-format OTT (1 min TTL, single-use)
3. The launcher launches the Roblox game with the OTT in LaunchData

### Phase 3 — OTT verification & billing start

When the user joins the game:

1. The Game Server extracts the OTT from LaunchData
2. Sends an OTT verification request to the PlayWave Server (API Key auth)
3. The PlayWave Server validates the OTT and starts billing
4. Returns the game session ID and PC cafe status

### Phase 4 — Heartbeat

During gameplay:

1. The Game Server sends heartbeats to the PlayWave Server every 2 minutes
2. The PlayWave Server renews the billing session and records play time
3. If no heartbeat is received for 4 minutes, the session is auto-terminated

### Phase 5 — Session end

When the user leaves the game:

1. The Game Server calls the PlayWave Server session end API
2. The PlayWave Server stops billing and records the final play time
3. On abnormal exit, heartbeat timeout handles automatic cleanup

## OTT (One-Time Token)

OTT is a single-use token that securely transfers the session from the PlayWave Launcher to the Game Server.

| Property | Value                                |
| -------- | ------------------------------------ |
| Format   | UUID v4                              |
| TTL      | 1 minute (60 seconds)                |
| Usage    | Single-use (consumed on verify call) |
| Delivery | Roblox LaunchData                    |

<Warning>
  OTT is single-use. It cannot be reused after the verify call, and expires if not used within 1 minute.
</Warning>