documentation/start-here/architecture.md

Architecture & System Design

Deep architectural breakdown of the Vyla Ecosystem: component boundaries, communication protocols, video delivery pipelines, and failover topologies.

High-Level Architecture

The Vyla architecture cleanly separates presentation, gateway mediation, and content resolution. This decoupling ensures that any individual layer can be replaced, scaled, or run independently.

Architecture Tier	Components	Protocols & Interfaces	Core Responsibilities
Presentation Tier	Vyla Home, Vyla Go, Vyla TV, Third-Party Web Players	SSE (HTTP/1.1), REST (JSON), HLS / DASH	Render user interface, manage local state, execute video playback via HLS.js or ExoPlayer Media3.
Gateway Tier	Stream API (server.js)	Node.js Cluster IPC, HTTP/REST, SSE, Reverse Proxy	Expose public endpoints, manage 1,500-entry in-memory cache, rewrite M3U8 playlists & AES keys, strip 120-byte obfuscation masks.
Resolver Tier	Vyla SDK (@vyla-entertainment/sdk)	Direct ESM function calls, HTTP/HTTPS scrapers	Scrape 60+ upstream providers concurrently, enforce random jitter delays, run two-phase stream validation.
Upstream Hosts	Public Third-Party CDNs & Video Hosts	Encrypted TLS/HTTPS, M3U8, MP4	Deliver raw media segments and video assets.

---

Component Boundaries & Responsibilities

1. Vyla Home (Desktop)

• Runtime Environment: Built on Tauri v2 using Rust and an embedded Node.js sidecar service.
• IPC Protocol: Communicates with the sidecar process via standard input/output (stdin/stdout) passing JSON-RPC messages.
• Responsibilities:
  • Manages application lifecycle, window management, and native system tray.
  • Automatically checks, verifies cryptographic signatures (update-signing.pem), and extracts delta updates from GitLab releases.
  • Houses the local ServiceManager and Patcher for offline and local service fallback.
  • Dispatches Discord Rich Presence activity updates (discord-rpc.js).
  • Persists configuration and cache to platform-specific AppData locations.

2. Vyla Go (Mobile)

• Runtime Environment: Tauri v2 for Android (tauri-android) targeting ARM64 (aarch64) and x86_64 architectures.
• Responsibilities:
  • Touch-optimized interface utilizing WebGL hardware shaders and glassmorphism styling.
  • Automated resource management: fetches, unpacks, and hot-patches runtime assets directly from remote releases without requiring full APK reinstallations for minor script updates.
  • Background playback coordination and media notification integration.

3. Vyla TV (Leanback)

• Runtime Environment: Native Android application written in Kotlin utilizing Jetpack Compose and Google's ExoPlayer (Media3).
• Responsibilities:
  • Strictly optimized for D-pad remote controls, 10-foot viewing distances, and Android TV / Google TV operating systems.
  • Native HLS stream parsing, hardware-accelerated 4K/HDR decoding, playback speed manipulation, audio track selection, and subtitle overlay.
  • Local client storage for user favorites, watch progress resume, and TMDB catalog browsing.

4. Stream API (Gateway)

• Runtime Environment: Node.js microservice utilizing the native cluster module for multi-core process forking.
• Responsibilities:
  • Acts as an HTTP/SSE bridge for clients that cannot run the Node.js SDK directly (e.g. mobile apps, TV apps, browser frontends).
  • Emits real-time playback events (meta, source, done) over Server-Sent Events.
  • Proxies HLS media streams (/api?url=...), automatically rewriting playlist chunk URIs and AES encryption key endpoints to bypass browser CORS and network restrictions.
  • Strips obfuscation masks (e.g. 120-byte fake PNG/JPEG headers used by ByteDance/TikTok-based content delivery networks).
  • Caches verified results for 5 minutes (TTL = 300,000 ms) in a shared inter-process memory map.

5. Vyla SDK (@vyla-entertainment/sdk)

• Runtime Environment: Pure ES Module Node.js library.
• Responsibilities:
  • Houses the core provider scraping modules (60+ scrapers in src/sources/).
  • Implements jitter scheduling, retry backoff, and custom header injection (User-Agent, Referer, Origin).
  • Performs two-phase verification on resolved candidate URLs.
  • Houses the Manga resolver engine leveraging node-tls-client to bypass TLS fingerprint blocking on atsu.moe.

