🎬 Flex-Watch — Enterprise Movie Discovery & Streaming Platform

A production-grade, distributed movie discovery and streaming web platform inspired by BookMyShow and Netflix. Features a high-performance React 19 frontend powered by Vite 6 and Vitest, an Express BFF (Backend-For-Frontend) with Prisma ORM persistence, two-tier caching (L1 In-Memory + L2 Redis) with singleflight request deduplication, interactive OpenAPI 3.0 / Swagger docs, Prometheus metrics, on-demand Python ML recommendations, and full Docker Compose containerization.

---

🏛️ System Architecture

                                [Web Browser / Client]
                                          │
                         (Clerk Auth Token / Guest Session)
                                          │
                                          ▼
                         [Nginx Reverse Proxy & Static Host]
                                          │
                                          ▼
                        [Flex-Watch API Server (Node.js)]
                 ┌────────────────────────┼────────────────────────┐
                 ▼                        ▼                        ▼
        [Security & Resilience]    [Persistence Layer]       [Catalog & ML Engine]
        - Helmet, CORS Protection  - Prisma ORM              - L1 In-Memory LRU Cache
        - Rate Limiting            - SQLite (Local Dev)      - L2 Distributed Redis
        - Structured Pino Logs     - PostgreSQL (Production) - Singleflight Collapsing
        - Trace IDs (x-request-id) - Watchlist & Bookings    - On-demand ML Serving
        - Prometheus /metrics      - Idempotency & Conflict  - Protected TMDB Secrets

---

✨ Production Highlights

Feature	Description
🛡️ Zero Secret Exposure	TMDB API keys and Clerk credentials live strictly on the backend service.
⚡ Two-Tier Resilient Caching	Local L1 LRU memory + distributed L2 Redis with singleflight promise collapsing eliminates upstream TMDB rate limit spikes and stampedes.
📖 Interactive Swagger UI	Complete OpenAPI 3.0 interactive documentation and live sandbox available at /api/docs.
📊 Prometheus Metrics	Production-ready /metrics endpoint tracking HTTP latency histograms, status code counts, and cache hit ratios.
🎟️ Cinema Seat Booking	BookMyShow-style curved screen seat selector with tiered pricing (VIP/Club/Standard), conflict guards (409), idempotent bookings, and digital printable ticket passes.
🔄 Database Persistence	Watchlists ("My List") and booking drafts are persisted via Prisma ORM (SQLite for zero-config dev, PostgreSQL for cloud production).
🤖 On-Demand ML Recommendations	ML cosine-similarity matches (~4,800 titles) are served dynamically via API rather than bloated into the client bundle.
🎥 Interactive Hero Carousel	Live background video trailers with audio toggle, poster fallback for low-speed connections, and YouTube API sync.
🔍 Real-Time Catalog & Search	Live search and multi-genre filtering across trending, popular, upcoming, and top-rated movies & TV series.
🐳 Full Containerization	Multi-stage Dockerfiles and docker-compose.yml orchestrating PostgreSQL, Redis, Backend API, and Nginx.
🚦 Automated CI Pipeline	GitHub Actions validating backend migrations, linting, and 100% frontend test suites on PR/push.
🚀 High-Throughput Benchmark	Automated autocannon concurrency test verifying 1,200+ req/sec throughput and singleflight collapsing.

---

📁 Clean Monorepo Directory Structure

