Hotel Booking System - Documentation

Complete documentation of the implementation and architecture

Table of Contents

1. Project Overview

The Hotel Booking System is a full-stack web application designed to facilitate hotel room bookings, property management, and reservation handling. The system provides a clean, user-friendly interface for guests to search, view, and book hotel rooms, while also offering administrative capabilities for property and inventory management.

This project follows a modern architecture pattern with a Next.js frontend communicating with a Spring Boot REST API backend, backed by PostgreSQL for data persistence.

2. Technology Stack

Frontend

  • Next.js 14 - React framework with App Router for server-side rendering and routing
  • TypeScript - Type-safe JavaScript for better development experience
  • Tailwind CSS - Utility-first CSS framework for rapid UI development
  • React Hooks - For state management and side effects
  • Fetch API - For making HTTP requests to the backend

Backend

  • Spring Boot 3.x - Java framework for building RESTful APIs
  • Java 21 - Modern Java with latest features
  • Spring Data JPA - For database operations and ORM
  • Spring Security - For authentication and authorization
  • PostgreSQL 16 - Relational database for data persistence
  • Flyway - Database migration tool

Development Tools

  • Git - Version control
  • Maven/Gradle - Build automation
  • Docker - Containerization (for deployment)

3. Architecture

System Architecture

The application follows a client-server architecture with clear separation between frontend and backend:

  • Frontend (Next.js): Handles UI/UX, user interactions, and client-side state management
  • Backend (Spring Boot): Provides RESTful APIs, business logic, and data processing
  • Database (PostgreSQL): Stores all persistent data including properties, rooms, reservations, etc.

Data Flow

  1. User interacts with Next.js frontend (searches, views properties, makes bookings)
  2. Frontend makes HTTP requests to Spring Boot REST API endpoints
  3. Spring Boot processes requests, applies business logic, and queries PostgreSQL
  4. Database returns data to Spring Boot
  5. Spring Boot formats and returns JSON responses to frontend
  6. Frontend updates UI based on API responses

4. Implementation Details

Frontend Implementation

Project Structure

app/
├── page.tsx              # Home page with search and property listing
├── layout.tsx            # Root layout with Navbar and Footer
├── properties/
│   └── [id]/page.tsx     # Property details page
├── booking/page.tsx      # Booking form page
├── bookings/page.tsx      # User bookings list
└── admin/                # Admin pages
    ├── properties/
    ├── room-types/
    └── inventory/

components/
├── Navbar.tsx            # Navigation bar
├── Footer.tsx            # Footer component
├── PropertyCard.tsx      # Property card display
├── RoomTypeCard.tsx      # Room type card
├── PropertyFilters.tsx   # Sidebar filters
├── FeaturesSection.tsx   # Features section
├── SearchBar.tsx         # Search bar component
├── DatePicker.tsx        # Date picker input
├── PriceBadge.tsx        # Price display component
└── BookingSummary.tsx   # Booking summary card

Backend Implementation (Spring Boot)

Key Modules

  • Catalog Module: Manages properties, room types, rooms, and rate plans
  • Availability Module: Handles availability checks and inventory management
  • Reservation Module: Manages booking lifecycle (create, confirm, cancel)
  • Payment Module: Integrates with payment gateways (Razorpay/Stripe/PayU)
  • Housekeeping Module: Tracks room status and cleaning logs
  • User & Auth Module: Handles authentication and role-based access control
  • Reporting Module: Generates occupancy, ADR, and RevPAR reports

Database Schema (PostgreSQL)

Core Entities

  • property: Hotel properties with address, contact info, timezone
  • room_type: Room categories with occupancy limits and descriptions
  • room: Individual rooms linked to room types and properties
  • rate_plan: Pricing plans with cancellation policies
  • rate_calendar: Daily pricing and availability rules
  • inventory: Daily room availability (total, reserved, out-of-order)
  • reservation: Booking records with guest info and status
  • payment: Payment transactions and refunds
  • user: System users with roles (ADMIN, AGENT, HOUSEKEEPING, GUEST)

5. API Endpoints

Public/Guest APIs

GET /v1/properties

Fetch all available properties

GET /v1/property/{id}/details

Get detailed property information including room types

POST /v1/admin/search-details

Search properties by location, check-in, and check-out dates

Body: { checkIn, checkOut, location }

Admin APIs

POST /v1/admin/properties

Create new property

GET /v1/admin/properties

List all properties (admin view)

