# aryaniiil/vidlink-m3u8 architecture

> Architecture diagram of the GitHub repository aryaniiil/vidlink-m3u8, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aryaniiil/vidlink-m3u8
- Repository: https://github.com/aryaniiil/vidlink-m3u8

## Overview

This repo is a **single-service Node.js REST API** (Fastify) whose main job is to:
- Accept client requests for **movie/series streaming info** (by TMDB IDs)
- **Generate/compute an authentication token via WebAssembly (Go WASM runtime + `fu.wasm`)**
- Call **Vidlink upstream APIs** to obtain stream metadata / HLS master playlists
- Optionally call **TMDB** for `/search` enrichment (requires `TMDB_API_KEY`)
- Return a JSON payload containing the upstream API URL, required headers, and the extracted HLS playlist/stream URLs

- **Request flow** (client → Fastify routes → WASM token gen → upstream fetch → response)
- **External dependencies** (Vidlink, TMDB, streaming CDN hosts that serve `.m3u8`)

##### File structure → architectural components

Top-level:
- `server.js` → **Fastify HTTP server + route handlers** (`/movie`, `/series`, `/search`, `/health`)
- `fu.wasm` → **WASM binary module** that performs **token generation/auth logic**
- `wasm_exec.js` → **Go WASM runtime shim** that lets Node execute the Go-compiled WASM
- `.env` → runtime configuration (`PORT`, `TMDB_API_KEY`)
- `package.json` / `package-lock.json` → Node deps / build & run scripts
- `README.md` → behavior, endpoint contracts, constraints (headers required, token expiry)

Architecturally, this is best modeled as **one container (Node service)** with an **internal component boundary** around “Token Generation (WASM)”.

##### Actors / Clients
- **API Consumer** (curl, browser app, backend service, etc.)
- Calls your endpoints: `/movie/:movieId`, `/series/:tmdbId/:season/:episode`, `/search/:query`, `/health`

##### Primary runtime container
- **Node.js 18+ Process**
- **Fastify Server** listening on `PORT`
- Route handlers (logical sub-components):
- Movie Stream Controller/Handler
- Series Episode Stream Controller/Handler
- Search Controller/Handler (TMDB)
- Health Handler (reports `wasmInitialized`)

##### External services (must be drawn explicitly)
- **Vidlink** (e.g., `https://vidlink.pro/api/...`)
- Upstream API used to fetch streaming data; requires token
- **TMDB API** (search + metadata; requires `TMDB_API_KEY`)
- **Streaming/CDN hosts** (e.g., `storm.vodvidl.site`, `rainflare53.pro`, etc.)
- These ultimately serve HLS playlists/segments, and require special headers

##### Client → Fastify
- HTTP GET to `/movie/:id` or `/series/:tmdbId/:season/:episode`

##### Fastify Route Handler → WASM Token Generator
- Call into `wasm_exec.js` + `fu.wasm`
- Output: token (time-sensitive / expiring)

##### Fastify Route Handler → Vidlink API
- HTTP fetch to Vidlink endpoint using generated token
- Output: upstream response that includes/points to HLS resources

##### Fastify Route Handler → HLS Playlist Extraction
- Parse/extract “master playlist” and quality variants
- Output: playlist text + selected stream URL(s) + required headers

##### Fastify → Client
- JSON response: `api_url`, `headers`, `playlist`, `stream/sourceId`, etc.

##### Search flow
- **Client → `/search/:query` → Fastify → TMDB API → Fastify → Client**
- `TMDB_API_KEY` dependency from `.env`

##### Health flow
- **Client → `/health` → Fastify**

- `.env` → Node/Fastify process (configuration injection: `PORT`, `TMDB_API_KEY`)
- `package.json` → Node process (runtime dependencies)

##### Architectural patterns / principles to highlight
- **Single-service / modular monolith**: one Node runtime hosting all routes
- **Adapter boundary for WASM**: Go WASM runtime (`wasm_exec.js`) acting as an execution adapter around `fu.wasm`
- **Facade API** pattern: your server is a façade over Vidlink + TMDB, normalizing responses and providing required headers/playlist extraction
- **Time-sensitive auth**: token expiration drives the need to regenerate tokens per request or cache carefully

- **Rate limiting** (to respect upstream constraints)
- **Caching** (token caching and/or response caching keyed by TMDB ID + season/episode)
- **Reverse proxy** (Nginx/Cloudflare) in front of Fastify (optional deployment view)

