01 — Product Overview (Library Module)

• 1. Purpose
• 2. Business goals
• 3. User goals
• 4. Stakeholders
• 5. Why this exists
• 6. Dependencies
• 7. Success metrics
• 8. Edge cases (contract level)
• 9. Assumptions (module)
• 10. Open questions (module-grain; global ledger in 00-shared/12)
• 11. Glossary (this module)

StudyLyon — multi-tenant ERP / School Management API. This package designs the Library module client (Flutter, forward-looking spec) against the implemented NestJS backend. All endpoints, DTO fields, schemas, domain events, permissions, and wire contracts are derived directly from src/modules/library/**, src/modules/rbac/permissions.constants.ts, and docs/IMPLEMENTATION_PLAN.md. No feature is invented — anything not present in source is flagged (planned) / (proposed) / (forward-looking) in Assumptions & Open Questions.

Heads-up: per the PRD, the mobile client is out of Phase 1; this package is the forward-looking spec the client will be built against later. Everything below is best-effort UI design on top of the current backend surface.

Blueprint note: studylyon-blueprint/04-Modules/ has no dedicated Library doc; the module is only sketched as "Books / Issue / Return / Fines" responsibilities (MODULE_ARCHITECTURE.md:546-557) and appears in the fee-category list (COLLECTIONS.md:2247). The code is the source of truth.

1. Purpose

Library manages the school's physical book collection and the borrow lifecycle:

• Catalog: books with title/author/ISBN, optional publisher/category/edition, copy counts (totalCopies/availableCopies), and a status (available|borrowed|damaged|lost).
• Issue/return: staff hand a copy to a student with an explicit due date; returning closes the record, restores availability, and computes a fine when late.
• Fines: computed server-side at return time at a fixed daily rate, tracked as fineStatus (pending|paid|waived), payable via a dedicated endpoint.
• Borrow visibility: full history and active-borrow lists per student.

2. Business goals

3. User goals

• Librarian / staff: search the catalog; add, edit, delete books; issue and return copies; see overdue borrowers; collect fine payments.
• Student: browse/search the catalog; see which books are currently on loan to them and their history; know what's overdue.
• Parent: (read-only, via student) see the child's active loans and any fine.
• Org admin: catalog oversight, permission assignment (who may issue/return), configuration of limits (planned).

4. Stakeholders

Librarian/staff with books.* permissions, org admin (RBAC), students, parents, the RBAC module (permissions.constants.ts), events/notifications pipeline, QA + design + engineering.

5. Why this exists

A school library without tracking loses books and revenue. The backend enforces the hard invariants (ISBN uniqueness, availability, 5-book cap, tenant isolation, soft delete). The client's job is to present the catalog and loan state authoritatively, never guess server state, and treat every write (create, issue, return, fine pay) as server-confirmed.

6. Dependencies

7. Success metrics

• Catalog search (title/author/ISBN) round-trip < 2 s (regex search, indexed title/author).
• Duplicate-ISBN attempt handled as 409 100% of the time.
• Issue of an exhausted book always blocked (409), even under concurrent requests (see QA-1 in 14_QA_Checklist.md — read-then-write race today).
• Fine amount at return always equals ceil(daysOverdue) × 5 unless staff overrides.
• Zero cross-tenant leaks (BaseRepository scope).

8. Edge cases (contract level)

• Duplicate ISBN → 409 DUPLICATE_RESOURCE "Book with ISBN "..." already exists." (library.service.ts:37-39).
• No copies available → 409 "No copies available for borrowing." (library.service.ts:109-111).
• Student at 5 active loans → 409 "Student already has maximum number of borrowed books." (library.service.ts:116-120).
• Delete book with active loans → 409 "Cannot delete book with active borrow records." (library.service.ts:99-101); delete is a soft delete (book.repository.ts via BaseRepository.softDelete, library.service.ts:103).
• Return a non-active record → 409 "Book was not actively borrowed." (library.service.ts:155-157).
• Unknown book/record → 404 RESOURCE_NOT_FOUND (library.service.ts:80,92,103,154,170,207).
• Invalid Mongo id → CastError → 400 VALIDATION_ERROR "Invalid resource identifier." (http-exception.filter.ts).
• Copy-count edits adjust availableCopies by the same delta, floored at 0 (library.service.ts:87-90).
• Staff override fine — return DTO may set fineAmount explicitly (return-book.dto.ts:9-13); server uses dto.fineAmount ?? calculateFine(dueDate) (library.service.ts:159).
• fineStatus on time — records with fineAmount = 0 keep fineStatus: undefined (library.service.ts:166); WAIVED is never produced by any endpoint.

9. Assumptions (module)

• PRD: mobile client out of Phase 1 — forward-looking spec; backend remains the contracts authority.
• Endpoints are guarded only by JwtAuthGuard (library.controller.ts:22) — no @Permissions() metadata anywhere; books.read/create/update/delete/issue/return and fines.pay exist in ALL_PERMISSIONS (permissions.constants.ts:55-61) but are not enforced. Real RBAC is (planned) (OQ-1).
• Overdue is not computed by the server. BorrowStatus.OVERDUE and repository findOverdue() exist (borrow-record.schema.ts:9-11, borrow-record.repository.ts:34-43) but no service endpoint/worker sets it. Overdue detection is client-derived today; a scheduled scan is (planned) (IMPLEMENTATION_PLAN.md:228) (OQ-2).
• issuedBy is never populated — the schema has the field (borrow-record.schema.ts:28-29) but issueBook doesn't set it (library.service.ts:132-139) (OQ-3).
• Fines are units (plain Number, library.service.ts:25 rate = 5); no currency/format contract server-side.
• BookStatus.DAMAGED/LOST and BorrowStatus.LOST exist in enums but no endpoint transitions to them — damage/loss workflow (planned) (OQ-4).
• No pagination on borrow endpoints (library.service.ts:195-201) — client paging (proposed).
• Search covers title/author/ISBN only (book.repository.ts:26-30); category/ publisher/status filters must be client-side (OQ-5).
• Catalog import/export is (planned) (IMPLEMENTATION_PLAN.md:172,228); QR/barcode scanning is (forward-looking); analytics (proposed).

10. Open questions (module-grain; global ledger in 00-shared/12)

11. Glossary (this module)