Cinema Seat Reservation System

This project is a Spring Boot REST application that manages cinema movie screenings and seat reservations. It allows administrators to manage cinemas, halls, seats, movies, categories, screenings, and customers, while customers can view seat availability and create or cancel reservations.

All data is persisted in a relational database (PostgreSQL).

Business Requirements

1. The system must manage cinemas, each identified by name and city.
2. A cinema must contain one or more halls.
3. Each hall must contain a predefined set of seats, identified by row and number.
4. The system must manage movies, including title, duration, age rating, description, and categories.
5. A movie can belong to multiple categories, and categories can be reused.
6. A movie can be scheduled for multiple screenings.
7. A screening represents a movie shown in a specific hall at a specific date and time and has an associated price.
8. Customers must be able to view seat availability for a screening.
9. Customers must be able to create reservations for one or more seats for a screening.
10. The system must prevent double booking of the same seat for the same screening and allow reservations to be cancelled.

MVP Features

1. Cinema, Hall, and Seat Management
   Create and manage cinemas, halls inside cinemas, and seats inside halls.

2. Movie & Category Management
   Create, update, delete, and list movies and assign them to categories.

3. Screening Management
   Schedule screenings for movies in specific halls, with validation to prevent overlapping screenings.

4. Seat Availability & Reservation
   Display seat availability per screening and allow customers to reserve available seats.

5. Reservation Management
   View reservations, cancel reservations, and release seats automatically.

Entities

1. Cinema
2. Hall
3. Seat
4. Movie
5. Category
6. Screening
7. Customer
8. Reservation
9. ReservationSeat (join entity)

Entity Relationships

• One Cinema has many Halls
• One Hall has many Seats
• One Movie has many Screenings
• One Hall has many Screenings
• One Customer has many Reservations
• One Reservation belongs to one Screening
• One Reservation has many ReservationSeats
• One Seat can appear in many ReservationSeats (for different screenings)

Business Rules & Constraints

• Seat (row, number) must be unique within a hall.
• A seat can be reserved only once per screening.
• Reservation requests must contain at least one ticket.
• Ticket seat IDs must be unique inside a reservation request. (custom validation)
• Screening start time must be in the future.
• Customer email must be unique.
• Cancelling a reservation releases all associated seats.

System Usage Flow

1. Create categories
2. Create cinemas
3. Create halls for a cinema
4. Create seats for each hall
5. Create movies and assign categories
6. Create screenings for movies in halls
7. View screenings and seat availability
8. Create a customer
9. Create a reservation
10. Cancel a reservation if needed

This flow ensures correct setup and usage of the system.

API Documentation

All REST APIs in this application are fully documented using Swagger (OpenAPI 3).

The full visual API documentation exported from Swagger UI is available here: Swagger API Documentation (PDF).

The PDF was generated by exporting the Swagger UI using the browser print-to-PDF functionality.

REST API Overview (Examples)

• GET /api/movies
• POST /api/movies
• GET /api/screenings
• GET /api/screenings/{id}/seats
• POST /api/reservations
• PUT /api/reservations/{id}/cancel
• GET /api/customers
• POST /api/customers

(Complete API documentation is available in Swagger.)

Testing

• Unit tests implemented for all services.
• Controller tests implemented for all REST endpoints.
• Validation and error scenarios fully tested.

Technologies Used

• Java 21
• Spring Boot
• Spring Data JPA
• Hibernate
• PostgreSQL
• Bean Validation (Jakarta Validation)
• Swagger / OpenAPI (springdoc-openapi)
• JUnit 5 & Mockito