🏨 Reception — Hotel Reception Management System

A full-stack web application built to digitize hotel reception operations from end to end. Guest records, room management, reservations, payments, parking tracking, and more — all managed from a single place.

The backend is powered by Spring Boot 3.4, the frontend by Angular 21. It uses PostgreSQL as the database, MinIO for file storage, Stripe for payments, and SendGrid for email delivery. Everything runs on Docker.

🧰 Tech Stack

Layer	Technology
Backend	Java 17, Spring Boot 3.4.2, Spring Security, Spring Data JPA
Frontend	Angular 21, TypeScript 5.9, Bootstrap 5 (Bootswatch), Tailwind CSS 4
Database	PostgreSQL 15
File Storage	MinIO (S3-compatible object storage)
Payments	Stripe
Email	SendGrid + Thymeleaf templates
Authentication	JWT (JSON Web Token)
Migration	Flyway
Mapping	MapStruct + Lombok
Rate Limiting	Bucket4j + Caffeine Cache
API Docs	Springdoc OpenAPI (Swagger UI)
Testing	JUnit, Spring Security Test, H2 (in-memory), Vitest (frontend)
Containers	Docker & Docker Compose
Build	Maven (backend), npm (frontend), multi-stage Dockerfile

📁 Project Structure

Reception/
├── docker-compose.yml          # Spins up all services
├── Dockerfile                  # Multi-stage build for the backend
├── pom.xml                     # Maven dependencies
├── .env                        # (You need to create this) Environment variables
│
├── src/main/java/.../reception/
│   ├── common/                 # Shared infrastructure
│   │   ├── config/             # Application configuration
│   │   ├── entity/             # Base entity classes
│   │   ├── exception/          # Global error handling
│   │   ├── filter/             # JWT filters
│   │   ├── response/           # Standardized API response models
│   │   ├── security/           # Spring Security setup
│   │   └── utility/            # Helper classes
│   │
│   └── features/               # Business logic modules
│       ├── admin/              # Admin management
│       ├── audit/              # Audit logs
│       ├── email/              # Email delivery
│       ├── guest/              # Guest operations
│       ├── images/             # Image management (MinIO)
│       ├── parking/            # Parking tracking
│       ├── profile/            # User profile
│       ├── receptionist/       # Receptionist management
│       ├── reservation/        # Reservation operations
│       ├── room/               # Room management
│       ├── schedule/           # Scheduling / Shifts
│       ├── stripe/             # Payment integration
│       └── user/               # User authentication
│
├── src/main/resources/
│   ├── application.properties  # Application settings
│   ├── db/migration/           # Flyway SQL files (V1–V8)
│   └── templates/              # Thymeleaf email templates
│
└── src/main/frontend/          # Angular application
    ├── Dockerfile              # Multi-stage build for the frontend
    ├── nginx.conf              # Nginx reverse proxy config
    └── src/app/
        ├── core/               # Guards, interceptors, models, services
        ├── features/           # Page components (16 modules)
        └── shared/             # Shared components

✨ Features

👤 User Roles

The application is built around three distinct roles:

Role	Permissions
ADMIN	Full access — user, room, guest, reservation, receptionist, parking, image, and audit log management
RECEPTIONIST	Guest, reservation, parking, and schedule management
GUEST	View own profile, track reservations, make payments

🔑 Security & Authentication

Stateless authentication via JWT
Role-based access control (route guards + backend filtering)
Temporary password mechanism for account creation
Rate limiting for brute-force protection (Bucket4j)

🏠 Room & Reservation Management

Create, edit, and delete rooms
Upload room images (via MinIO)
Create and track reservations
Guest-specific reservation history

💳 Payments

Secure online payments with Stripe integration
Refund support

📧 Email

Email delivery via SendGrid API
Thymeleaf templates (reservation confirmation, temporary password)

🚗 Parking Tracking

Assign and manage parking spaces for guests

📋 Audit Logs

Automatic created_by, created_at, updated_by, updated_at tracking for all entities
Audit log viewer in the admin panel

🖼️ Image Management

Image storage on MinIO (S3-compatible) object storage
Room image upload and listing

⚙️ Prerequisites

Make sure you have the following installed before getting started:

Java JDK 17 or higher
Node.js v18+ and npm
Docker Desktop
Maven (comes bundled with most IDEs)

🔧 Setup

1. Create the Environment Variables File

Create a .env file in the project root directory and fill in the following variables with your own values:

# Database
DB_USER=reception_admin
DB_PASSWORD=your_strong_password

# JWT
JWT_SECRET_KEY=your_unique_jwt_secret_key

# SendGrid (Email)
SENDGRID_API_KEY=your_sendgrid_api_key
SPRING_EMAIL=verified@email.com
MAIL_FROM_NAME=Reception Hotel

# Stripe (Payments)
STRIPE_SECRET_KEY=your_stripe_secret_key

# MinIO (File Storage)
MINIO_USER=minioadmin
MINIO_PASSWORD=minioadmin
MINIO_ENDPOINT=http://localhost:9000

2. IDE Environment Variables (For Local Development)

If you're running the app from your IDE, add these environment variables to the ReceptionApplication run configuration:

