Library Management System

HCLib - Full-stack Library Management System

Loan management · Rich catalog relations · Staff access control

Role: Solo developer across frontend and backend. I designed the architecture and implemented the circulation, catalog, and authentication flows end to end.

Next.js 15 · React 19 · TypeScript · NestJS 11 · TypeORM · PostgreSQL · Redis · Docker Compose

HCLib is a library operations system built for day-to-day staff workflows. The hardest part was keeping loan state, inventory updates, and catalog data consistent while still making the admin UI fast enough to use at the desk.

System Architecture

flowchart LR
    U[Staff User] --> M[Next.js Middleware]
    M --> F[Feature Modules / Forms / Tables]
    F --> A[Axios Client + Refresh Logic]
    A --> B[NestJS API]
    B --> D[Domain Services]
    D --> P[(PostgreSQL)]
    D --> R[(Redis)]
    D --> S[Storage / Image Pipeline]
    D --> J[Scheduled Jobs]

The frontend is organized feature-first so staff workflows remain easy to iterate. The backend is domain-centric so transaction boundaries, validation, and state transitions stay inside the correct service layer.

Loan Lifecycle Management

Problem: Real library circulation is not a single record with a due date. Each loan can include multiple copies, each copy has its own condition and return flow, and invalid transitions can quickly corrupt inventory.

Solution: Treat circulation as a domain workflow instead of a simple CRUD form.

Implementation highlights:

• One loan form handles member selection, staff selection, multiple copies, due date, and loan conditions
• Validation errors from nested array fields are mapped back into the matching React Hook Form path
• Loan creation runs inside a transaction and atomically updates copy state from AVAILABLE to BORROWED
• Return flows support damaged books, fines, renewals, and separate item-level transitions

Result: The system prevents double-loans, invalid returns, and broken inventory counts while still keeping the desk-side UI fast enough for operators.

sequenceDiagram
    participant Staff as Staff UI
    participant LoanUI as Loan Form / Modal
    participant LoanAPI as Loan API
    participant LoanService as LoanService
    participant LoanItemService as LoanItemService
    participant Inventory as BookCopy / Book Stats
    participant FineAPI as Fine API

    Staff->>LoanUI: Select member, staff, copies, due date
    LoanUI->>LoanAPI: POST /loans
    LoanAPI->>LoanService: create()
    LoanService->>LoanItemService: insertMultiple()
    LoanItemService->>Inventory: Atomic update AVAILABLE -> BORROWED
    Inventory-->>LoanItemService: OK / fail if race condition
    LoanItemService-->>LoanService: Loan items created
    LoanService-->>LoanUI: Loan created

    Staff->>LoanUI: Return damaged copy
    LoanUI->>FineAPI: POST /fines
    FineAPI-->>LoanUI: Fine created
    LoanUI->>LoanAPI: PATCH /loan-items/:id/return
    LoanAPI->>LoanItemService: returnItem()
    LoanItemService->>Inventory: Restore copy status + sync stats
    LoanItemService-->>LoanUI: Item returned

Catalog Management with Complex Relations

Problem: Adding a book requires much more than inserting one database row. A valid catalog record needs publisher data, multiple authors with role/order, categories, cover uploads, and uniqueness checks such as ISBN.

Solution: Build catalog creation as a composed workflow: upload first, validate relations inside a transaction, then persist book and relation tables together.

Implementation highlights:

• A multi-block form separates basic data, metadata, relations, and cover upload
• Author selection supports debounced search, multi-select, role assignment, and ordering
• Cover upload happens before submit so the book endpoint stays focused on business validation
• Backend services validate ISBN uniqueness and relation existence inside one transaction

Result: The form stays usable even though the domain is dense, and the backend remains strict about consistency.

sequenceDiagram
    participant Editor as Staff UI
    participant CatalogUI as Book Form
    participant FileAPI as File API
    participant Storage as Storage Service
    participant BookAPI as Book API
    participant BookService as BookService
    participant Relations as Author/Category/Publisher Checks

    Editor->>CatalogUI: Enter metadata + select relations
    Editor->>FileAPI: Upload cover image
    FileAPI->>Storage: Convert + store image
    Storage-->>CatalogUI: cover_id
    CatalogUI->>BookAPI: POST /book with cover_id + author_infos + category_ids
    BookAPI->>BookService: create()
    BookService->>Relations: Validate ISBN + relations + cover
    Relations-->>BookService: Validation OK
    BookService-->>BookAPI: Save Book + BookAuthor + BookCategory
    BookAPI-->>CatalogUI: Created book

CI/CD & Deploy

• Frontend build, backend Jest, and container health checks are part of the pipeline
• docker-compose is used for local development and image-based production deploys
• The deployment topology keeps the frontend app and backend API isolated behind a reverse proxy