Cinevora - AI-Powered Movie & TV Streaming Platform

A modern, full-stack streaming platform built with Next.js, Firebase, and TMDB API, featuring deterministic AI-powered recommendations.

🎯 Features

• Authentication:
  • Google Sign-In (OAuth)
  • Passwordless Email Authentication (Magic Link)
• Movie & TV Browsing: Browse trending, popular, and search content from TMDB
• Personalized Recommendations: Deterministic AI recommendations using:
  • Content-based filtering (genre similarity)
  • Collaborative filtering (user similarity)
  • Behavioral ranking (recency, completion rate, engagement)
• Watchlist: Save movies and TV shows for later
• Watch History: Track viewing progress and continue watching
• Real-time Updates: Firebase Firestore for real-time data sync
• Responsive Design: Beautiful UI that works on all devices
• Mobile-Ready APIs: RESTful APIs ready for React Native consumption

🛠️ Tech Stack

• Frontend: Next.js 15 (App Router), React 19, Tailwind CSS
• Backend: Next.js API Routes, Server Actions
• Database: Firebase Firestore
• Authentication: Firebase Authentication
• External API: TMDB API v3
• Language: TypeScript
• Styling: Tailwind CSS with custom dark theme

📋 Prerequisites

• Node.js 18+ and npm
• Firebase project with Firestore and Authentication enabled
• TMDB API key (free tier available at https://www.themoviedb.org/settings/api)

🚀 Getting Started

1. Clone the repository

git clone <repository-url>
cd Movie-Streaming

2. Install dependencies

npm install

3. Configure environment variables

Create a .env.local file in the root directory:

# TMDB API Configuration
NEXT_PUBLIC_TMDB_API_KEY=your_tmdb_api_key_here
TMDB_API_KEY=your_tmdb_api_key_here

# Firebase Client Configuration
NEXT_PUBLIC_FIREBASE_API_KEY=your_firebase_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your-project-id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id

# Firebase Admin SDK (Server-side only)
FIREBASE_ADMIN_PROJECT_ID=your-project-id
FIREBASE_ADMIN_CLIENT_EMAIL=firebase-adminsdk@your-project.iam.gserviceaccount.com
FIREBASE_ADMIN_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYour private key here\n-----END PRIVATE KEY-----\n"

4. Set up Firebase

1. Create a Firebase project at https://console.firebase.google.com
2. Enable Authentication with the following providers:
   • Google (OAuth)
   • Email/Password (for email link authentication)
3. Create a Firestore database
4. Download your service account key for Admin SDK
5. Copy the configuration values to .env.local

5. Deploy Firestore security rules

Create firestore.rules in your Firebase project:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // Users collection
    match /users/{userId} {
      allow read, write: if request.auth != null && request.auth.uid == userId;
    }

    // Watchlists
    match /watchlists/{userId}/items/{itemId} {
      allow read, write: if request.auth != null && request.auth.uid == userId;
    }

    // Watch History
    match /watchHistory/{userId}/items/{itemId} {
      allow read, write: if request.auth != null && request.auth.uid == userId;
    }

    // Recommendations
    match /recommendations/{userId} {
      allow read, write: if request.auth != null && request.auth.uid == userId;
    }
  }
}

6. Run the development server

npm run dev

Open http://localhost:3000 in your browser.

📁 Project Structure

