Skip to content
BranchesTags

Repository files navigation

StreamFlix Platform

Multi-platform streaming platform with API server and web client. Ready for mobile, TV, and desktop expansion.

Version License

🎬 Overview

StreamFlix is a production-ready Netflix-like streaming platform aggregating 24,000+ movies and TV series from 5 streaming providers with rich TMDB metadata.

Key Features:

  • 🎥 24,489+ movies & TV series
  • 🔄 5 streaming providers with automatic failover
  • 📊 Rich metadata (40+ fields per item from TMDB)
  • ⚡ Redis caching & MongoDB storage
  • 🔐 Production-grade (clustering, rate limiting, health checks)
  • 🐳 Docker-ready with NGINX load balancing
  • 🎨 Modern Next.js 15 web client with React 19

🏗️ Architecture

streamflix-platform/
├── api/              # Node.js/Express API Server (port 8080)
│   ├── server.js     # Main entry point
│   ├── services/     # 10+ core services (MongoDB, Redis, TMDB, etc.)
│   ├── routes/       # RESTful API endpoints
│   └── controllers/  # Business logic
│
├── web/              # Next.js 15 Web Client (port 3000)
│   ├── src/app/      # App Router with React Server Components
│   ├── src/components/ # React components
│   └── .env.local    # Frontend configuration
│
└── docs/             # Complete documentation

Multi-Frontend Ready: This structure supports future platforms:

  • ✅ Web (current)
  • 📱 Mobile (React Native) - future
  • 📺 TV (Smart TV apps) - future
  • 💻 Desktop (Electron) - future

🚀 Quick Start

Prerequisites

  • Node.js 18+
  • MongoDB 7.0+
  • Redis 7+
  • TMDB API Key (Get one here)

Installation

  1. Clone the repository:

    git clone <your-repo-url>
cd Films

  2. Configure environment:

    cp .env.example .env
# Edit .env and add your TMDB_API_KEY

  3. Install dependencies:

    # Root dependencies
npm install

# API dependencies
cd api && npm install && cd ..

# Web dependencies
cd web && npm install && cd ..

  4. Initialize database:

    npm run api:init-db

  5. Start development:

    # Terminal 1 - API Server
npm run api:dev

# Terminal 2 - Web Client
npm run web:dev

  6. Access the platform:

📜 NPM Scripts

API Commands

npm run api:start      # Start API in production mode
npm run api:dev        # Start API with hot reload
npm run api:init-db    # Initialize MongoDB database

Web Commands

npm run web:dev        # Start web client in dev mode
npm run web:build      # Build web client for production
npm run web:start      # Start web client in production

Utility Commands

npm run health         # Check API health
npm run stats          # View platform statistics
npm run sync           # Trigger manual content sync

🐳 Docker Deployment

Quick Start with Docker

docker-compose up -d

This starts:

  • MongoDB (port 27017)
  • Redis (port 6379)
  • 3x API servers (ports 8080-8082)
  • NGINX load balancer (port 80)

Access Services

# Check all containers
docker-compose ps

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

📚 Documentation

Comprehensive documentation available in /docs:

🛠️ Tech Stack

API Server

  • Runtime: Node.js 18 (Alpine)
  • Framework: Express.js 4.18
  • Database: MongoDB 7.0 + Mongoose
  • Cache: Redis 7.0
  • External APIs: TMDB v3
  • Features: Clustering, rate limiting, health checks

Web Client

  • Framework: Next.js 15 (with Turbopack)
  • UI Library: React 19
  • Language: TypeScript 5
  • Styling: Tailwind CSS 4
  • State: React Context API
  • Rendering: SSR + CSR hybrid

Infrastructure

  • Containerization: Docker + Docker Compose
  • Load Balancer: NGINX
  • Process Manager: PM2-ready
  • Monitoring: Health checks + metrics

🔌 API Endpoints

Movies

GET  /api/movies              # All movies (paginated)
GET  /api/movies/trending     # Trending movies
GET  /api/movies/new          # Recently added (24h)
GET  /api/movies/:id          # Movie details
GET  /api/movies/:id/stream   # Streaming URLs
GET  /api/movies/search       # Search with filters

Series

GET  /api/series              # All series (paginated)
GET  /api/series/trending     # Trending series
GET  /api/series/:id          # Series details
GET  /api/series/:id/stream   # Streaming URLs

Platform

GET  /api/stats               # Platform statistics
GET  /api/health              # Health check
GET  /api/sync/status         # Sync status
POST /api/sync/trigger        # Manual sync

See docs/API.md for complete reference.

🎨 Web Features

  • 🏠 Homepage: Hero banner, trending content, genre carousels
  • 🔍 Search: Advanced filters (genre, year, rating)
  • 🎬 Watch Page: Embedded player, cast info, similar recommendations
  • 📋 Watchlist: Local storage-based favorites
  • 🌗 Dark Mode: System preference detection
  • 📱 Responsive: Mobile, tablet, desktop optimized
  • ⚡ Performance: Sub-second load times with caching

🔐 Environment Variables

API (.env)

# Database
MONGODB_URI=mongodb://localhost:27017/films_streaming
REDIS_URL=redis://localhost:6379

# External APIs
TMDB_API_KEY=your_tmdb_api_key_here

# Server
NODE_ENV=production
PORT=8080
CORS_ORIGIN=*

Web (web/.env.local)

NEXT_PUBLIC_API_URL=http://localhost:8080
NEXT_PUBLIC_APP_NAME=StreamFlix
NEXT_PUBLIC_APP_VERSION=2.0.0

📊 Platform Statistics

  • Total Content: 24,489+ items
  • Movies: ~18,000+
  • TV Series: ~6,000+
  • Streaming Providers: 5 (VidSrc, SuperEmbed, 2Embed, AutoEmbed, Smashy)
  • Metadata Quality: 70% average completeness
  • TMDB Integration: 40+ fields per item
  • Performance: Sub-second response times
  • Uptime: 99.9% with health monitoring

🤝 Contributing

This is currently a private project. For questions or suggestions, please contact the maintainer.

📄 License

MIT License - See LICENSE file for details

🔗 Links

📞 Support

For issues, bugs, or questions:

  1. Check docs/API_DEBUGGING_GUIDE.md
  2. Review docs/QUICK_START_GUIDE.md
  3. Contact the maintainer

Built with ❤️ for the streaming future

StreamFlix Platform v2.0.0 - Production Ready

About

streamflix-xhamza-x.vercel.app/

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages