# Architecture

> **TL;DR** — Your server syncs Wandura's catalog into your own database, applies your own paywall, and asks Wandura for a short-lived ticket each time a viewer starts an episode. The app plays that ticket with the licensed Player SDK. Wandura checks your licence on every ticket; you decide which viewer may watch what. Content with nothing to protect can use the lighter **open video** path instead.

## The pieces
```mermaid
flowchart LR
  subgraph You["Your systems"]
    App["Your app<br/>Player SDK"]
    BE["Your backend<br/>API keys, paywall"]
    DB["Your database<br/>catalog copy"]
  end
  subgraph W["Wandura"]
    API["Delivery API"]
    CDN["Streaming network"]
  end
  BE -->|"GET /catalog, every 15-60 min"| API
  BE --> DB
  App -->|"play request + device values"| BE
  BE -->|"POST /playback"| API
  API -->|"ticket"| BE
  BE -->|"ticket"| App
  App -->|"encrypted stream + keys"| CDN
```

| Piece | Runs | Talks to | Holds |
|---|---|---|---|
| Catalog sync job | Your backend, on a schedule | `GET /catalog` | A `metadata:read` key; writes your film tables |
| Ticket endpoint | Your backend, per play | `POST /playback` | A `playback` key; your paywall |
| App | Viewer's phone | Your backend only | One ticket per episode, in memory |
| Player SDK | Inside your app | Wandura's streaming network | Its licence file; the device key, which never leaves the device |
| Creatives sync (optional) | Your backend | `GET /creatives` | A `creatives:export` key |

One play, step by step:

```mermaid
sequenceDiagram
    participant Device as Viewer device (Player SDK)
    participant Backend as Your backend
    participant API as Wandura Delivery API
    participant Stream as Wandura streaming network
    Device->>Backend: Episode + device ID + device public key
    Backend->>Backend: Your paywall: may this viewer watch?
    Backend->>API: POST /api/delivery/v1/playback (Bearer key)
    API->>API: Check key scope and licence for this film
    API-->>Backend: vid, play_auth_token, expires_at, protection, subtitles
    Backend-->>Device: vid, play_auth_token, subtitles
    Device->>Stream: Player SDK loads the encrypted stream and keys
    Stream-->>Device: Video plays
```

The key that decrypts the video is bound to the viewer's device: it never passes through your backend or the API response.

## Who does what
| Area | Wandura | Your team |
|---|---|---|
| Films | Produces, encodes and protects every film; keeps titles, posters, order and subtitles up to date. | Shows them in your app, in the order and with the text you receive. |
| Rights | Grants your organisation a licence per film, with an optional window, and checks it on every ticket. | Follows any other limits of your contract (for example countries). |
| Viewers and money | Nothing: the API has no viewer identity. | Accounts, sign-in, paywall, free episodes, coins, subscriptions, refunds, viewer support. |
| Keys | Nothing to issue: your Admins and Developers create, rotate and revoke every key themselves, playback keys included. | Keeps keys on your servers; revokes a key that may have leaked, then tells Wandura. |
| Player | Registers your app IDs and issues the Player SDK licence (your organisation pays for it). | Integrates the Player SDK in each app. |
| Playback | Signs a ticket for one episode on one device and records it. | Asks for a ticket only for episodes the viewer may watch. |
| Usage | Counts views from `play` tickets. | Sends `"intent": "play"` when a viewer starts an episode and `"prefetch"` when preloading. |

## Choose a model
|  | **Standard** (licensed films) | **Open video** | **Own space** (*once your space is set up*) |
|---|---|---|---|
| For | Every partner app showing Wandura films | Content with no rights to protect, for example fitness clips | Partners Wandura sets up with a space of their own, for films and fitness |
| Film list | Your server polls `GET /catalog` | `GET /videos` | Read from your own space with your key; extra metadata from `GET /catalog` |
| Playback | A ticket per episode from `POST /playback` | Plain signed MP4 links, valid 1 hour | Links your server gets from your own space |
| Player | The Player SDK (licensed) | Any standard player | The Player SDK (licensed) for films; any standard player for fitness |
| Licence check | On every ticket | Per organisation and per app key | Only licensed content is copied into your space |
| Start with | [Integration roadmap](https://docs.wandura.ai/developers/integration-guide) | [Open video](https://docs.wandura.ai/developers/concepts/open-video) | [Your own video space](https://docs.wandura.ai/developers/concepts/own-space) |

If you are not sure, you are on the standard model.

## Related
- [Before you start](https://docs.wandura.ai/developers/before-you-start)
- [Security](https://docs.wandura.ai/developers/concepts/security): the trust boundary.
- [Canonical API behaviour](https://docs.wandura.ai/developers/reference/behaviour)