Library

The library module manages books, active lendings, reservation waitlists, and history at /libraries. Loan period, fine rates, and auto-fulfill settings live in school library configuration (/settings/library). Students browse and request books from /my-library when self-request is enabled.

Set the circulation policy before the first book leaves the desk. Loan period, fine rate, grace days, the per-student loan cap and the reservation hold length are school-wide values read at the moment a loan is created or returned, so editing them later does not re-price loans that are already open. A school that opens on the defaults lends for 14 days, charges 5 rupees for each overdue day with no grace period, caps students at 3 concurrent loans, and holds a reservation for 3 days before it expires.

Tabs on the library desk

• Desk - search the catalog and issue or place a hold in a single action.
• Books - catalog rows with category and stock filters.
• Lendings - everything currently issued or overdue.
• Reservations - the waitlist, showing queue rank with fulfil and cancel.
• History - closed lendings, including returned, lost, and damaged outcomes.
• Analytics - stock and circulation counts served by /api/library/analytics.

Who owns it

Rules the desk enforces

• Issue is refused when the book is inactive, when no copy is available, when the borrower account is inactive, or when that borrower already holds an active lending for the same title.
• A reservation does not take a copy off the shelf. It records a hold whose expiry comes from the reservation hold days setting, and the reservations tab shows queue position.
• Fulfilling a hold converts it into an issued loan and decrements available copies; cancelling removes the waitlist row and leaves stock untouched.
• On return, the post-return step looks for the oldest waiting hold. With auto-fulfil on it issues that hold straight away; with auto-fulfil off it notifies the next borrower that a copy is ready to collect.
• Marking a copy lost reduces total copies and does not add anything back to available stock. Marking it damaged leaves both counts alone and flags the physical copy.
• Student self-request is refused once the borrower already has as many active loans as maxBooksPerStudent allows. When every copy is out, the request is queued and the reply carries the waitlist position.

Fines and the handoff to fees

• The overdue fine is whole days late beyond the grace period multiplied by the per-day rate. An on-time or early return costs nothing.
• A lost book is charged the greater of the accrued overdue amount and the lost replacement value. A damaged book is charged the overdue amount plus the damaged fine.
• For a student borrower, any fine above zero creates a one-time fee instance under fee type code LIB_FINE with a due date 14 days out. The fee type and its structure are created on first use, so no fee setup is needed in advance.
• The fee instance carries a bookLendingId marker in its notes, so repeating a return cannot charge the same lending twice.
• The fine reaches finance as an ordinary pending fee instance for the active academic year. If no academic year is active, no fee instance is written and the fine stays only on the lending record.

Scheduled jobs

• POST /api/library/cron/reminders promotes issued loans past their due date to OVERDUE, sends a reminder to borrowers inside the reminder window, and sends an overdue alert to everyone past due.
• POST /api/library/cron/expire-reservations moves holds past their expiry to EXPIRED and releases the reserved copy back to available.
• Both accept the x-fees-cron-secret header used by the rest of the daily ops cron.

Limits

• There is no renew action. Extending a loan means returning the copy and issuing it again, which restarts the loan period.
• The per-student loan cap is applied only to student self-request. A librarian issuing at the desk is not blocked by it.
• Fines are recorded against the borrower. There is no way to waive a library fine from the library screens - open the fee instance in the fees module instead.