# Architecture & System Design

<p class="page-description">Component boundaries, communication protocols, and media pipelines across the Vyla ecosystem.</p>

## System Layers

Vyla decouples presentation, streaming gateway mediation, and provider scraping into three distinct tiers:

- **Presentation Tier** (`Vyla Home`, `Vyla Go`, `Vyla TV`, custom web players): Handles the UI, player state, and media rendering using ExoPlayer Media3 or HLS.js. Connects via Server-Sent Events (SSE) and HTTP.
- **Gateway Tier** (`Stream API`): A Node.js cluster gateway. Manages in-memory LRU caching (1,500 entries, 5-minute TTL), rewrites HLS manifests and AES keys, and strips obfuscation headers.
- **Resolver Tier** (`@vyla-entertainment/sdk`): Directly queries 60+ scrapers with jitter delays, performs two-phase stream verification, and resolves subtitle tracks.
- **Upstream Hosts**: External CDNs and video hosts serving raw HLS manifests, video segments, and subtitle files.

---

## Component Details

### Vyla Home (Desktop)
- **Runtime**: Built with Tauri v2, Rust, and a local Node.js sidecar service.
- **IPC**: Communicates with the sidecar over standard I/O passing JSON-RPC messages.
- **Features**: System tray integration, automated delta updates, Discord Rich Presence, and local cache persistence.

### Vyla Go (Mobile)
- **Runtime**: Tauri v2 Mobile targeting Android ARM64 and x86_64 architectures.
- **Features**: Touch UI with WebGL shaders, background audio playback, and runtime asset patching.

### Vyla TV (Leanback)
- **Runtime**: Native Android app written in Kotlin with Jetpack Compose and ExoPlayer (Media3).
- **Features**: D-pad remote navigation, hardware-accelerated 4K/HDR decoding, audio track selection, and watch progress tracking.

### Stream API (Gateway)
- **Runtime**: Node.js microservice using the native `cluster` module.
- **Features**: Emits real-time playback events (`meta`, `source`, `done`) over SSE. Proxies HLS streams, rewrites encryption keys, strips 120-byte fake image masks, and caches verified sources for 5 minutes.

### Vyla SDK (`@vyla-entertainment/sdk`)
- **Runtime**: Pure ES Module Node.js package.
- **Features**: Contains 60+ modular scrapers in `src/sources/`, random jitter scheduling, retry backoff, two-phase validation (`verifyStream` / `verifyPlayable`), and Manga scraping with TLS client fingerprint spoofing.

---

## Playback Pipeline

1. **Client Handshake**: The player initiates an HTTP Server-Sent Events connection with a TMDB ID:
```http
GET /movie?id=155 HTTP/1.1
Host: api.vyla.cc
Accept: text/event-stream
```

2. **Metadata Delivery**: Stream API fetches TMDB details and subtitle tracks, emitting the first event immediately:
```json
data: {"type": "meta", "meta": {"title": "The Dark Knight", "year": 2008}, "subtitles": [{"lang": "English", "url": "..."}]}
```

3. **Concurrent Scraper Queries**: The SDK queries active scrapers concurrently with randomized jitter (0–500 ms) to prevent rate limits.

4. **Two-Phase Validation**:
   - `verifyStream`: Tests candidate URLs with HTTP `HEAD` or range requests. Any response with status >= 400 is discarded.
   - `verifyPlayable`: Validates the master HLS playlist and confirms video segment availability.

5. **Progressive Source Emission**: As each scraper verifies a working link, Stream API pushes a `source` event:
```json
data: {"type": "source", "source": "vidlink", "url": "https://api.vyla.cc/api?url=...", "quality": "1080p", "type": "hls"}
```

6. **Instant Playback**: The player starts playback on the very first source (typically within 3 to 8 seconds) and retains subsequent sources as automatic fallbacks.

7. **Stream Close**: When all scrapers finish or time out, Stream API emits the completion event:
```json
data: {"type": "done", "total": 4}
```

---

## Reverse Proxy & Mask Stripping

Many video hosts enforce strict CORS policies or mask video chunks behind fake image headers. Stream API handles this transparently:

### Playlist & Key Rewriting
When a stream is routed through `/api?url=<URL>`:
1. Stream API fetches the playlist using upstream `Referer` and `Origin` headers.
2. It rewrites `#EXT-X-KEY` AES encryption endpoints to route through the local proxy.
3. It rewrites `.ts` chunk paths so the player can fetch them with permissive CORS headers.

### Byte-Mask Stripping
Certain hosts prepend a 120-byte fake image header (`image/png` or `image/jpeg`) before the MPEG-TS sync byte (`0x47`). Stream API detects these headers and strips the prefix:
```javascript
const stripped = (full[0] === 0x89 || full[0] === 0xFF || full[0] === 0x00)
    ? full.subarray(120)
    : full;
```
The stripped payload is returned with `Content-Type: video/MP2T`.

---

## Common Deployments

- **Single Desktop**: Run Vyla Home locally on your PC. No external ports or public servers required.
- **Smart TV Setup**: Run Vyla TV on your Android TV device connected to a hosted Stream API gateway on your local network or VPS.
- **Private Home Server**: Run Stream API on a home NAS or VPS behind Nginx with TLS and API key authentication.
- **Custom Application**: Import `@vyla-entertainment/sdk` into your own Node.js backend.