Controllers

Controllers are the bridge between HTTP requests and the data layer. Each controller module groups related handler functions for a specific API domain.

Location: backend/controllers/

---

1. Auth Controller

File: authController.js

Handles authentication flows — initial setup, login, logout, and session retrieval.

Functions

setup(req, res)

Creates the initial Super Admin account. This endpoint can only be used once — subsequent calls return 403.

• Validates: All fields required (firstName, lastName, email, contactNumber, password)
• Hashes password with bcrypt (10 rounds)
• Creates user with role: 'ROLE_ADMIN'
• Returns: JWT token + user object (sans passwordHash)

login(req, res)

Authenticates a user by email or roll number.

• Accepts: { identifier, password } — identifier can be email or rollNumber
• Checks: User exists AND isActive === true
• Compares: Password against stored bcrypt hash
• Returns: JWT token + user object (sans passwordHash)

logout(req, res)

Stateless logout — returns a success message. Token invalidation is handled client-side by removing the token from localStorage.

getMe(req, res)

Retrieves the currently authenticated user's profile.

• Requires: authenticate middleware (populates req.user)
• Returns: Full user object excluding passwordHash

---

2. Book Controller

File: bookController.js

CRUD operations for the book catalogue and physical copy management.

Functions

listBooks(req, res)

Returns all books with optional filtering.

• Query Params: search (regex match on title/author/ISBN), categoryId
• Populates: category and copies virtual relations

getBook(req, res)

Returns a single book by ID with populated category and copies.

createBook(req, res)

Creates a new book record from req.body fields.

updateBook(req, res)

Updates a book by ID using findByIdAndUpdate with { new: true }.

deleteBook(req, res)

Deletes a book by ID using findByIdAndDelete.

addCopy(req, res)

Adds a physical BookCopy to an existing book.

• Accepts: { barcode, location, status }
• Defaults: location to '', status to 'AVAILABLE'
• Validates: Parent book must exist

---

3. Circulation Controller

File: circulationController.js

Manages the book borrowing lifecycle — issue, return, and history.

Functions

issueBook(req, res)

Checks out a book copy to a user.

• Accepts: { userId, bookCopyId }
• Validates: Copy must exist AND status must be 'AVAILABLE'
• Updates: BookCopy status to 'CHECKED_OUT'
• Creates: Transaction with dueDate set to 14 days from now
• Returns: The created transaction

returnBook(req, res)

Processes a book return.

• Accepts: { transactionId }
• Validates: Transaction must exist AND returnedAt must be null
• Updates: Transaction returnedAt to current date
• Updates: BookCopy status back to 'AVAILABLE'

getHistory(req, res)

Returns borrowing history.

• Role-aware: Students see only their own history; Admins/Librarians see all
• Populates: BookCopy → Book chain
• Sorts: By issuedAt descending (newest first)

getActive(req, res)

Returns all currently active (unreturned) loans system-wide.

• Filter: { returnedAt: null }
• Populates: User and BookCopy → Book

---

4. User Controller

File: userController.js

User account management operations.

Functions

listUsers(req, res)

Returns all users with passwordHash excluded.

createUser(req, res)

Creates a new user account.

• Accepts: { email, password, firstName, lastName, role, rollNumber, contactNumber }
• Hashes password with bcrypt (10 rounds)
• Returns: Created user (sans passwordHash)

getUser(req, res)

Returns a single user by ID (passwordHash excluded).

updateUser(req, res)

Updates user fields. If password is provided, it is hashed before saving.

• Destructures: { password, ...updateData } from req.body
• Conditional hashing: Only re-hashes if a new password was supplied

---

5. Fine Controller

File: fineController.js

Fine listing and payment processing.

Functions

listFines(req, res)

Returns fines based on role.

• Students: See only their own fines (userId filter)
• Admins/Librarians: See all fines
• Populates: userId and transactionId

payFine(req, res)

Marks a fine as PAID.

• Updates: Fine status to 'PAID' using findByIdAndUpdate

---

6. Dashboard Controller

File: dashboardController.js

Provides aggregate system statistics for the admin dashboard.

Functions

getStats(req, res)

Returns four key metrics: