🎬 Enterprise Cinema Booking Platform

A scalable, multi-tenant cinema management platform built with the MERN Stack

Features • Tech Stack • Installation • Usage • API • Contributors

📸 Screenshots

🖼️ View More Screenshots

Page	Screenshot
Home
Movie Listing
Movie Details
Seat Selection
Payment
Booking Confirmation
User Profile
Admin Dashboard
Cinema-Admin Dashboard

✨ Features

🎟️ Booking System Real-time seat reservation with WebSocket updates Interactive seat map with live availability 15-minute booking timer with auto-expiration QR code tickets with PDF download Booking history with status tracking	🔐 Authentication & Security JWT-based authentication with refresh tokens Role-based access control (User, Cinema Admin, Platform Admin) Email verification via OTP Secure password hashing with bcrypt Rate limiting & CORS protection
💳 Payment Integration PayPal Checkout integration Sandbox & Production modes Automatic refund on cancellation Payment history & receipts Secure transaction handling	🎬 Cinema Management Multi-cinema support (B2B platform) Movie & showtime management Dynamic pricing by showtime Seating layout customization Cinema admin applications
📊 Admin Dashboards Platform Admin: User, cinema, movie management Cinema Admin: Showtimes, bookings, analytics Approval workflows for new cinemas Revenue tracking & reports	⭐ Reviews & Ratings Movie & cinema reviews Star ratings with averages Verified booking badge Review moderation

🛠️ Tech Stack

Frontend	Backend	Database	DevOps
React 18	Node.js	MongoDB	Docker
TypeScript	Express.js	Mongoose	CI/CD
Tailwind CSS	Socket.io	Redis (Cache)	Jest

Additional Technologies

Category	Technologies
State Management	React Query (TanStack Query)
Form Handling	React Hook Form
HTTP Client	Axios
Authentication	JWT, bcryptjs
Validation	Joi
Payment	PayPal Checkout SDK
File Generation	jsPDF, html2canvas, QRCode
Testing	Jest, Supertest, React Testing Library

🏗️ Architecture

graph TB
    subgraph Client["🖥️ Frontend (React)"]
        UI[UI Components]
        RQ[React Query]
        WS[WebSocket Client]
    end

    subgraph Server["⚙️ Backend (Express)"]
        API[REST API]
        Auth[Auth Middleware]
        WSS[WebSocket Server]
    end

    subgraph Data["💾 Data Layer"]
        MongoDB[(MongoDB)]
        Cache[(Redis Cache)]
    end

    subgraph External["🌐 External Services"]
        PayPal[PayPal API]
        Email[SendGrid]
    end

    UI --> RQ --> API
    WS <--> WSS
    API --> Auth --> MongoDB
    API --> Cache
    API --> PayPal
    API --> Email

🚀 Installation

Prerequisites

Node.js >= 18.x
MongoDB >= 6.0 (or Docker)
npm >= 9.x

Quick Start with Docker (Recommended)

# Clone the repository
git clone https://github.com/deaneeth/enterprise-cinema-booking-platform.git
cd enterprise-cinema-booking-platform

# Start all services
docker compose up -d

# Access the application
# Frontend: http://localhost:3000
# Backend API: http://localhost:5000
# MongoDB: localhost:27017

Manual Installation

📋 Step-by-step instructions

1. Clone the repository

git clone https://github.com/deaneeth/enterprise-cinema-booking-platform.git
cd enterprise-cinema-booking-platform

2. Install dependencies

# Install root dependencies
npm install

# Install backend dependencies
cd backend
npm install

# Install frontend dependencies
cd ../frontend
npm install

3. Configure environment variables

# Backend (.env in /backend directory)
cp backend/.env.example backend/.env

Edit backend/.env:

# Server
PORT=5000
NODE_ENV=development

# MongoDB
MONGODB_URI=mongodb://localhost:27017/cinema-booking

# JWT
JWT_SECRET=your-super-secret-key
JWT_EXPIRES_IN=7d

# PayPal (Optional - for payments)
PAYPAL_CLIENT_ID=your-paypal-client-id
PAYPAL_CLIENT_SECRET=your-paypal-client-secret
PAYPAL_MODE=sandbox

# Email (Optional - for verification)
SENDGRID_API_KEY=your-sendgrid-api-key
FROM_EMAIL=noreply@yourcinema.com

4. Start MongoDB

# Using Docker
docker run -d -p 27017:27017 --name mongodb mongo:latest

# Or install MongoDB locally
# https://www.mongodb.com/docs/manual/installation/

5. Run the application

# Start backend (from /backend directory)
cd backend
npm run dev

# Start frontend (from /frontend directory - new terminal)
cd frontend
npm start

📖 Usage

Default Accounts

After seeding the database (or first run), use these accounts:

Role	Email	Password
Platform Admin	`admin@gmail.com`	`Admin123`
Cinema Admin	`cinema@gmail.com`	`Cinema123`
Regular User	`user@gmail.com`	`User123`

User Workflows

