MSTREAM

A Modern, Fast, and Ad-Free Cinema Streaming Experience

Explore Live Demo »
Key Features • Architecture • Getting Started • Deployment • Documentation

📽️ Overview

MSTREAM is an open-source, cinema-grade movie and TV show streaming web application powered by The Movie Database (TMDB) API and modern React 19. Designed with an ultra-clean OLED Cinema Dark aesthetic, MSTREAM delivers instantaneous catalog browsing, zero-lag page transitions, multi-provider playback options, and an account-free persistent library that stays in sync across your browser tabs.

Built specifically for high-speed delivery, it deploys seamlessly to Cloudflare Pages with an edge caching proxy and full Progressive Web App (PWA) offline precaching.

✨ Key Features

🎬 Cinema-Grade Interface: Immersive OLED dark theme (#07070a), glassmorphic overlays, fluid hover micro-interactions, and responsive layout perfected for both desktop monitors and mobile touchscreens.
💾 Account-Free Persistent Library:
- Save movies and TV shows to your personal library with one click.
- Zero registration or login required — persists automatically in localStorage.
- Live Cross-Tab Sync: Add a title in one tab, and all other open tabs reflect the change instantly via storage event synchronization.
- Dedicated /library view with instant search filtering, category tabs, and live navbar badges.
⚡ Multi-Tiered Performance Caching:
- Tier 1 (Memory): 0ms instantaneous lookup for catalog lists, genres, and page transitions.
- Tier 2 (sessionStorage): Keeps loaded content instant across browser refreshes.
- In-Flight Deduplication: Simultaneous components requesting the same TMDB endpoint share a single network Promise.
- Cloudflare Edge Cache: Edge proxy (functions/api/[[path]].js) caches upstream TMDB JSON responses with X-Cache-Status headers.
🛡️ Client Rate Limiting & Debounce:
- Built-in token-bucket algorithm (max 12 req/sec) with automatic exponential backoff on 429 responses.
- 280ms search query debouncing prevents unnecessary API spam while typing.
📺 Multi-Server Streaming Player:
- 7+ independent embed streaming servers with quick-switching failover.
- Interactive season and episode pickers for TV series.
- Clean cinema playback mode and sandbox security controls.
📱 Installable Progressive Web App (PWA):
- Installable on iOS, Android, macOS, and Windows.
- Workbox service worker precaching for static assets and offline shell loading.
🔍 Advanced Discovery & Filtering:
- Filter by release year, genre, certification, sort order, and keyword search.
- Dynamic segmented switch for "This Week" vs. "Today" trending items.

🏗️ System Architecture

flowchart TD
    subgraph Client["MSTREAM Client (Browser)"]
        UI["React 19 UI Components<br/>(Home, Catalog, Watch, Library)"]
        Context["LibraryContext & useTMDB"]
        MemoryCache[("Tier 1: Memory Cache<br/>(0ms In-Memory Map)")]
        SessionCache[("Tier 2: sessionStorage<br/>(TTL: 5m - 24h)")]
        LocalStore[("localStorage<br/>(Library & Session ID)")]
        RateLimiter["Token-Bucket Rate Limiter<br/>(12 req/s + Backoff)"]
    end

    subgraph Edge["Cloudflare Edge Network"]
        CFProxy["Cloudflare Pages Function<br/>(/api/[[path]])"]
        EdgeCache[("Tier 3: Cloudflare Cache API<br/>(1h Edge TTL)")]
    end

    subgraph Upstream["Upstream APIs & Streams"]
        TMDB["The Movie Database (TMDB) API"]
        Streams["Multi-Server Video Embeds"]
    end

    UI --> Context
    Context --> MemoryCache
    MemoryCache -- "Cache Miss" --> SessionCache
    SessionCache -- "Cache Miss" --> RateLimiter
    Context <--> LocalStore

    RateLimiter --> CFProxy
    CFProxy --> EdgeCache
    EdgeCache -- "Edge Miss" --> TMDB
    UI -. "Stream Selection" .-> Streams

🛠️ Technology Stack

Layer	Technologies
Frontend Framework	React 19, React DOM 19
Routing	React Router v7
Build Tool & Bundler	Vite 7
Package Manager	pnpm
Edge & Hosting	Cloudflare Pages, Wrangler
PWA & Offline	vite-plugin-pwa, Workbox
Styling & Design	Modern CSS3 Variables, Glassmorphism, Responsive Grid/Flexbox
Data Source	The Movie Database (TMDB) API v3

🚀 Getting Started

Prerequisites

Node.js (version 18.0.0 or higher)
pnpm (version 9.x or higher)
A free API Read Access Token from The Movie Database (TMDB)

1. Clone the Repository

git clone https://github.com/cd-Crypton/mstream.git
cd mstream

2. Install Dependencies

Always use pnpm for package installation:

pnpm install

3. Configure Environment Variables

Copy the sample environment file to .env:

cp .env.example .env

Open .env and fill in your TMDB Read Access Token:

# TMDB API Read Access Token (from https://www.themoviedb.org/settings/api)
VITE_TMDB_READ_ACCESS_TOKEN=your_tmdb_read_access_token_here

# TMDB Base URL and Image CDN Endpoints
VITE_TMDB_BASE_URL=https://api.themoviedb.org/3
VITE_BACKDROP_URL=https://image.tmdb.org/t/p/w500
VITE_POSTER_URL=https://image.tmdb.org/t/p/w1280

4. Start the Local Development Server

pnpm run dev

Open http://localhost:5173 in your browser to start exploring.

📜 Available Scripts

All scripts must be executed using pnpm:

Command	Description
`pnpm run dev`	Starts the Vite development server with Hot Module Replacement (HMR).
`pnpm run build`	Compiles production bundle to `/dist` and generates the PWA service worker.
`pnpm run preview`	Builds the project and starts a local Cloudflare Pages runtime with Wrangler.
`pnpm run deploy`	Builds and deploys the project directly to Cloudflare Pages via Wrangler.
`pnpm run lint`	Runs ESLint to verify code quality and style.
`pnpm run format:check`	Checks source code formatting with Prettier.
`pnpm run format:fix`	Automatically formats all JS, JSX, and CSS files with Prettier.

☁️ Deployment

Option 1: Cloudflare Pages (Git Integration — Recommended)

Push your code or fork this repository to GitHub/GitLab.
Log into the Cloudflare Dashboard and navigate to Workers & Pages > Create Application > Pages > Connect to Git.
Select the mstream repository.
Configure your build settings:
- Framework preset: None
- Build command: pnpm run build
- Build output directory: dist
- Root directory: / (or left blank)
Under Environment variables, add:
- VITE_TMDB_READ_ACCESS_TOKEN: (Your TMDB Read Access Token)
- VITE_TMDB_BASE_URL: https://api.themoviedb.org/3
- VITE_BACKDROP_URL: https://image.tmdb.org/t/p/w500
- VITE_POSTER_URL: https://image.tmdb.org/t/p/w1280
Click Save and Deploy. Cloudflare Pages will automatically execute the edge worker in functions/api/[[path]].js to proxy and cache TMDB requests.

Option 2: CLI Deployment with Wrangler

# Authenticate with Cloudflare
pnpm wrangler login

# Build and deploy
pnpm run deploy

📂 Project Structure

mstream/
├── .agents/                 # AI Assistant skills & agent toolkits
├── docs/                    # Architectural & in-depth technical documentation
│   └── ARCHITECTURE.md      # Tiered cache, rate limiting, and session design
├── functions/
│   └── api/
│       └── [[path]].js      # Cloudflare Pages edge proxy with Cache API
├── public/                  # Static assets, web manifest, and logos
├── src/
│   ├── assets/              # Branding images and icons
│   ├── components/          # Reusable UI components
│   │   ├── BannerSlider.jsx # Hero carousel with video backdrop
│   │   ├── Icons.jsx        # Lightweight inline SVG icon set
│   │   ├── Modal.jsx        # Item detail modal dialog
│   │   ├── MovieCard.jsx    # Poster card with bookmark & hover states
│   │   ├── MovieRow.jsx     # Horizontal/grid category row
│   │   ├── Navbar.jsx       # Responsive navigation with live Library counter
│   │   └── SearchModal.jsx  # Fullscreen search modal
│   ├── context/
│   │   └── LibraryContext.jsx # Reactive library state with cross-tab sync
│   ├── hooks/
│   │   └── useTMDB.js       # TMDB API hook with deduplication & caching
│   ├── pages/               # Main route views
│   │   ├── Home.jsx         # Trending hero, segmented window toggle
│   │   ├── Movies.jsx       # Filterable movies catalog
│   │   ├── TVShows.jsx      # Filterable TV shows catalog
│   │   ├── Popular.jsx      # Popular titles catalog
│   │   ├── Library.jsx      # Personal saved titles with instant filter
│   │   └── Watch.jsx        # Multi-server streaming player & episodes
│   ├── services/            # Core business logic & performance services
│   │   ├── apiCache.js      # Memory + sessionStorage multi-tier cache
│   │   ├── rateLimiter.js   # Token bucket limiter & exponential backoff
│   │   └── sessionManager.js# Anonymous device ID & preference manager
│   ├── styles/              # Global cinema styles & variables
│   │   ├── design-tokens.css# Colors, spacing, radii, blur tokens
│   │   ├── components.css   # Reusable component classes
│   │   └── pages.css        # Page layout styles
│   ├── App.jsx              # Main routing & provider composition
│   └── main.jsx             # React DOM entry point & PWA registration
├── index.html               # HTML entry with metadata & SEO tags
├── package.json             # Scripts & dependencies
├── vite.config.js           # Vite configuration with PWA plugin
└── wrangler.jsonc           # Cloudflare Pages configuration

📚 Additional Documentation

System Architecture & Caching Deep Dive: Comprehensive breakdown of the caching tiers, token-bucket rate limiter, cross-tab synchronization, and edge worker implementation.
Contributing Guide: Standards for PRs, conventional commits, and code formatting.

🤝 Contributing

Contributions are welcomed! Whether it is a bug fix, new server integration, or UI polish:

Fork the repository.
Create your feature branch (git checkout -b feat/amazing-feature).
Commit your changes using Conventional Commits (git commit -m 'feat: add amazing feature').
Ensure code adheres to standards:
```
pnpm run lint
pnpm run format:check
```
Push to your branch (git push origin feat/amazing-feature).
Open a Pull Request.

⚖️ License & Disclaimer

This project is licensed under the MIT License.

Disclaimer: MSTREAM does not host, store, or stream any media files directly on its servers. All streaming links and metadata are retrieved via third-party iframe embeds and public APIs (such as The Movie Database). MSTREAM operates solely as an open-source indexing client.

Navigation Menu

Repository files navigation

MSTREAM

📽️ Overview

✨ Key Features

🏗️ System Architecture

🛠️ Technology Stack

🚀 Getting Started

Prerequisites

1. Clone the Repository

2. Install Dependencies

3. Configure Environment Variables

4. Start the Local Development Server

📜 Available Scripts

☁️ Deployment

Option 1: Cloudflare Pages (Git Integration — Recommended)

Option 2: CLI Deployment with Wrangler

📂 Project Structure

📚 Additional Documentation

🤝 Contributing

⚖️ License & Disclaimer

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
docs		docs
functions/api		functions/api
public		public
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
index.html		index.html
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
vite.config.js		vite.config.js
wrangler.jsonc		wrangler.jsonc

Latest commit

History

Folders and files

Repository files navigation

MSTREAM

📽️ Overview

✨ Key Features

🏗️ System Architecture

🛠️ Technology Stack

🚀 Getting Started

Prerequisites

1. Clone the Repository

2. Install Dependencies

3. Configure Environment Variables

4. Start the Local Development Server

📜 Available Scripts

☁️ Deployment

Option 1: Cloudflare Pages (Git Integration — Recommended)

Option 2: CLI Deployment with Wrangler

📂 Project Structure

📚 Additional Documentation

🤝 Contributing

⚖️ License & Disclaimer

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages