🏨 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.

---

📑 Table of Contents

• Tech Stack
• Project Structure
• Features
• Prerequisites
• Setup
• Running the App
• Port Map
• API Documentation
• Technical Details
• Git Policies

---

🧰 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

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

---

Reception — Built to simplify hotel management. 🏨