The powerful RESTful server-side engine for the Shelfy Library Management System, built with Node.js, Express and MongoDB.
Shelfy Backend is a production-ready API that serves as the core engine for the Shelfy ecosystem. It handles complex book inventory management and borrowing workflows with strict business logic enforcement and robust data validation.
This repository focuses exclusively on the Server-Side logic, providing a high-performance RESTful API for the Shelfy Client-Side Application.
| Feature | Description |
|---|---|
| CRUD Operations | Create, read, update and delete books with full validation |
| Genre Filtering | Filter books by FICTION, NON_FICTION, SCIENCE, HISTORY, BIOGRAPHY, FANTASY |
| Advanced Sorting | Sort by any field in ascending or descending order with pagination |
| Unique ISBN | Enforces unique ISBN per book to prevent duplicate entries |
| Feature | Description |
|---|---|
| Availability Control | Auto-updates book availability when all copies are borrowed |
| Copy Management | Tracks exact copy count and prevents over-borrowing |
| Due Date Validation | Enforces future-only due dates on every borrow request |
| Borrow Summary | Aggregated view of all borrowed books with total quantities |
| Feature | Description |
|---|---|
| Zod Validation | Strong schema-level validation with detailed error messages |
| Global Error Handler | Centralized middleware for consistent, structured error responses |
| Mongoose Middleware | Pre-save hooks for automatic availability management |
| Static Methods | Reusable Mongoose static method for complex borrow logic |
| Technology | Version | Purpose |
|---|---|---|
| Node.js | LTS | JavaScript runtime environment |
| Express.js | ^5.1.0 | Web framework and routing |
| TypeScript | ^5.8.3 | Type-safe JavaScript superset |
| MongoDB | ^6.17.0 | NoSQL document database |
| Mongoose | ^8.16.2 | MongoDB ODM with schema validation |
| Zod | ^4.0.3 | Runtime schema validation |
| CORS | ^2.8.5 | Cross-origin resource sharing |
| dotenv | ^17.2.0 | Environment variable management |
| ts-node-dev | ^2.0.0 | TypeScript live-reload dev server |
┌──────────────────────────────────────────────────┐
│ Client Request │
└───────────────────────┬──────────────────────────┘
│
┌───────────────────────▼──────────────────────────┐
│ Express Application │
│ (CORS · JSON Parser · Routes) │
└──────────┬────────────────────────┬──────────────┘
│ │
┌──────────▼──────────┐ ┌──────────▼───────────────┐
│ /api/books │ │ /api/borrow │
│ Book Router │ │ Borrow Router │
└──────────┬──────────┘ └──────────┬───────────────┘
│ │
┌──────────▼────────────────────────▼───────────────┐
│ Controllers (Zod Validation) │
└──────────────────────────┬────────────────────────┘
│
┌──────────────────────────▼────────────────────────┐
│ Mongoose Models (Static Methods, │
│ Pre-save Middleware, Aggregation) │
└──────────────────────────┬────────────────────────┘
│
┌──────────────────────────▼────────────────────────┐
│ MongoDB Atlas │
└───────────────────────────────────────────────────┘
milestone-16-server/
├── src/
│ ├── app/
│ │ ├── controllers/ # Route handler logic
│ │ ├── interfaces/ # TypeScript type definitions
│ │ ├── models/ # Mongoose schemas & static methods
│ │ ├── middlewares/ # Global error & 404 handlers
│ │ └── zodSchemas/ # Zod validation schemas
│ ├── app.ts # Express app setup
│ └── server.ts # Entry point & DB connection
├── .env # Environment variables
├── package.json
└── README.md
| Requirement | Details |
|---|---|
| Node.js | v18 or higher |
| MongoDB | Atlas account or local installation |
| Package Manager | npm or yarn |
-
Clone the repository
git clone https://github.com/zahid-official/milestone-16-shelfyServer.git cd milestone-16-server -
Install dependencies
npm install
-
Configure environment variables
Create a
.envfile in the root directory:PORT=3000 DB_USER=your_mongodb_username DB_PASSWORD=your_mongodb_password DB_NAME=your_database_name
-
Start the development server
npm run dev
The server will start on
http://localhost:3000
| Variable | Description | Required |
|---|---|---|
PORT | Server port (default: 3000) | No |
DB_USER | MongoDB Atlas username | Yes |
DB_PASSWORD | MongoDB Atlas password | Yes |
DB_NAME | Target MongoDB database name | Yes |
| Script | Command | Description |
|---|---|---|
| Development | npm run dev | Start server with live reload via ts-node-dev |
| Test | npm test | Run test suite |
All API responses share a consistent structure:
{
"success": true,
"message": "Operation successful",
"data": {}
}| Method | Endpoint | Description |
|---|---|---|
GET | /api/books | Get all books (supports filter, sort, limit) |
GET | /api/books/:bookId | Get a single book by ID |
POST | /api/books | Create a new book |
PUT | /api/books/:bookId | Update an existing book |
DELETE | /api/books/:bookId | Delete a book |
Query Parameters for GET /api/books:
filter- Genre filter:FICTION | NON_FICTION | SCIENCE | HISTORY | BIOGRAPHY | FANTASYsortBy- Field to sort by (default:createdAt)sort- Order:ascordesc(default:asc)limit- Number of results (default:10)
| Method | Endpoint | Description |
|---|---|---|
GET | /api/borrow | Get aggregated borrowed books summary |
POST | /api/borrow | Borrow a book (enforces availability & copy count) |
Borrow Flow:
Client POST /api/borrow
│
▼
Zod validates { book, quantity, dueDate }
│
▼
BorrowModel.borrowBook() static method
│
┌─────┴──────┐
│ │
▼ ▼
Book exists? Enough copies?
│ │
└─────┬──────┘
│ Yes
▼
Deduct copies from book
│
▼
Pre-save hook sets available = (copies > 0)
│
▼
Save borrow record → Return 201 response
- Request received - Zod validates all fields including future-date enforcement
- Static method invoked -
BorrowModel.borrowBook()handles the complete workflow - Availability checked - Ensures sufficient copies are available before proceeding
- Copy count updated - Deducts borrowed quantity from the book document
- Middleware fires - Pre-save hook automatically recalculates the
availableflag - Borrow record saved - Returns the new borrow document with a
201status
Web Developer | Tech Enthusiast
Crafting robust, type-safe APIs and clean architectural solutions.
# 1. Fork the repository on GitHub
# 2. Clone your fork
git clone https://github.com/your-username/milestone-16-server.git
# 3. Create a feature branch
git checkout -b feature/your-feature-name
# 4. Commit your changes
git commit -m "feat: add your feature description"
# 5. Push to your fork
git push origin feature/your-feature-name
# 6. Open a Pull Request on GitHubShelfy - Your books, managed with precision.