Movie-Streaming/
├── app/                      # Next.js App Router pages
│   ├── api/                  # API routes
│   │   ├── user/            # User profile endpoints
│   │   ├── watchlist/       # Watchlist endpoints
│   │   ├── history/         # Watch history endpoints
│   │   └── recommendations/ # Recommendation endpoints
│   ├── movie/[id]/          # Movie detail page
│   ├── tv/[id]/             # TV show detail page
│   ├── login/               # Login page
│   ├── signup/              # Signup page
│   ├── profile/             # User profile page
│   ├── watchlist/           # Watchlist page
│   ├── history/             # Watch history page
│   ├── search/              # Search page
│   ├── layout.tsx           # Root layout
│   ├── page.tsx             # Home page
│   └── globals.css          # Global styles
├── components/              # Reusable React components
│   ├── Navbar.tsx
│   ├── Footer.tsx
│   ├── MovieCard.tsx
│   ├── Carousel.tsx
│   ├── WatchlistButton.tsx
│   └── Loading.tsx
├── lib/                     # Core library code
│   ├── api/                 # API utilities
│   │   └── middleware.ts    # Auth middleware
│   ├── context/             # React contexts
│   │   └── AuthContext.tsx
│   ├── firebase/            # Firebase configuration
│   │   ├── config.ts        # Client SDK
│   │   └── admin.ts         # Admin SDK
│   ├── services/            # Business logic services
│   │   ├── tmdb.ts          # TMDB API service
│   │   ├── watchlist.ts     # Watchlist service
│   │   ├── history.ts       # Watch history service
│   │   └── recommendation.ts # Recommendation engine
│   └── utils/               # Utility functions
│       └── similarity.ts    # Similarity algorithms
├── types/                   # TypeScript type definitions
│   └── index.ts
├── public/                  # Static assets
├── .env.example             # Environment variables template
├── .env.local               # Your environment variables (gitignored)
├── next.config.js           # Next.js configuration
├── tailwind.config.ts       # Tailwind CSS configuration
├── tsconfig.json            # TypeScript configuration
└── package.json             # Dependencies and scripts

🎨 Key Features Explained

Recommendation Engine

The recommendation system uses a hybrid approach combining multiple algorithms:

1. Content-Based Filtering: Analyzes genre similarity between watched content and potential recommendations
2. Collaborative Filtering: Finds users with similar watch patterns (using Jaccard similarity)
3. Behavioral Ranking: Considers recency, completion rate, and re-watch count
4. Cold-Start Handling: New users get trending and popular content until enough data is collected

All algorithms are deterministic and explainable - no black-box ML models.

Real-Time Features

• Watchlist updates instantly across devices using Firestore real-time listeners
• Watch progress syncs automatically
• Recommendations are cached for 24 hours and refreshed on-demand

API Design

All API routes follow RESTful conventions and return consistent JSON responses:

{
  "success": true,
  "data": { ... }
}

Or on error:

{
  "success": false,
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE"
  }
}

🔒 Security

• Firebase Authentication handles user sessions
• Server-side token verification on all protected routes
• Firestore security rules enforce user-specific data access
• API keys are never exposed to the client
• CORS configured for mobile app support

📱 Mobile App Integration

The API is designed to be consumed by a React Native mobile app:

1. All endpoints use standard HTTP methods (GET, POST, PUT, DELETE)
2. Authentication uses Firebase tokens in Authorization header
3. Consistent response format across all endpoints
4. TypeScript types can be shared between web and mobile

🚀 Deployment

Vercel (Recommended)

1. Push your code to GitHub
2. Import project in Vercel
3. Add environment variables in Vercel dashboard
4. Deploy!

Other Platforms

The app can be deployed to any platform that supports Next.js:

• AWS Amplify
• Netlify
• Railway
• Self-hosted with Docker

📝 Environment Variables

Variable	Description	Required
NEXT_PUBLIC_TMDB_API_KEY	TMDB API key (client-side)	Yes
TMDB_API_KEY	TMDB API key (server-side)	Yes
NEXT_PUBLIC_FIREBASE_API_KEY	Firebase API key	Yes
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN	Firebase auth domain	Yes
NEXT_PUBLIC_FIREBASE_PROJECT_ID	Firebase project ID	Yes
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET	Firebase storage bucket	Yes
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID	Firebase messaging sender ID	Yes
NEXT_PUBLIC_FIREBASE_APP_ID	Firebase app ID	Yes
FIREBASE_ADMIN_PROJECT_ID	Firebase admin project ID	Yes
FIREBASE_ADMIN_CLIENT_EMAIL	Firebase admin client email	Yes
FIREBASE_ADMIN_PRIVATE_KEY	Firebase admin private key	Yes

🤝 Contributing

This is a production-ready codebase. Contributions are welcome!

📄 License

MIT License - feel free to use this project for learning or commercial purposes.

🙏 Acknowledgments

• Movie and TV data provided by TMDB
• Built with Next.js
• Powered by Firebase
• Styled with Tailwind CSS

📧 Support

For issues or questions, please open an issue on GitHub.

---

Note: This platform is for demonstration purposes. Actual video streaming functionality is not implemented - only metadata, recommendations, and playback state tracking.