Librarianz 📚

A simple Library Management System built with Spring Boot, providing RESTful APIs for managing authors, books, members, and borrowed book records with enterprise-grade features including soft deletes and audit timestamps.

🚀 Features

• Complete CRUD Operations for Authors, Books, Members, and Borrowed Books
• Soft Delete Pattern - Data is never permanently deleted, only marked as deleted
• Audit Timestamps - Automatic tracking of created_at, updated_at, and deleted_at
• Pagination & Search - All list endpoints support pagination and search filtering
• RESTful API Design - Standard HTTP methods and status codes
• PostgreSQL Database - Robust relational database with Supabase support
• Docker Ready - Multi-stage Docker build

📋 Prerequisites

• Java 21 or higher
• Maven 3.6+
• PostgreSQL 12+
• Docker (optional, for containerized deployment)

🛠️ Tech Stack

• Framework: Spring Boot 4.0.0
• Language: Java 21
• Database: PostgreSQL
• ORM: Spring Data JPA / Hibernate
• Build Tool: Maven
• Deployment: Docker, Render.com

📦 Installation

1. Clone the Repository

git clone https://github.com/bayulaxana05/librarianz.git
cd librarianz

2. Configure Database

Create a .env file or set environment variables:

DB_URL=jdbc:postgresql://localhost:5432/librarianz
DB_USERNAME=your_username
DB_PASSWORD=your_password

Or update src/main/resources/application.properties directly (not recommended for production).

3. Build the Application

Using Maven wrapper:

# Windows
.\mvnw clean package

# Linux/Mac
./mvnw clean package

Or with Maven installed:

mvn clean package

4. Run the Application

Option A: Using JAR file

# Set environment variables (PowerShell)
$env:DB_URL="jdbc:postgresql://localhost:5432/librarianz"
$env:DB_USERNAME="your_username"
$env:DB_PASSWORD="your_password"
$env:PORT="8080"

# Run the JAR
java -jar target/librarianz-0.0.1-SNAPSHOT.jar

Option B: Using Maven

.\mvnw spring-boot:run

Option C: Using Docker

# Build the image
docker build -t librarianz:latest .

# Run the container
docker run -p 8080:8080 \
  -e DB_URL="jdbc:postgresql://host.docker.internal:5432/librarianz" \
  -e DB_USERNAME="your_username" \
  -e DB_PASSWORD="your_password" \
  librarianz:latest

The API will be available at http://localhost:8080

🔌 API Endpoints

Authors

Method	Endpoint	Description
GET	/api/authors?page=1&size=10&search=	Get all authors (paginated)
GET	/api/authors/{id}	Get author by ID
POST	/api/authors	Create new author
PUT	/api/authors/{id}	Update author
DELETE	/api/authors/{id}	Soft delete author

Books

Method	Endpoint	Description
GET	/api/books?page=1&size=10&search=	Get all books (paginated)
GET	/api/books/{id}	Get book by ID
POST	/api/books	Create new book
PUT	/api/books/{id}	Update book
DELETE	/api/books/{id}	Soft delete book

Members

Method	Endpoint	Description
GET	/api/members?page=1&size=10&search=	Get all members (paginated)
GET	/api/members/{id}	Get member with borrowed books
POST	/api/members	Create new member
PUT	/api/members/{id}	Update member
DELETE	/api/members/{id}	Soft delete member

Borrowed Books

Method	Endpoint	Description
GET	/api/borrowed-books?page=1&size=10&search=	Get all borrowed books (paginated)
GET	/api/borrowed-books/{id}	Get borrowed book by ID
POST	/api/borrowed-books	Create borrow record
PUT	/api/borrowed-books/{id}	Update borrow record
DELETE	/api/borrowed-books/{id}	Soft delete borrow record

📝 Sample API Requests

Create an Author

curl -X POST http://localhost:8080/api/authors \
  -H "Content-Type: application/json" \
  -d '{
    "name": "J.K. Rowling",
    "biography": "British author, best known for Harry Potter series",
    "website": "https://www.jkrowling.com",
    "birthDate": "1965-07-31"
  }'

Create a Book

curl -X POST http://localhost:8080/api/books \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Harry Potter and the Philosopher'\''s Stone",
    "category": "Fantasy",
    "publishedYear": 1997,
    "author": {
      "id": 1
    }
  }'

Create a Member

curl -X POST http://localhost:8080/api/members \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice Johnson",
    "username": "alice_j",
    "email": "alice@example.com",
    "phoneNumber": "555-0001",
    "address": "123 Main St, New York, NY"
  }'

Create a Borrowed Book Record

curl -X POST http://localhost:8080/api/borrowed-books \
  -H "Content-Type: application/json" \
  -d '{
    "book": { "id": 1 },
    "member": { "id": 1 },
    "borrowDate": "2024-01-15",
    "returnDate": ""
  }'

🏗️ Project Structure

librarianz/
├── src/
│   ├── main/
│   │   ├── java/com/example/librarianz/
│   │   │   ├── LibrarianzApplication.java
│   │   │   ├── controller/
│   │   │   │   ├── AuthorController.java
│   │   │   │   ├── BookController.java
│   │   │   │   ├── MemberController.java
│   │   │   │   └── BorrowedBookController.java
│   │   │   ├── entity/
│   │   │   │   ├── Author.java
│   │   │   │   ├── Book.java
│   │   │   │   ├── Member.java
│   │   │   │   └── BorrowedBook.java
│   │   │   ├── repository/
│   │   │   │   ├── AuthorRepository.java
│   │   │   │   ├── BookRepository.java
│   │   │   │   ├── MemberRepository.java
│   │   │   │   └── BorrowedBookRepository.java
│   │   │   └── service/
│   │   │       ├── AuthorService.java
│   │   │       ├── BookService.java
│   │   │       ├── MemberService.java
│   │   │       └── BorrowedBookService.java
│   │   └── resources/
│   │       └── application.properties
│   └── test/
├── Dockerfile
├── .dockerignore
├── pom.xml
└── README.md

🔧 Configuration

Application Properties

Key configuration options in application.properties:

# Database Configuration (use environment variables)
spring.datasource.url=${DB_URL}
spring.datasource.username=${DB_USERNAME}
spring.datasource.password=${DB_PASSWORD}

# Hibernate Settings
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=false

Environment Variables

Required environment variables:

• DB_URL - PostgreSQL connection string
• DB_USERNAME - Database username
• DB_PASSWORD - Database password
• PORT - Application port (default: 8080)

👤 Author

bayulaxana05

• GitHub: @bayulaxana05