##### “Don’t overthink it”: split into as many components as possible (but keep truthfulness)
- Fastify routing vs business logic handlers
- Token generation (WASM) vs HTTP fetching (Vidlink/TMDB)
- Playlist parsing/extraction vs response formatting
- Client consumption of streaming hosts (since headers/403 constraints are central to the system behavior)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% View 1 — System Context
  %% =========================
  subgraph "View 1 — System Context (C4 L1)"
    direction TB

    Client["API Consumer<br/>(curl / browser app / backend)"]:::actor

    Service["Movie/Series Stream REST API<br/>(Fastify on Node.js)"]:::service

    Vidlink["Vidlink Upstream API<br/>(vidlink.pro)"]:::external
    TMDB["TMDB API<br/>(api.themoviedb.org)"]:::external
    CDNs["Streaming/CDN Hosts<br/>(serve .m3u8 / segments)"]:::external

    Client -->|"GET /movie/:movieId"| Service
    Client -->|"GET /series/:tmdbId/:season/:episode"| Service
    Client -->|"GET /search/:query"| Service
    Client -->|"GET /health"| Service

    Service -->|"HTTP(fetch)+token"| Vidlink
    Service -->|"HTTP(fetch)+TMDB_API_KEY"| TMDB

    Service -->|"returns JSON: api_url+headers+playlist+stream_urls"| Client
    Client -->|"HLS access (.m3u8)+required headers"| CDNs

    Vidlink -->|"stream metadata / HLS pointers"| Service
    TMDB -->|"search results / metadata"| Service
  end

  %% =========================
  %% View 2 — Container
  %% =========================
  subgraph "View 2 — Container (C4 L2)"
    direction TB

    Env["Runtime Config<br/>(PORT, TMDB_API_KEY)"]:::config
    Pkg["Node Dependencies & Scripts"]:::config

    subgraph "Node.js 18+ Process (Single Service)"
      direction TB

      Fastify["Fastify Server<br/>(listen on PORT)"]:::service

      subgraph "In-Process WASM Token Generation Subsystem"
        direction TB
        GoShim["Go WASM Runtime Shim<br/>(wasm_exec.js)"]:::wasm
        FuWasm["Token/Auth WASM Binary<br/>(fu.wasm)"]:::wasm
        GoShim -->|"executes"| FuWasm
      end

      Env -.->|"injects config"| Fastify
      Pkg -.->|"declares runtime deps"| Fastify

      Fastify -->|"generate token"| GoShim
      Fastify -->|"HTTP(fetch)+token"| Vidlink
      Fastify -->|"HTTP(fetch)+TMDB_API_KEY"| TMDB
      Fastify -->|"produces URLs+headers for client HLS access"| CDNs
    end
  end

  %% =========================
  %% View 3 — Components (inside Node)
  %% =========================
  subgraph "View 3 — Components (C4 L3, inside Fastify App)"
    direction TB

    Router["Fastify Router / Routes"]:::service

    subgraph "Route Handlers / Controllers"
      direction TB
      MovieH["Movie Handler<br/>(/movie/:movieId)"]:::service
      SeriesH["Series Handler<br/>(/series/:tmdbId/:season/:episode)"]:::service
      SearchH["Search Handler<br/>(/search/:query)"]:::service
      HealthH["Health Handler<br/>(/health)"]:::service
    end

    TokenSvc["Token Service (WASM wrapper)"]:::wasm
    VidlinkClient["Vidlink Client (fetch wrapper)"]:::service
    TMDBClient["TMDB Client (fetch wrapper)"]:::service
    Parser["HLS Playlist Parser / Extractor"]:::service
    Formatter["Response Formatter<br/>(api_url, headers, playlist, stream/sourceId)"]:::service
    State["In-memory State<br/>(wasmInitialized)"]:::state

    Fastify -->|"routes"| Router
    Router -->|"dispatch"| MovieH
    Router -->|"dispatch"| SeriesH
    Router -->|"dispatch"| SearchH
    Router -->|"dispatch"| HealthH

    MovieH -->|"needs token"| TokenSvc
    SeriesH -->|"needs token"| TokenSvc
    TokenSvc -->|"calls"| GoShim

    MovieH -->|"fetch stream metadata"| VidlinkClient
    SeriesH -->|"fetch stream metadata"| VidlinkClient
    VidlinkClient -->|"HTTP(fetch)"| Vidlink

    SearchH -->|"fetch metadata"| TMDBClient
    TMDBClient -->|"HTTP(fetch)"| TMDB

    MovieH -->|"extract master+variants"| Parser
    SeriesH -->|"extract master+variants"| Parser

    Parser -->|"playlist text + stream URLs"| Formatter
    MovieH -->|"compose JSON"| Formatter
    SeriesH -->|"compose JSON"| Formatter
    SearchH -->|"compose JSON"| Formatter

    HealthH -->|"reads"| State
    TokenSvc -->|"sets init status"| State

    Formatter -->|"JSON response"| Client
  end

  %% =========================
  %% View 4 — Sequences
  %% =========================
  subgraph "View 4 — Sequences (Key Runtime Flows)"
    direction TB

    subgraph "Sequence A — GET /movie/:movieId"
      direction TB
      S1["Client"]:::actor
      S2["Fastify / Movie Handler"]:::service
      S3["Token Service (WASM)"]:::wasm
      S4["Vidlink API"]:::external
      S5["Playlist Parser / Extractor"]:::service
      S6["Client (uses returned headers)"]:::actor
      S7["Streaming/CDN Hosts"]:::external

      S1 -->|"GET /movie/:movieId"| S2
      S2 -->|"generate token"| S3
      S3 -->|"token (time-sensitive)"| S2
      S2 -->|"HTTP(fetch)+token"| S4
      S4 -->|"stream metadata / HLS pointers"| S2
      S2 -->|"parse playlist"| S5
      S5 -->|"HLS master playlist + variants"| S2
      S2 -->|"200 JSON: api_url+headers+playlist+stream_urls"| S1
      S6 -->|"GET .m3u8 / segments + referer/origin/user-agent"| S7
    end

    subgraph "Sequence B — GET /series/:tmdbId/:season/:episode"
      direction TB
      T1["Client"]:::actor
      T2["Fastify / Series Handler"]:::service
      T3["Token Service (WASM)"]:::wasm
      T4["Vidlink API"]:::external
      T5["Playlist Parser / Extractor"]:::service

      T1 -->|"GET /series/:tmdbId/:season/:episode"| T2
      T2 -->|"generate token"| T3
      T3 -->|"token (time-sensitive)"| T2
      T2 -->|"HTTP(fetch)+token"| T4
      T4 -->|"stream metadata / HLS pointers"| T2
      T2 -->|"parse playlist"| T5
      T5 -->|"HLS master playlist + variants"| T2
      T2 -->|"200 JSON: api_url+headers+playlist+stream_urls"| T1
    end

    subgraph "Sequence C — GET /search/:query"
      direction TB
      U1["Client"]:::actor
      U2["Fastify / Search Handler"]:::service
      U3["TMDB API"]:::external
      U4[".env (TMDB_API_KEY)"]:::config

      U1 -->|"GET /search/:query"| U2
      U2 -->|"uses TMDB_API_KEY"| U4
      U2 -->|"HTTP(fetch)"| U3
      U3 -->|"search results / metadata"| U2
      U2 -->|"200 JSON results"| U1
    end
  end

  %% =========================
  %% Click events (from mapping)
  %% =========================
  click Service "https://github.com/aryaniiil/vidlink-m3u8/blob/main/server.js"
  click Fastify "https://github.com/aryaniiil/vidlink-m3u8/blob/main/server.js"
  click Router "https://github.com/aryaniiil/vidlink-m3u8/blob/main/server.js"
  click MovieH "https://github.com/aryaniiil/vidlink-m3u8/blob/main/server.js"
  click SeriesH "https://github.com/aryaniiil/vidlink-m3u8/blob/main/server.js"
  click SearchH "https://github.com/aryaniiil/vidlink-m3u8/blob/main/server.js"
  click HealthH "https://github.com/aryaniiil/vidlink-m3u8/blob/main/server.js"

  click GoShim "https://github.com/aryaniiil/vidlink-m3u8/blob/main/wasm_exec.js"
  click FuWasm "https://github.com/aryaniiil/vidlink-m3u8/blob/main/fu.wasm"

  click Env "https://github.com/aryaniiil/vidlink-m3u8/blob/main/.env"
  click Pkg "https://github.com/aryaniiil/vidlink-m3u8/blob/main/package.json"

  click README "https://github.com/aryaniiil/vidlink-m3u8/blob/main/README.md"
  click Lock "https://github.com/aryaniiil/vidlink-m3u8/blob/main/package-lock.json"

  %% Hidden nodes to attach remaining click mappings without cluttering diagram text
  README["Docs (README)"]:::config
  Lock["Lockfile"]:::config

  %% =========================
  %% Styles
  %% =========================
  classDef actor fill:#ffffff,stroke:#0f172a,stroke-width:1px,color:#0f172a
  classDef service fill:#dbeafe,stroke:#1d4ed8,stroke-width:1px,color:#0b1b44
  classDef wasm fill:#ede9fe,stroke:#6d28d9,stroke-width:1px,color:#2e1065
  classDef external fill:#e5e7eb,stroke:#4b5563,stroke-width:1px,color:#111827
  classDef config fill:#fef3c7,stroke:#b45309,stroke-width:1px,color:#78350f
  classDef state fill:#dcfce7,stroke:#15803d,stroke-width:1px,color:#052e16
```
