Our Architecture

How Vyla Home, SDK, and Stream API relate, and where each responsibility belongs.

The Vyla stack

Vyla separates local application management, provider resolution, and client-facing delivery. That separation lets each layer be used on its own while keeping the integration points clear.

Vyla Home

Home is responsible for a desktop session: local configuration, encrypted local credentials, update coordination, managed processes, and the embedded interface. It is the right layer for launching and supervising a local experience.

Vyla SDK

The SDK contains the provider-facing work: source configuration, stream resolution, subtitle retrieval, download lookup, and health probes. It is the right layer when your Node.js application needs to decide how requests are authorized, cached, selected, and returned.

Stream API

Stream API wraps the SDK in a self-hosted HTTP service. Its movie and TV endpoints use Server-Sent Events so metadata can arrive first and usable sources can be delivered progressively. It also provides subtitle, download, health, test, and optional debug routes.

Common deployment patterns

Pattern	Best for	Key decision
Home only	a managed local desktop experience	Home owns the lifecycle of bundled local services
App + SDK	a Node.js backend with a custom product API	your app owns authentication, policy, and response design
Player + Stream API	browser or mobile clients that need a stable HTTP contract	deploy Stream API and place it behind TLS when exposed remotely
Home + Stream API	a local player backed by a local service	keep the service bound and access-controlled for the local environment

Data flow for playback

1. A client provides a TMDB media ID (plus season and episode for TV).
2. Stream API, or your own SDK-based backend, asks active providers for candidates.
3. Candidates are checked and successful sources are returned progressively.
4. The player begins with the first compatible candidate and keeps later candidates as fallbacks.
5. Subtitle and download lookups are separate operations; neither should block first playback.

Provider availability varies by source and network environment. Build the player experience around fallbacks and empty-result states, as described in Error handling.