🎬 CinemaBook

A full-featured cinema ticket reservation system built with Java 21, Spring Boot, and vanilla JavaScript. Browse screenings, pick your seats on an interactive seat map, and reserve — all with real-time availability, dynamic pricing, and concurrency protection.

---

✨ Features

🎟️ Reservation Flow

• Interactive seat map — CSS Grid layout with color-coded seat types (Accessible, Standard, Premium)
• 15-minute seat locking — selected seats are held while you complete your booking
• Lazy lock expiry — no background jobs; expired locks are detected on read
• Full lifecycle — PENDING → CONFIRMED → CANCELLED or EXPIRED

💰 Dynamic Pricing

Occupancy	Tier	Multiplier
< 50%	🟢 BASE	×1.00
50–79%	🟡 MID	×1.25
≥ 80%	🔴 HIGH	×1.50

Prices are locked at reservation time — no surprises on confirmation.

🔒 Concurrency Protection

• Pessimistic locking on seat selection prevents double-booking
• Pessimistic locking on user row prevents active reservation count races
• Adjacent seat and same-row enforcement for group bookings

📋 Business Rules

• Max 10 seats per reservation
• Max 3 active reservations per customer
• All seats must be adjacent in the same row
• Booking closes 30 minutes before screening starts
• Payment modeled as status: PENDING → PAID → REFUNDED

---

🚀 Quick Start

Prerequisites

• Java 21+
• Maven 3.8+

That's it — no Docker, no external database, no npm.

Run

mvn spring-boot:run

Open

Endpoint	URL
🎬 App	http://localhost:8080
📖 Swagger UI	http://localhost:8080/swagger-ui.html
🗄️ H2 Console	http://localhost:8080/h2-console

Pre-seeded Data

The app seeds reference data on startup:

Type	Details
👤 Admin	User ID 1
👥 Customers	User IDs 2, 3, 4
🎥 Movies	Inception, The Dark Knight, Interstellar
🏛️ Hall	Hall A (10 rows × 12 seats)
📅 Screenings	3 screenings with different times

---

🧪 Testing

Run All Tests

mvn clean test

Test Suite Breakdown

Suite	Count	Description
Unit tests	44	Service logic with Mockito
Integration tests	44	MockMvc end-to-end with @SpringBootTest
🥒 BDD scenarios	58	Cucumber feature files covering 12 user stories + 1 full-lifecycle scenario
Total	146	All passing ✅

Run a Single Test Class

mvn test -Dtest=ReservationServiceTest

BDD Feature Files

Cucumber scenarios live under src/test/resources/features/:

Feature	User Story	Scenarios
us003-seat-map.feature	View seat map	5
us004-initiate-reservation.feature	Initiate reservation	9
us005-confirm-reservation.feature	Confirm reservation	4
us006-auto-lock-expiry.feature	Automatic lock expiry	5
us007-cancel-reservation.feature	Cancel reservation	5
us008-view-reservations.feature	View my reservations	4
us009-user-identification.feature	User identification	4
us013-concurrent-booking.feature	Concurrent booking	2
us017-booking-cutoff.feature	Booking cutoff	4
us018-adjacent-seat-enforcement.feature	Adjacent seats	5
us019-dynamic-pricing.feature	Dynamic pricing	5
us020-active-reservation-limit.feature	Reservation limit	4
full-lifecycle.feature	End-to-end lifecycle	2

After running tests, check target/cucumber-reports.html for a formatted BDD report.

---

🏗️ Architecture

Tech Stack

Layer	Technology
Language	Java 21
Framework	Spring Boot 3.3.11
ORM	Spring Data JPA / Hibernate
Database	H2 (file-based, persists across restarts)
API Docs	Springdoc OpenAPI 2.5.0
Frontend	Vanilla JS + HTML5 + CSS3 (single file)
Testing	JUnit 5, Mockito, MockMvc, Cucumber 7.18
Code Gen	Lombok

Project Structure

com.cinemabooking
├── 🎬 movie/           # Movie entity + repository
├── 🏛️ hall/            # Hall, Seat entities + repositories
├── 📅 screening/       # Screening, ShowSeat, controller, service, DTOs
├── 🎟️ reservation/    # Reservation, ReservationSeat, controller, service, DTOs
├── 👤 user/            # User entity + repository, UserRole enum
└── 🔧 shared/          # Enums, ErrorResponse, GlobalExceptionHandler, DataSeeder, PricingCalculator

Entity Relationships

Movie ──1:N── Screening ──1:N── ShowSeat ──N:1── Seat ──N:1── Hall
                  │
                  └──1:N── Reservation ──1:N── ReservationSeat ──N:1── ShowSeat
                               │
                               └──N:1── User

Key Design Decisions

• 🗄️ No external infrastructure — H2 file DB, no Redis, no message queues
• ⏰ Lazy expiry — no scheduled jobs; ShowSeat.getEffectiveStatus() checks lockedUntil
• 🔐 Pessimistic locking — @Lock(PESSIMISTIC_WRITE) on seat and user queries
• 💵 Price snapshots — prices calculated at initiation, stored in ReservationSeat
• 📋 Spec-first API — contract defined in openapi.yaml, no annotations on Java code
• 🧹 No auth framework — identity via X-User-Id header (training project focus is business logic)

---

📡 API Endpoints

Method	Endpoint	Description
GET	/api/screenings/{id}/seats	🗺️ Seat map with pricing & availability
POST	/api/reservations	🎟️ Initiate reservation (lock seats)
POST	/api/reservations/{code}/confirm	✅ Confirm reservation
POST	/api/reservations/{code}/cancel	❌ Cancel reservation
GET	/api/reservations	📋 List user's reservations

All mutation endpoints require the X-User-Id header.

---

🖥️ Frontend

Single-file app at src/main/resources/static/index.html:

• 🌙 Dark cinema theme with CSS custom properties
• 🪑 Interactive seat grid — click to select, color-coded by type and status
• 💵 Live pricing — pricing tier badge + per-type price table
• ⏱️ Countdown timer — shows remaining lock time on pending reservations
• 📱 Responsive — breakpoints at 700px and 480px
• 📋 My Reservations tab — filter by status, cancel confirmed bookings

---

📄 Documentation

File	Description
prd.md	Product requirements & user stories
tech-stack.md	Technology choices & constraints
decisions.md	Architectural decision log
CLAUDE.md	AI assistant instructions
testing-rules.md	Test conventions & patterns

---

📜 License

This is a training/demo project. No license specified.