Library Management System

A library management system built with Spring Boot, split into public book catalog browsing, customer self-service reservations, and librarian workflow management.

Features

• Book management with data validation and author relationships
• Author management with many-to-many relationships to books
• Copy tracking with status management (available, borrowed, reserved, lost)
• Borrowing and reservation system with state transition validation
• Customer management with offline and online account separation
• Role-based access control (Librarian vs Customer vs Public)
• Optimistic locking and retry mechanisms to prevent concurrency issues
• Authentication and authorization with Spring Security and password hashing
• Comprehensive integration and unit testing
• Application monitoring with Prometheus and Grafana
• Detailed API documentation with Swagger
• Docker Compose setup for easy deployment
• Caching book catalog with Caffeine
• Logs in JSON format with MDC
• CI with GitHub Actions
• Frontend for staff operations using Thymeleaf and Bootstrap

Tech Stack

• Java 21 + Spring Boot 3.5
• JPA/Hibernate with PostgreSQL
• Spring Security for authentication and role-based authorization
• Slf4j + Logback for logging
• Prometheus for metrics collection
• Grafana for monitoring dashboards
• Docker Compose for containerization
• Swagger for API documentation
• Caffeine for caching
• JUnit 5 + MockMvc for testing
• Flyway for database migrations
• Testcontainers for integration tests
• Thymeleaf + Bootstrap for staff frontend
• Maven

Starting Guide

# Clone environment
cp .env.example .env
# Edit .env with your database credentials. For example:
# POSTGRES_USER=library_admin
# POSTGRES_PASSWORD=secret123
# POSTGRES_DB=library_db

# Start all services
docker compose up

The application runs on http://localhost:8080. API documentation is available via Swagger. Monitoring dashboard is available via Grafana and Prometheus. Access the staff panel athttp://localhost:8080/register.

Monitoring Setup Guide

1. Visit Grafana at http://localhost:3000 (admin/admin)
2. Create a new data source:
   • Type: Prometheus
   • URL: http://prometheus:9090
   • Use default settings for everything else
3. Click "Save & Test"
4. Import dashboard from grafana/dashboard.json
5. Select the created Prometheus data source
6. Generate sample data by running exampleRequests/complete-workflow.http

API Overview

Full API Documentation and details are available at http://localhost:8080/swagger-ui/index.html. The API is organized into four main areas:

Public Browsing (No Authentication Required)

Browse books and authors, search the catalog, check what's available

Customer Self-Service (CUSTOMER role)

Create, view and cancel your reservations

Desk Operations (LIBRARIAN role)

Handle checkouts, returns, and mark items as lost

Admin Operations (LIBRARIAN role)

Manage books, copies, and customer accounts

Example HTTP Requests

The exampleRequests directory contains ready-to-use HTTP requests:

exampleRequests/
├── admin/
│   ├── books.http        # Book CRUD operations
│   ├── copies.http       # Copy management
│   └── customers.http    # Customer management
├── customer/
│   └── reservations.http # Customer self-service
├── librarian/
│   └── desk.http        # Desk operations
├── public/
│   ├── auth.http        # Authentication flows
│   └── browse.http      # Public browsing
└── complete-workflow.http # Full use case example

Progress

• Basic book CRUD operations
• ISBN regex validation and duplicate prevention
• Many-to-many author-book relationships with author duplicate prevention
• Book search
• Copy status tracking (available, borrowed, reserved, lost)
• State transition validation for copies
• Comprehensive test coverage written while procrastinating adding new features (ongoing)
• Customer management
• Borrowing and reservation system with customers
• Authentication and authorization with Spring Security
• Password hashing and secure user management
• Role-based access control (Librarian vs Customer)
• Centralized messages
• Proper separation of admin, desk, and customer endpoints
• PostgreSQL migration from H2
• Docker support
• Application monitoring with Prometheus and Grafana
• Custom dashboard in Grafana
• Proper API documentation
• Caching
• Logs in JSON format with MDC
• CI
• Login and registration pages
• Admin panel with full operations:
  • Books
  • Copies
  • Customers
• Concurrency protection
• Deployment
• Flyway migrations
• PostgreSQL testcontainers for integration tests
• Enhance admin panel with HTMX
• Separate frontend for customers

Gallery

Book browsing page Book adding form showcasing data validation Copy browsing page Copy checkout form Customer browsing page Grafana dashboard during high load simulation using the config in grafana/dashboard.json.