DB_USER=reception_admin
DB_PASSWORD=your_strong_password
SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/reception_db
SPRING_DATASOURCE_USERNAME=reception_admin
SPRING_DATASOURCE_PASSWORD=your_strong_password
JWT=your_unique_jwt_secret_key
SENDGRID_API_KEY=your_sendgrid_api_key
SPRING_EMAIL=verified@email.com
MAIL_FROM_NAME=Reception Hotel
STRIPE_SECRET_KEY=your_stripe_secret_key
MINIO_USER=minioadmin
MINIO_PASSWORD=minioadmin
MINIO_ENDPOINT=http://localhost:9000

🚀 Running the App

You can run the application in two ways:

Option 1: Docker (Recommended) 🐳

The easiest way. A single command brings everything up:

docker compose up --build -d

This command starts the following services:

reception_backend — Spring Boot application
reception_frontend — Angular app (served via Nginx)
reception_postgres — PostgreSQL database
reception_flyway — Database migrations
reception_minio — File storage service

Open the app: http://localhost:4200

To follow the logs:

docker logs -f reception_backend

To start fresh (including wiping the database):

docker compose down -v
docker compose up --build -d

Option 2: Local Development 💻

Ideal for active development. The database still runs via Docker, but the backend and frontend run locally.

Step 1 — Start the database and MinIO:

docker compose up --build -d db minio

Step 2 — Start the backend:

Run ReceptionApplication.java from your IDE, or:

./mvnw spring-boot:run

Step 3 — Start the frontend:

cd src/main/frontend
npm install
npm run build
ng serve

Frontend: http://localhost:4200
Backend (Swagger): http://localhost:8080/swagger-ui/index.html

🔌 Port Map

Service	Port	Description
Frontend	`4200`	Angular app (Nginx in Docker, `ng serve` locally)
Backend (Docker)	`8082`	Spring Boot application (Docker container)
Backend (Local)	`8080`	Spring Boot application (IDE / Maven)
PostgreSQL	`5432`	Database
MinIO API	`9000`	Object storage API
MinIO Console	`9001`	MinIO management console

📖 API Documentation

Explore and test all API endpoints through Swagger UI.

Local: http://localhost:8080/swagger-ui/index.html
Docker: http://localhost:8082/swagger-ui/index.html

All REST endpoints are versioned with the /api/v1 prefix.

🏗️ Technical Details

Topic	Detail
Architecture	Feature-based package structure split into `common` (infrastructure) and `features` (business logic)
Security	Stateless JWT authentication with `JwtAuthenticationFilter` for request filtering
Database Migration	8 SQL migration files (V1–V8) managed by Flyway
Error Handling	Global exception handler with standardized HTTP error responses
Auditing	JPA Auditing for automatic `created_by/at`, `updated_by/at` tracking
Logging	Structured logging via SLF4J (`@Slf4j`), configured in `logback-spring.xml`
Rate Limiting	API request throttling with Bucket4j + Caffeine Cache
Object Mapping	DTO ↔ Entity conversions via MapStruct
Email Templates	HTML email templates with Thymeleaf (`reservation-confirmation`, `temporary-password`)
Frontend Build	Multi-stage Docker build (Node.js → Nginx), Tailwind CSS + Bootstrap
Testing	Backend: JUnit + Spring Security Test + H2, Frontend: Vitest

🔒 Git Policies

The following are excluded via .gitignore for security and a clean repository:

.env — Environment secrets, should never be committed
target/ — Java build artifacts
node_modules/ — Frontend dependencies
src/main/resources/static/* — Auto-generated frontend assets
.idea/, .vscode/ — IDE configurations

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/awesome-feature)
Commit your changes (git commit -m 'Add awesome feature')
Push to the branch (git push origin feature/awesome-feature)
Open a Pull Request

Reception — Built to simplify hotel management. 🏨

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

🏨 Reception — Hotel Reception Management System

📑 Table of Contents

🧰 Tech Stack

📁 Project Structure

✨ Features

👤 User Roles

🔑 Security & Authentication

🏠 Room & Reservation Management

💳 Payments

📧 Email

🚗 Parking Tracking

📋 Audit Logs

🖼️ Image Management

⚙️ Prerequisites

🔧 Setup

1. Create the Environment Variables File

2. IDE Environment Variables (For Local Development)

🚀 Running the App

Option 1: Docker (Recommended) 🐳

Option 2: Local Development 💻

🔌 Port Map

📖 API Documentation

🏗️ Technical Details

🔒 Git Policies

🤝 Contributing

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

🏨 Reception — Hotel Reception Management System

📑 Table of Contents

🧰 Tech Stack

📁 Project Structure

✨ Features

👤 User Roles

🔑 Security & Authentication

🏠 Room & Reservation Management

💳 Payments

📧 Email

🚗 Parking Tracking

📋 Audit Logs

🖼️ Image Management

⚙️ Prerequisites

🔧 Setup

1. Create the Environment Variables File

2. IDE Environment Variables (For Local Development)

🚀 Running the App

Option 1: Docker (Recommended) 🐳

Option 2: Local Development 💻

🔌 Port Map

📖 API Documentation

🏗️ Technical Details

🔒 Git Policies

🤝 Contributing