Libris — Library Management System

A modern, responsive, and robust library management platform built with Spring Boot 3.5 and Vanilla ES Modules.

---

Libris is a comprehensive Library Management System designed for educational institutions. It features a secure REST API powered by Java 21 and Spring Boot, paired with an elegant, dual-theme frontend (Ember Dark / Verdigris Light) built entirely without heavy SPA frameworks.

✨ Key Features

Feature Area	Description
Secure Identity	Session-based authentication (BCrypt) + Opt-in Google OpenID Connect (SSO).
Role-Based Access	Strictly enforced permissions for ADMIN, LIBRARIAN, and STUDENT across all endpoints.
Complete Cataloging	Track Books, Magazines, and Newspapers with ISBN validation, book categories/genres, and availability locks.
Borrowing Workflow	Automated checkout, 14-day due date defaults, real-time overdue tracking, and return history.
Interactive API Docs	Auto-generated Swagger UI at /swagger-ui.html (OpenAPI 3.0) — browse and test all endpoints live.
Analytics & Reports	Dashboard analytics, CSV exports (inventory and borrowing history with due dates).
Modern UX/UI	Fast, vanilla ES Modules frontend with dynamic shell, command palette, custom CSS themes, and responsive design.
Audit & Observability	JPA auditing (created_at/updated_at), Structured JSON Logging for ELK/Datadog, Actuator health/metrics.
Production Ready	Docker Compose, Flyway versioned migrations, CSRF protection, Railway/Render 1-click deployment configs.

🏗️ Architecture Overview

flowchart LR
    Browser["Browser UI<br/>(Vanilla JS / ES Modules)"] --> Fetch["Fetch API<br/>(w/ CSRF Token)"]
    Fetch --> Controller["REST Controllers<br/>(/api/**)"]
    Controller --> Service["Transactional Services<br/>(@Service)"]
    Service --> Repository["Spring Data JPA<br/>(@Repository)"]
    Repository --> Database[("MySQL 8<br/>(Flyway Migrated)")]

Loading

🚀 Quick Start

Option A — Docker Compose (Local)

git clone https://github.com/prathamkashyap/library-management-system.git
cd library-management-system/backend
cp .env.example .env
# Edit .env: set LMS_DB_PASSWORD and LMS_ADMIN_PASSWORD
docker compose up --build

Navigate to http://localhost:8080. Log in with admin / your LMS_ADMIN_PASSWORD.
Swagger UI: http://localhost:8080/swagger-ui.html

Option B — H2 In-Memory (No Docker)

export LMS_ADMIN_PASSWORD=ChangeMe123!
./mvnw spring-boot:run -Dspring-boot.run.profiles=h2

Option C — Deploy to Railway (Recommended)

1. Go to railway.app → New Project → Deploy from GitHub repo → select this repo.
2. Add a MySQL database plugin.
3. Set env vars: LMS_DB_URL, LMS_DB_USERNAME, LMS_DB_PASSWORD, LMS_ADMIN_PASSWORD, SPRING_PROFILES_ACTIVE=docker.
4. Railway auto-detects railway.json and the multi-stage Dockerfile.

See docs/DEPLOYMENT.md for Render, Fly.io, and Hugging Face Spaces guides.

📋 API Documentation

Endpoint	Description
/swagger-ui.html	Interactive Swagger UI (try any endpoint live — no login required)
/v3/api-docs	Raw OpenAPI 3.0 JSON spec
/actuator/health	Health check probe

🧪 Running Tests

./mvnw clean verify

• 20 tests across 4 test classes (integration, CSRF flow, repository, unit)
• H2 in-memory — no MySQL or extra env vars needed
• JaCoCo enforces ≥ 70% line coverage
• Spotless enforces Google Java Format

📚 Documentation

Doc	Contents
API.md	All endpoints, request/response shapes, error codes
DATABASE.md	ER diagram, table schemas, Flyway migration log
SECURITY.md	CSRF, session, OAuth2 OIDC, role matrix
DEPLOYMENT.md	Railway, Render, Fly.io, Hugging Face, Docker Compose
FRONTEND.md	ES module architecture, component injection, theming
CURRENT_STATE.md	Live test counts, coverage, feature inventory

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

Libris is a comprehensive Library Management System designed for educational institutions. It features a secure REST API powered by Java 21 and Spring Boot, paired with an elegant, dual-theme frontend (Ember Dark / Verdigris Light) built entirely without heavy SPA frameworks.

✨ Key Features

Feature Area	Description
Secure Identity	Session-based authentication (BCrypt) + Opt-in Google OpenID Connect (SSO).
Role-Based Access	Strictly enforced permissions for ADMIN, LIBRARIAN, and STUDENT across controllers and UI.
Complete Cataloging	Track and manage Books, Magazines, and Newspapers with ISBN validation and availability locks.
Borrowing Workflow	Automated checkout limits, return history tracking, and overdue analytics.
Modern UX/UI	Fast, vanilla ES Modules frontend with dynamic shell, custom CSS properties, and responsive design.
Audit & Observability	Automatic JPA auditing (created_at / updated_at) and Structured JSON Logging for ELK/Datadog.
Production Ready	Robust Docker Compose setup, Flyway migrations, CSRF protection, and Actuator metrics.

🏗️ Architecture Overview

flowchart LR
    Browser["Browser UI<br/>(Vanilla JS / ES Modules)"] --> Fetch["Fetch API<br/>(w/ CSRF Token)"]
    Fetch --> Controller["REST Controllers<br/>(@RestController)"]
    Controller --> Service["Transactional Services<br/>(@Service)"]
    Service --> Repository["Spring Data JPA<br/>(@Repository)"]
    Repository --> Database[("MySQL 8<br/>(Flyway Migrated)")]

Loading

For an in-depth architectural breakdown, including ADRs and schema definitions, see docs/ARCHITECTURE.md.

🚀 Quick Start (Docker)

The recommended way to run Libris locally is via Docker. Ensure you have Docker and Docker Compose installed.

1. Clone the repository:

   git clone https://github.com/your-username/libris.git
   cd libris/backend

2. Configure Environment:

   cp .env.example .env
   # Edit .env and set secure values for LMS_DB_PASSWORD and LMS_ADMIN_PASSWORD

3. Launch the stack:

   docker compose up --build

Navigate to http://localhost:8080. Log in using the username admin and the password you defined in .env.

Note: To run without Docker using the embedded H2 database, run ./mvnw spring-boot:run -Dspring-boot.run.profiles=h2.

📸 Screenshots

Dashboard (Ember Theme)	Catalog (Verdigris Theme)
Analytics Overview	Student Management

(Full evidence in screenshots/desktop and screenshots/mobile)

📚 Documentation

Dive deeper into the system's technical details:

• API Contract: Request/response schemas and error codes.
• Database Setup: ER diagram and migration strategies.
• Frontend Architecture: Component injection and module boundaries.
• Security Model: CSRF flow, OAuth implementation, and role matrices.
• Production Readiness: Audit of deployment readiness, logging, and dependency hygiene.
• Release Notes: Latest changes in v1.0.1.

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details on our code of conduct, development environment setup, and the process for submitting Pull Requests.

To run the test suite locally:

./mvnw clean verify

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.