---

Playback Data Flow: Step-by-Step

Understanding how a media stream is discovered, verified, and played:

1. Client Establishes SSE Connection
   The viewer selects a title (e.g., TMDB ID 155), and the client initiates an HTTP Server-Sent Events handshake:

GET /movie?id=155 HTTP/1.1
Host: api.vyla.cc
Accept: text/event-stream

2. Stream API Emits Initial Metadata
   Stream API validates the identifier, queries TMDB for metadata and artwork, queries subtitle providers, and immediately delivers a meta event:

data: {"type": "meta", "meta": {"title": "The Dark Knight", "year": 2008}, "subtitles": [{"lang": "English", "url": "..."}]}

3. SDK Initiates Concurrent Provider Queries
   The SDK filters active provider scrapers from configuration, applies randomized per-source jitter (0–500 ms) to avoid burst-rate triggers, and initiates upstream HTTP scraping requests concurrently.

4. Two-Phase Stream Verification

   • Phase A (verifyStream): Executes an HTTP HEAD or range GET request against candidate stream URLs. Responses with status \ge 400 are discarded immediately.
   • Phase B (verifyPlayable): Downloads and parses the master HLS manifest (#EXT-X-STREAM-INF), validates chunk resolution, and tests segment availability.

5. Progressive Source Delivery
   As each provider scraper completes two-phase verification, Stream API immediately pushes a source event over the active SSE stream:

data: {"type": "source", "source": "vidlink", "url": "https://api.vyla.cc/api?url=...", "quality": "1080p", "type": "hls"}

6. Instant Client Playback
   The client media player (ExoPlayer, HLS.js, or AVPlayer) immediately begins playback upon receiving the first valid source event (typically within 3–8 seconds). Subsequent incoming sources are enqueued into a client-side fallback list.

7. Stream Completion
   Once all configured source scrapers have either returned verified streams or reached their timeout thresholds (typically 15–25 seconds), Stream API emits the completion event and closes the connection:

data: {"type": "done", "total": 4}

---

The HLS Proxy & De-Obfuscation Mechanics

Many upstream streaming hosts employ strict CORS restrictions, IP-bound tokens, or binary header obfuscation. Vyla resolves this transparently:

Playlist & Key Rewriting

When a stream URL is proxied through /api?url=<URL>&<param>=1, the gateway:

1. Requests the upstream playlist with provider-mandated Referer and Origin headers.
2. Intercepts #EXT-X-KEY:METHOD=AES-128,URI="..." and rewrites the key URI to route through the proxy.
3. Rewrites all chunk lines (.ts / .m4s) so that browser audio/video fetch calls pass through the proxy with valid Access-Control-Allow-Origin: * headers.

Byte-Mask Stripping

Certain modern providers mask .ts video chunks as fake image files (image/png, image/jpeg, letsgocdn, or TikTok CDN formats) by prepending a 120-byte image header before the MPEG-TS sync byte (0x47):

[ 120-byte Fake PNG Header (0x89 0x50 0x4E 0x47...) ] + [ MPEG-TS Payload (0x47...) ]

When Stream API detects these signatures via regular expressions (TIKTOK_REGEX, STRIP_REGEX), it slices off the first 120 bytes:

const stripped = (full[0] === 0x89 || full[0] === 0xFF || full[0] === 0x00)
    ? full.subarray(120)
    : full;

The resulting clean MPEG-TS stream is delivered to players with Content-Type: video/MP2T, enabling seamless playback across all platforms.

---

Deployment Topologies

Choose the deployment architecture that fits your infrastructure:

Topology	Components Used	Best For	Security & Networking
All-in-One Desktop	Vyla Home	Casual users wanting local playback on a single PC	Fully local, runs on localhost, zero open ports
Living Room TV	Vyla TV + Hosted Stream API	Smart TVs, Chromecast, NVIDIA Shield	TV connects over LAN/WAN to a secure Stream API gateway
Private Family Server	Stream API on VPS/NAS	Multi-device households streaming across phones, PCs, and TVs	Run behind Nginx/Caddy with TLS, enable API key protection
Custom Platform	SDK in Node.js backend	Developers building bespoke streaming web applications	Complete control over DB, auth, caching, and playback logic