journey
    title Movie Booking Journey
    section Browse
      View Movies: 5: User
      Select Movie: 5: User
      View Showtimes: 5: User
    section Book
      Select Seats: 4: User
      15-min Timer Starts: 3: System
      Proceed to Payment: 4: User
    section Pay
      PayPal Checkout: 4: User
      Confirm Payment: 5: PayPal
    section Receive
      Get QR Ticket: 5: System
      Download PDF: 5: User

📡 API Documentation

The API follows RESTful conventions with comprehensive documentation.

Base URL

Development: http://localhost:5000/api
Production: https://api.your-domain.com/api

Authentication

All protected endpoints require a Bearer token:

Authorization: Bearer <your-jwt-token>

Quick Reference

Endpoint	Method	Description	Auth
`/auth/register`	POST	Register new user	❌
`/auth/login`	POST	Login user	❌
`/movies`	GET	List all movies	❌
`/movies/:id`	GET	Get movie details	❌
`/cinemas`	GET	List all cinemas	❌
`/showtimes`	GET	Get showtimes	❌
`/bookings`	POST	Create booking	✅
`/bookings/:id`	GET	Get booking	✅
`/payments/create-order`	POST	Create PayPal order	✅
`/payments/capture`	POST	Capture payment	✅

📚 View Full API Documentation

See API_DOCUMENTATION.md for complete endpoint details, request/response schemas, and examples.

🧪 Testing

# Run all backend tests
cd backend
npm test

# Run unit tests only
npm run test:unit

# Run integration tests
npm run test:integration

# Run with coverage report
npm run test:coverage

# Run frontend tests
cd frontend
npm test

Test Coverage

Module	Coverage
Controllers	~80%
Services	~85%
Models	~90%
Middleware	~75%

📁 Project Structure

enterprise-cinema-booking-platform/
├── 📂 backend/
│   ├── 📂 src/
│   │   ├── 📂 config/        # Database & app configuration
│   │   ├── 📂 controllers/   # Route handlers
│   │   ├── 📂 middlewares/   # Auth, validation, error handling
│   │   ├── 📂 models/        # Mongoose schemas
│   │   ├── 📂 routes/        # API routes
│   │   ├── 📂 services/      # Business logic
│   │   ├── 📂 tests/         # Unit & integration tests
│   │   ├── 📂 types/         # TypeScript definitions
│   │   ├── 📂 utils/         # Helper functions
│   │   └── 📄 server.ts      # Entry point
│   ├── 📄 package.json
│   └── 📄 tsconfig.json
│
├── 📂 frontend/
│   ├── 📂 src/
│   │   ├── 📂 components/    # Reusable UI components
│   │   ├── 📂 contexts/      # React contexts
│   │   ├── 📂 hooks/         # Custom hooks
│   │   ├── 📂 pages/         # Page components
│   │   ├── 📂 services/      # API client
│   │   ├── 📂 types/         # TypeScript types
│   │   └── 📄 App.tsx        # Root component
│   ├── 📄 package.json
│   └── 📄 tailwind.config.js
│
├── 📂 docs/                  # Documentation
├── 📄 docker-compose.yml     # Docker configuration
├── 📄 .github/workflows/     # CI/CD pipelines
└── 📄 README.md

🗄️ Database Schema

erDiagram
    USER ||--o{ BOOKING : makes
    USER ||--o{ REVIEW : writes
    CINEMA ||--o{ SHOWTIME : has
    CINEMA ||--o{ REVIEW : receives
    MOVIE ||--o{ SHOWTIME : scheduled_in
    MOVIE ||--o{ REVIEW : receives
    SHOWTIME ||--o{ BOOKING : for
    BOOKING ||--o| PAYMENT : has

    USER {
        ObjectId _id PK
        string email UK
        string password
        string name
        enum role
        boolean isVerified
    }

    CINEMA {
        ObjectId _id PK
        string name
        string location
        array facilities
        ObjectId adminId FK
    }

    MOVIE {
        ObjectId _id PK
        string title
        string description
        number duration
        string genre
        string poster
    }

    SHOWTIME {
        ObjectId _id PK
        ObjectId movieId FK
        ObjectId cinemaId FK
        datetime startTime
        number price
        array seats
    }

    BOOKING {
        ObjectId _id PK
        ObjectId userId FK
        ObjectId showtimeId FK
        array seats
        enum status
        number totalAmount
    }

    PAYMENT {
        ObjectId _id PK
        ObjectId bookingId FK
        string paypalOrderId
        number amount
        enum status
    }

📚 View Full Database Schema

🤝 Contributors

_{Dineth Hettiarachchi} _{Project Lead}	_{Wickramaarachchi B S} _{Backend Developer}	_{Himasha Sandeepani} _{Frontend Developer}	_{Kasun Madhusanka} _{Full Stack Developer}
_Kavindu _{Backend Developer}	_Ashiru _{Frontend Developer}	_{Jayaweera HRK} _Developer	_{Rashmi Edirisinghe} _Developer