# Vyla Ecosystem Architecture

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

## System Topology

| Ecosystem Layer | Core Technologies | Primary Responsibilities |
| :--- | :--- | :--- |
| **Client Interfaces** | Vyla Home (Tauri v2), Vyla Go (Mobile), Vyla TV (ExoPlayer), Web Players | Render UI, manage local user state, initiate playback via SSE, 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, 120-byte fake image mask stripping. |
| **Vyla SDK Resolver** | `@vyla-entertainment/sdk` (ESM) | 60+ provider scrapers, randomized jitter scheduling, two-phase stream validation, manga scraping with Chrome 131 TLS fingerprinting. |
| **Upstream Hosts** | Third-party CDNs & Video Hosts | Remote video segment delivery, HLS manifest endpoints, subtitle hosts. |

## Projects Overview

| Directory / Package | Language / Framework | Purpose |
| :--- | :--- | :--- |
| `Documentation` | HTML5, Vanilla JS, CSS3 | Official developer documentation platform hosted at [vyla.cc](https://vyla.cc). |
| `Stream API` | Node.js (Cluster, HTTP, SSE) | Self-hosted streaming microservice gateway with caching and reverse proxying. |
| `SDK` | Node.js (ESM), TLS Client | Core multi-provider scraping library (`@vyla-entertainment/sdk`). |
| `Home` | Tauri v2, Rust, Node.js Sidecar | Native desktop application for Windows, macOS, and Linux. |
| `TV` | Kotlin, Jetpack Compose, ExoPlayer | Native 10-foot Leanback streaming application for Android TV and Fire TV. |
| `Go` | Tauri v2 Mobile, WebGL Shaders | Native mobile client for Android devices. |

## Core Architectural 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.