Architecture Document
How StreamVault Works
A zero-budget, open-source streaming platform built on Laravel, Livewire, and TMDB. This page explains the technical architecture for developers and contributors.
I
Overview
StreamVault is a monolithic Laravel application that proxies TMDB for metadata, stores user data in SQLite, and delegates video playback to an embedded client-side player that fetches streams from external sources. No media is stored or transcoded locally.
- Server-rendered UI via Livewire — no SPA complexity, no separate frontend deploy.
- TMDB as the source of truth for all metadata — no local movie/show tables needed.
- Aggressive caching — TMDB responses cached in SQLite via Laravel's cache.
- Source resolution is abstracted — providers are swappable via configuration.
II
Tech Stack
| Layer | Tool | Notes |
|---|---|---|
| Backend | Laravel 13 + PHP 8.4 | Routing, caching, auth, API proxy |
| Frontend | Livewire 4 + Flux UI 2 | Server-rendered reactive components |
| Styling | Tailwind CSS 4 | Utility-first, zero runtime cost |
| Database | SQLite | Users, favorites, watch history, cache |
| Metadata | TMDB API v3 | Free tier: 40 req/sec, unlimited daily |
| Auth | Laravel Fortify | Registration, login, 2FA |
| Caching | Laravel Cache (SQLite) | Configurable TTL per endpoint |
III
Data Flow
The TMDB service class (app/Services/Tmdb.php) wraps all API calls with automatic caching. Each endpoint has a configured cache TTL:
| Data | Cache TTL | Rationale |
|---|---|---|
| Trending / Popular | 6 hours | TMDB updates daily |
| Movie / TV details | 24 hours | Metadata rarely changes |
| Search results | 1 hour | New content appears quickly |
| Video sources | 1 hour | Stream URLs expire |
IV
Source Resolution
The source resolver (app/Services/SourceResolver.php) maps TMDB IDs to playable video URLs by querying configured providers in priority order. The provider interface is swappable — you can add or remove providers without touching the rest of the app.
Current provider chain:
- Embed provider — builds iframe URLs from a configurable base URL + TMDB ID
- Trailer fallback — extracts YouTube trailer keys from TMDB's video data
V
Database Schema
Only user-specific data is stored locally. Movie metadata lives in TMDB; we cache but never persist it.
favorites
id, user_id, tmdb_id, media_type, title, poster_path, timestamps
watch_histories
id, user_id, tmdb_id, media_type, title, poster_path,
progress_seconds, duration_seconds, season, episode, timestamps
VI
Contributing
StreamVault is open source. Contributions are welcome — whether it's adding new source providers, improving the UI, writing tests, or fixing bugs. Fork the repo, make your changes, and open a pull request.
StreamVault is an open-source project. Built with Laravel, Livewire, and TMDB.