Loan Management System (LMS)

A Next.js web application for managing NUSC Logistics inventory, loan requests, and users. Built with the App Router, Prisma ORM, and PostgreSQL.

Architecture & Schema

The LMS follows a Next.js App Router architecture with:

• Frontend: React components, ShadCN UI primitives, server and client components
• Backend: Server Actions (src/lib/actions/), Prisma ORM for data access
• Database: PostgreSQL with schema defined in prisma/schema.prisma

Core domain model (see PLAN_GUIDE.md for workflow details):

Entity	Purpose
User	Unified user model with roles: REQUESTER, IH, LOGS, ADMIN
IH (Inventory Holder)	Owner/custodian of items; can be INDIVIDUAL or GROUP
IHMember	Links users to IHs; supports multiple POCs per group
Item	Physical inventory items with quantity, storage location, and IH
Sloc	Storage locations (e.g. store rooms)
LoanRequest	Loan header: requester, loggie, dates, status
LoanItemDetail	Line items per loan: item, quantity, per-item status

For full architecture details, see DESIGN_GUIDE.md. For schema and migrations, see DB_GUIDE.md.

---

Setup Guide

1. Prerequisites

• Node.js: Download here
• Docker: Download here
• Git: Download here

2. Clone the Repository

In you terminal:

git clone https://github.com/usdevs/lms.git
cd lms

3. Install Dependencies

npm install

This will also run prisma generate automatically via the postinstall script.

4. Database Setup

The app uses PostgreSQL with Prisma as the ORM.

For local dev, we will run the Postgres locally with Docker using the provided docker-compose.yaml

From the project root:

docker compose up -d

This starts a Postgres 17 container with:

• Host port: 5432
• User: postgres
• Password: postgres123
• Database: lms_dev

4.2. Configure Environment Variables

Create a .env file in the project root (if it doesn’t exist yet) and define the Prisma connection URLs.

At minimum, you should have:

DATABASE_URL="postgresql://postgres:postgres123@localhost:5432/lms_dev?schema=public"
DIRECT_URL="postgresql://postgres:postgres123@localhost:5432/lms_dev?schema=public"

• DATABASE_URL: Used by Prisma Client at runtime
• DIRECT_URL: Used by Prisma Migrate to apply migrations directly

If you are not using Docker, adjust the host, port, user, password, and database to match your own Postgres instance.

5. Run Prisma Migrations

Once the database is running and .env is configured:

npx prisma migrate dev --name init

This will:

• Create the database schema defined in here
• Apply all migrations to your Postgres instance
• Regenerate the Prisma Client

For more detail on migration workflows, see here

6. Seed Data (Optional)

To seed the database with test data as defined in prisma/seed.ts,

npx prisma db seed

7. Run the App in Development

Start the Next.js dev server:

npm run dev

Then open http://localhost:3000 in your browser.

8. Troubleshooting

• Database connection errors

  • Ensure Docker is running (if using Docker)
  • Check that DATABASE_URL and DIRECT_URL in .env are correct
  • Confirm Postgres is listening on the expected host/port

• Prisma migration issues

  • See DB GUIDE.md for detailed instructions on migrations and common errors

9. Others

For more information on the design, read here

For more information on the functionality plans, read here