Flex-Watch/
├── .github/
│   ├── workflows/ci.yml         # GitHub Actions CI (validates backend & frontend)
│   └── PULL_REQUEST_TEMPLATE.md # Standard PR checklist
├── frontend/                    # ⚛️ React 19 + Vite 6 Client Application
│   ├── src/                     # Components, pages, layouts, and services
│   ├── public/                  # Static assets (HTML, favicons, manifests)
│   ├── Dockerfile               # Multi-stage production Nginx container
│   ├── nginx.conf               # Nginx reverse proxy & gzip configuration
│   ├── package.json             # Frontend dependencies & scripts
│   └── tailwind.config.js       # Custom cinematic dark theme
├── backend/                     # 🚀 Node.js/Express BFF & API Server
│   ├── prisma/
│   │   └── schema.prisma        # Prisma DB schema (User, Watchlist, Booking)
│   ├── data/
│   │   └── recommendations.json # ML recommendation lookup table (~718 KB)
│   ├── src/
│   │   ├── config/env.js        # Zod environment schema & validation
│   │   ├── db/prisma.js         # Singleton Prisma client
│   │   ├── middlewares/         # Logger (Pino), Auth, ErrorHandler, RateLimiter
│   │   ├── routes/              # Health, Movies, Series, Search, Watchlist
│   │   ├── services/            # Cache (Singleflight), TMDB, Recommendations
│   │   └── server.js            # Express application bootstrap
│   ├── tests/
│   │   └── test_api.js          # Backend integration smoke tests
│   ├── Dockerfile               # Multi-stage backend container (non-root)
│   └── package.json             # Backend dependencies & scripts
├── ml-engine/                   # 🧠 Python Content-Based Recommendation Pipeline
│   ├── export_data.py           # Cosine similarity export script
│   ├── movies_dict.pkl          # Pickled movie dataset
│   └── similarity.pkl           # Pickled cosine similarity matrix
├── docs/                        # Architecture, setup, and feature guides
├── docker-compose.yml           # Production stack (Postgres + Redis + API + Web)
├── package.json                 # Root monorepo workspaces orchestrator
└── .gitignore                   # Multi-tier ignore rules (DBs, envs, logs)

---

🚀 Getting Started

Prerequisites

• Node.js: v18 or higher (v20+ recommended)
• npm: v9+
• Docker & Docker Compose (optional, for containerized run)

---

Method 1: Local Monorepo Development (One-Command Run)

1. Clone the repository:

   git clone https://github.com/your-username/Flex-Watch.git
   cd Flex-Watch

2. Setup Backend Environment:

   cd backend
   cp .env.example .env
   npm install
   npx prisma db push
   cd ..

3. Install Root Workspaces Dependencies:

   npm install

4. Run Full-Stack (Frontend + Backend Concurrently):

   npm run dev

   • Frontend: http://localhost:3000

   • Backend API: http://localhost:5000

   • Interactive API Docs (Swagger UI): http://localhost:5000/api/docs

   • Prometheus Metrics: http://localhost:5000/metrics

Or run individual services:

• npm run dev:frontend (React client only)
• npm run dev:backend (Express API only)
• npm run db:studio (Open Prisma visual database GUI)

---

Method 2: Docker Compose (Full Production Stack)

To run the complete production topology (PostgreSQL, Redis, Backend API, and Nginx reverse proxy):

docker compose up --build -d

• Frontend Web Application: http://localhost
• Interactive API Docs: http://localhost/api/docs
• Backend API Probes: http://localhost/health/ready
• PostgreSQL Database: Port 5432
• Redis Cache: Port 6379

---

🧪 Testing & Benchmarks

Run full monorepo test suite:

npm test

Run backend API smoke tests:

npm run test:backend

Run frontend unit & integration tests:

npm run test:frontend

Run high-concurrency performance benchmark:

npm run benchmark

---

📡 Core API Endpoints

Method	Endpoint	Description	Cache Policy
GET	/api/docs	Interactive OpenAPI 3.0 Swagger UI	Real-time
GET	/metrics	Prometheus observability metrics	Real-time
GET	/health/live	Liveness check probe	None
GET	/health/ready	Deep check (DB, Cache, TMDB)	Real-time
GET	/api/v1/movies/trending	Weekly/daily trending movies	30 mins
GET	/api/v1/movies/popular	Popular movies catalog	1 hour
GET	/api/v1/movies/top-rated	Top-rated movies catalog	2 hours
GET	/api/v1/movies/:id	Full movie details	24 hours
GET	/api/v1/movies/:id/recommendations	Dynamic ML recommendations	On-demand
GET	/api/v1/bookings/occupied	Reserved seats for showtime	Real-time
GET	/api/v1/bookings	Retrieve user bookings	Authenticated/Guest
POST	/api/v1/bookings	Idempotent seat reservation (conflict safe)	Atomic (409 guard)
DELETE	/api/v1/bookings/:id	Cancel cinema booking	Authenticated/Guest
GET	/api/v1/watchlist	Retrieve user watchlist	Authenticated/Guest
POST	/api/v1/watchlist	Add movie to persistent watchlist	Authenticated/Guest
DELETE	/api/v1/watchlist/:tmdbId	Remove item from watchlist	Authenticated/Guest

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to your branch (git push origin feature/amazing-feature)
5. Open a Pull Request (PR template will guide verification)

---

📄 License

This project is for educational and personal use.