📚 ScholarStack LMS

A professional, full-stack College Library Management System equipped with secure, role-based access control (RBAC), live transaction monitoring, dynamic fine logging, and automated background tasks.

Built with a fast React 19, TypeScript, & Tailwind CSS client-side dashboard mated to a sturdy Node.js, Express, & Better-SQLite3 server engine.

---

🚀 Key Features

• Role-Based Access Control (RBAC): Customized dashboards and actions tailored for three distinct roles:
  • Librarian (Admin): Complete system access. Oversees staff management, fine configurations, and global statistics.
  • Staff (Library Assistant): Manages book catalogs, member registrations, transaction issuance, returns, and payment collection.
  • Student: Visualizes catalog, monitors borrow history, views overdue fines, and requests renewal extensions directly.
• Inventory & Member Directories: Complete CRUD handlers for books, locations, categories (ISBN, Publisher, Genre), and student library cards.
• Automated Ticketing & Transaction Engine: Seamlessly issues copies, facilitates returns, processes renewals, and automates check-ins.
• Dynamic Overdue & Fine Engine: Automated background checking updates transactional statuses and calculates accrued fines hourly based on customizable daily rates. Includes secure payment logging and dynamic receipt retrievals.
• Elegant Data Visualizations: Real-time data breakdowns, bar charts of borrowing activities, and pie charts of book statuses powered by Recharts and D3.js.
• Modern Aesthetic Design: Ambient modern visual look, designed with generous negative space, high-contrast layouts, smooth motion/react dynamic animations, and micro-hover states.

---

🛠️ Stack & Architecture

• Frontend SPA: React 19, Vite 6, Tailwind CSS 4, Lucide React (for icons), Recharts & D3 (for data visualizations), and Motion (for fluent animations).
• Secure Backend: Node.js, Express, and ESM-to-CJS compilation via Esbuild.
• Engine & Persistence: SQLite (via better-sqlite3) for robust, local, transaction-safe relational storage.
• Production Pipeline: Prepared with pre-configured self-contained production scripts launching via CJS bindings.

---

📂 Database Schema

ScholarStack leverages an optimized relational structure inside SQLite:

            ┌──────────────────┐
            │      users       │  (Librarians & Staff)
            └────────┬─────────┘
                     │ (librarianId)
                     ▼
            ┌──────────────────┐
            │  fine_payments   │
            └────────▲─────────┘
                     │ (transactionId)
                     │
┌──────────────────┐ │ ┌──────────────────┐
│      books       │─┼─►│   transactions   │
└──────────────────┘   └────────▲─────────┘
  (bookId)                      │
                                │ (memberId)
                       ┌────────┴─────────┐
                       │     members      │  (Students)
                       └──────────────────┘

1. users: Manages credential records, internal profiles, and student linkage cards.
2. books: Tracks specific title attributes, physical shelf coordinates, volumes configured, and active pool availability.
3. members: Holds standard academic program profiles, departments, emails, and student IDs.
4. transactions: Controls active loans, target due dates, return timestamps, and outstanding fines.
5. fine_payments: Relates transactions to paid financial receipts and recording staff.
6. settings: Manages operational key-values such as daily_fine_rate.

---

🔌 API Documentation

Endpoint	Method	Role Allowed	Description
/api/login	POST	Public	Authenticates users and establishes session payloads
/api/books	GET	All Roles	Returns complete searchable book inventory
/api/books	POST	LIBRARIAN, STAFF	Adds a new book volume to catalog listings
/api/books/:id	PUT	LIBRARIAN, STAFF	Updates metadata, locations, or stock balances
/api/books/:id	DELETE	LIBRARIAN, STAFF	Evicts book entry permanently
/api/staff	GET	LIBRARIAN	Retrieves list of assistant profile entities
/api/staff	POST	LIBRARIAN	Onboards a new staff assistant
/api/staff/:id	DELETE	LIBRARIAN	Revokes staff accesses and profiles
/api/members	GET	LIBRARIAN, STAFF	Lists all registered student members
/api/members	POST	LIBRARIAN, STAFF	Registers a student library profile
/api/transactions	GET	All Roles	Returns borrow lists (Student restricts to self)
/api/issue	POST	LIBRARIAN, STAFF	Dispatches checking slips out
/api/return	POST	LIBRARIAN, STAFF	Checks in returned volumes
/api/renew-request	POST	STUDENT	Submits student renewal requests
/api/renew-approve	POST	LIBRARIAN, STAFF	Grants extension approvals (+7 days due-window)
/api/check-overdue	GET	All Roles	Force triggers overdue updates and manual recalculations
/api/fines/stats	GET	LIBRARIAN, STAFF	Aggregates collection vs outstanding balances
/api/fines/pay	POST	LIBRARIAN, STAFF	Processes payments and clears ledger logs
/api/fines/receipt/:id	GET	All Roles	Fetches fully formatted operational receipts
/api/settings	GET / POST	LIBRARIAN	Queries and updates system variables (e.g. daily rates)

---

🏃 Setup & Installation

Follow these steps to run the application locally:

1. Prerequisites

Ensure you have Node.js (v18 or higher) and npm installed on your system.

2. Clone and Install Dependencies

git clone https://github.com/your-username/scholarstack-lms.git
cd scholarstack-lms
npm install

3. Environment Setup

Configure your environment variables by replicating .env.example:

cp .env.example .env

(Add your optional GEMINI_API_KEY or APP_URL secrets to your config if necessary.)

4. Development Run

Boot the fully localized front and back-end integration in hot reload development mode:

npm run dev

Open your browser and navigate to http://localhost:3000.

5. Production Compiles

Build and pack both client assets and backend server assets:

npm run build
npm start

This bundles the backend into optimized CommonJS files in dist/server.cjs via esbuild, preventing Node path resolution errors and ensuring fast cold-start metrics.

---

🔐 Demo Credentials

Use any of these embedded demo credentials to inspect the application dashboards:

• Admin Dashboard (Head Librarian)
  • Username: admin
  • Password: admin123
• Assistant Dashboard (Library Staff)
  • Username: staff
  • Password: staff123
• Student Dashboard (Member view)
  • Username: student
  • Password: student123

---

⚖️ License

Distributed under the MIT License. Feel free to use, modify, and distribute this software for educational or enterprise applications.