POST /v1/admin/room-types

Create room type

6. Frontend Components

Reusable Components

Layout Components

  • Navbar - Sticky navigation with menu
  • Footer - Site footer with links

Property Components

  • PropertyCard - Property display card
  • PropertyFilters - Sidebar filter component
  • RoomTypeCard - Room type information

Form Components

  • SearchBar - Search form
  • DatePicker - Date input component
  • BookingSummary - Booking details summary

Display Components

  • PriceBadge - Price display
  • FeaturesSection - Features showcase

7. Features Implemented

User Features

  • Property Search: Search properties by location, dates, guests, and rooms
  • Property Listing: View all available properties with images, prices, and ratings
  • Property Details: Detailed view with room types, descriptions, and contact information
  • Filtering: Filter properties by price range, room type, and minimum rating
  • Booking Flow: Complete booking process with guest information form
  • My Bookings: View all user reservations with status and details

Admin Features

  • Property Management: Create, edit, and delete properties
  • Room Type Management: Manage room types with capacity and pricing
  • Inventory Management: View room inventory by date with availability tracking

Technical Features

  • Responsive Design: Mobile-first approach with Tailwind CSS
  • API Integration: RESTful API calls with proper error handling
  • State Management: React hooks for component state
  • URL Parameters: Search parameters preserved in URL for sharing
  • Loading States: Loading indicators during API calls
  • Error Handling: Graceful error messages and empty states

How It Works

Property Search Flow

  1. User enters search criteria (location, dates, guests, rooms) on home page
  2. Frontend calls POST /v1/admin/search-details with search parameters
  3. Backend queries PostgreSQL for matching properties based on availability
  4. Results are filtered and returned as JSON
  5. Frontend displays properties in a responsive grid layout
  6. User can apply additional filters (price, rating) client-side

Property Details Flow

  1. User clicks on a property card
  2. Frontend navigates to /properties/{id}
  3. Page calls GET /v1/property/{id}/details
  4. Backend fetches property details, room types, and pricing from PostgreSQL
  5. Frontend displays property information, room types with descriptions, and contact details
  6. User can select a room type to proceed with booking

Backend Architecture (Spring Boot)

The Spring Boot backend follows a layered architecture:

  • Controller Layer: REST endpoints that handle HTTP requests/responses
  • Service Layer: Business logic and orchestration
  • Repository Layer: Data access using Spring Data JPA
  • Entity Layer: JPA entities mapping to database tables

Database Operations: Spring Data JPA provides automatic query generation and transaction management. Flyway handles database migrations to ensure schema consistency.

8. Future Enhancements

Planned Features

Booking & Payments

  • Complete booking creation with payment integration
  • Payment gateway integration (Razorpay/Stripe)
  • Booking confirmation emails
  • Cancellation and refund processing

Authentication

  • User registration and login
  • JWT-based authentication
  • Role-based access control (RBAC)
  • Password reset functionality

Advanced Features

  • Check-in/Check-out management
  • Housekeeping status updates
  • Rate plan management
  • Promotional codes and discounts
  • Multi-property support

Reporting & Analytics

  • Occupancy reports
  • Revenue analytics (ADR, RevPAR)
  • Daily arrivals/departures
  • Dashboard with key metrics

Backend Architecture (PRD Summary)

Core Modules

The Spring Boot backend is organized into modular components: Catalog (properties/rooms/rates), Availability (inventory management), Reservation (booking lifecycle), Payment (gateway integration), Housekeeping (room status), User & Auth (authentication/authorization), and Reporting (analytics).

Availability Algorithm

The system uses an atomic inventory update mechanism to prevent overbooking. When a booking is initiated, a hold is created with a TTL (time-to-live) in Redis, and inventory is reserved atomically. This ensures no double-bookings even under concurrent load.

Security & Compliance

The backend implements OAuth2/OIDC with JWT tokens, password hashing (Argon2id/BCrypt), input validation, and audit logging. Payment data follows PCI-DSS guidelines with tokenization.

Performance & Scalability

The system is designed for horizontal scaling with stateless instances, database read replicas, Redis caching, and optimized queries. Target performance: P95 latency < 300ms for reads, 99.9% availability.

Additional Resources

For more detailed information about the backend implementation, refer to the Product Requirements Document (PRD) which outlines the complete system architecture, data models, API specifications, and implementation guidelines.

Note: This documentation reflects the current state of the implementation. As new features are added, this page will be updated accordingly.