🛡️ Book Management Web Portal

A secure, full-stack project demonstrating the integration of Spring Boot 3, Spring Security, and Spring Data REST with a Vanilla JavaScript frontend. It integrates Google Gemini AI to act as an online book search, ensuring users can find online and "wishlist" books if they aren't currently in the local library.

This project serves as a reference for building a hypermedia-based RESTful backend coupled with a JPA-based data layer, secured via industry-standard protocols, useful also for educational purposes.

🕹️ How to Use

You log in using authorized credentials to manage the workforce. The application allows you to perform CRUD operations (Add, Update, Search Book or Borrower, and Delete) on book records, which are persisted in the H2 in-memory database during runtime.

AI-Powered Fallback Search: When a search returns no results from the local database, the system automatically triggers a request to the Gemini AI Service.

Smart Wishlisting: If the AI confirms the book exists online, users are presented with a suggestion to add the title to the "To Order/Wishlist" queue.

---

---

🚀 Key Technologies

Backend (Java 17 & Spring Boot)

• Spring Boot 3.4.1: Framework for rapid application development.

• Spring Data JPA: For object-relational mapping and database abstraction.

• Spring Data REST: Automatically exports JPA repositories as Hypermedia-driven RESTful resources.

• Spring Security 6: Manages authentication and authorization (Thymeleaf integration included).

• Google Gemini AI (via RestClient): Used for external book verification when local searches fail.

• H2 Database: An in-memory database used for development and testing.

• Jakarta Bean Validation: Ensures data integrity via @Valid annotations.

• Lombok: Reduces boilerplate code for POJOs.

• Swagger: Integrated Springdoc OpenAPI (Swagger) for endpoint testing and schema visualization

Frontend

• Thymeleaf: Server-side Java template engine for dynamic HTML rendering.

• Vanilla JavaScript (ES6+): Handles asynchronous API calls (Fetch API) and client-side DOM manipulation.

• CSS3: Custom styles featuring a responsive card-based layout and linear gradients.

🧠 **AI Logic Flow** The search operation follows a tiered discovery process:

Local Check: BookRepository queries the H2 database.

AI Verification: If database is empty, BookSearchService uses RestClient to ask Gemini: "Does this book title exist?"

UI Feedback: The frontend renders either the local book list or a special "Order/Wishlist" card based on the AI's response.

🛠️ Getting Started

Prerequisites

Java 17 or higher
Maven 3.x (or use the provided ./mvnw wrapper)
Node.js & npm (for client-side testing)

To enable the AI search, you must provide a Google Gemini API Key.
Obtain a Key: Get your free API key from the Google AI Studio.
Apply the Key: Set an environment variable on your system: export GEMINI_API_KEY='your_key' or add it directly to src/main/resources/application.properties: gemini.api.key='your_key'

Installation & Run

--> Option A: Development Mode Run the application directly using the Maven wrapper:

./mvnw spring-boot:run

--> Option B: Production Build To package the application as a standalone executable "Fat JAR":

Build the artifact

./mvnw clean package

Run the generated JAR

java -jar ./target/book-portal.jar

Once started, access the portal at: http://localhost:8080

🛠 API Documentation & Testing This project uses Springdoc OpenAPI (Swagger) to provide interactive documentation.

Accessing the UI:

http://localhost:8080/swagger-ui/index.html

OpenAPI Spec:

http://localhost:8080/v3/api-docs

⚠️ Testing POST, PUT, and DELETE By default, this application is secured with Spring Security and has CSRF protection enabled.

GET Requests: Can be tested in Swagger UI after login in http://localhost:8080/ with user/password.

POST/DELETE: These operations fail in Swagger UI. This is expected behavior because Swagger does not automatically provide the required CSRF token from the session. For dev mode, you must disable CSRF in WebSecurityConfig.java and remove the _csrf token references from JavaScript/HTML.

🧪 Testing

The project emphasizes quality through a dual-testing strategy covering both the server and client logic.

--> Server-Side Tests (JUnit 5) To verify the JPA repository layer and backend logic:

./mvnw test -Dtest=BookRepositoryTest

--> Client-Side Tests (Jest) The JavaScript validation logic is tested using Jest to ensure a robust user experience without needing a browser. Requirements: npm 8.11.0+

Install dependencies

npm install --save-dev jest
npm install --save-dev @babel/core @babel/preset-env babel-jest

Run JavaScript tests

npm test

📁 Project Structure

src/main/java: Backend controllers, entities, and repositories.

src/main/resources/static: Frontend assets (CSS/JS).

src/main/resources/templates: Thymeleaf HTML views.

src/test: Integrated suite for both JUnit and Jest