# Vyla Ecosystem Architecture

High-level architecture, module boundaries, communication protocols, and design principles of the Vyla Ecosystem.

## System Topology

- **Client Interfaces**: Vyla Home (Tauri v2), Vyla Go (Mobile), Vyla TV (ExoPlayer), Web Players. Render UI, manage local state, initiate playback via SSE, and handle failover queues.
- **Stream API Gateway**: Node.js Cluster, SSE, HTTP Proxy. Multi-core IPC caching (1,500 entries, 5-min TTL), HLS/AES key rewriting, and 120-byte fake image mask stripping.
- **Vyla SDK Resolver**: `@vyla-entertainment/sdk` (ESM). 60+ provider scrapers, randomized jitter scheduling, two-phase stream validation, and manga scraping with Chrome 131 TLS fingerprinting.
- **Upstream Hosts**: Remote video segment delivery, HLS manifest endpoints, and subtitle hosts.

---

## Projects Overview

- **Documentation**: Developer documentation platform hosted at [vyla.cc](https://vyla.cc).
- **Stream API**: Self-hosted streaming microservice gateway with caching and reverse proxying.
- **SDK**: Core multi-provider scraping library (`@vyla-entertainment/sdk`).
- **Home**: Native desktop application for Windows, macOS, and Linux (Tauri v2 + Rust + Node.js sidecar).
- **TV**: Native 10-foot Leanback streaming application for Android TV and Fire TV (Kotlin + Jetpack Compose + ExoPlayer).
- **Go**: Native mobile client for Android devices (Tauri v2 Mobile).

---

## Core Invariants

1. **Decoupled Resolution**: Client interfaces never scrape providers directly; they interact through `@vyla-entertainment/sdk` or the Stream API gateway.
2. **Progressive Playback**: Streaming links are emitted incrementally over Server-Sent Events (SSE). Players start playback on the first candidate (3-8s) and queue subsequent sources as fallbacks.
3. **Transparent Proxying**: All upstream HLS playlists are rewritten to route segments and AES encryption keys through the local gateway, bypassing browser CORS restrictions and stripping 120-byte image obfuscation masks.
4. **Resilience by Default**: Provider queries are scheduled with randomized jitter and timeout budgets to prevent burst rate limits.