How abhinavdogra21/lab-managment-system works
This repository is a Next.js 15 application that combines a role-based UI, a large REST-style backend under app/api, and a MySQL-backed workflow engine for lab bookings and equipment management.
1) High-level architecture
The system is organized around three main boundaries:
• Presentation layer: role-specific dashboard pages under app/
• Application/API layer: route handlers under app/api/
• Infrastructure/data layer: shared server utilities in lib/ plus MySQL and SMTP services
The app is not a generic CRUD dashboard. It is a workflow system where users move through different approval paths depending on role:
• student
• faculty
• lab-staff
• hod
• lab-coordinator
• admin
• others such as T&P or similar non-student categories
A generic dashboard at app/dashboard/page.tsx acts as a role redirector, while each role also has its own dashboard subtree.
2) Frontend/UI subsystem
The UI is built with:
• Next.js App Router
• React 18
• TypeScript
• Tailwind CSS
• Shadcn UI primitives in components/ui
Page structure
Each role has its own dashboard area:
• app/admin/dashboard
• app/faculty/dashboard
• app/hod/dashboard
• app/lab-staff/dashboard
• app/lab-coordinator/dashboard
• app/student/dashboard
• app/others/dashboard
These pages are mostly thin route-level screens. They rely on shared dashboard wrappers in:
• components/dashboard/dashboard-layout.tsx
• components/dashboard/dashboard-header.tsx
• components/dashboard/dashboard-sidebar.tsx
There is also shared auth UI:
• components/auth/login-form.tsx
And reporting UI:
• components/reports/report-generator.tsx
• app/admin/dashboard/reports/components/report-generator.tsx
UI boundary
Frontend pages do not directly talk to the database. They call the API routes in app/api/*, which centralizes business logic and permissions on the server side.
3) Backend/API subsystem
All backend behavior is implemented as Next.js route handlers in app/api/. These are grouped by domain and role.
Major API domains
• Authentication
- app/api/auth/*
- login, logout, forgot/reset password, session identity
• User profile
- app/api/user/*
- change password, update profile
• Admin
- app/api/admin/*
- manage users, departments, labs, reports, cleanup/migration operations
• Student
- app/api/student/*
- lab booking requests, component requests, bookings, loans, request history
• Faculty
- app/api/faculty/*
- booking approvals, faculty bookings, component requests, logs
• Lab staff
- app/api/lab-staff/*
- booking approvals, component issuance, inventory, loans, logs, timetable
• HOD
- app/api/hod/*
- department-level approvals, analytics, bookings, logs
• Lab coordinator
- app/api/lab-coordinator/*
- final approval flows and analytics
• Others
- app/api/others/*
- alternate booking/request flow for non-student users
• Public
- app/api/labs/*
- shared lab listing and booked slot data
• Cron/internal
- app/api/cron/*
- booking and loan reminder jobs
• Debug/maintenance
- app/api/debug/*
- troubleshooting routes
- plus admin utilities like cleanup, migration, and status repair endpoints
Architectural pattern in the API layer
Most business logic is centralized in route handlers rather than separate service classes. The route files perform:
• role checks
• request validation
• database reads/writes
• email notifications
• activity logging
• approval state transitions
That means the API layer is both the controller and the application service layer.
4) Shared server-side libraries
The lib/ directory contains the main reusable backend capabilities:
• lib/database.ts
- MySQL connection pool and query helpers
- core database access boundary
• lib/auth.ts
- session handling
- password hashing
• lib/roles.ts
- role/permission helpers
• lib/activity-logger.ts
- writes audit events into logging tables
• lib/notifications.ts
- email templates and notification orchestration
• lib/mailer.ts and lib/email.ts
- Nodemailer SMTP transport and send wrapper
• lib/report-generator.ts
- PDF/Excel export generation
• lib/utils.ts
- general helpers
Key architectural dependencies
The server layer depends on two external infrastructure services:
• MySQL 8 for all persistent state
• SMTP/Gmail for notifications and reminders
5) Data model and storage boundary
The repository is designed around a rich relational schema. The README describes 10 core tables, but the codebase also includes many extended/operational tables for workflows, logs, timetable management, reminders, attendance, and archives.
Core entities
• users: all identities and roles
• departments: departmental configuration and approval authority
• labs: lab metadata and ownership
• booking_requests: main lab booking workflow records
• multi_lab_approvals: per-lab approval tracking for multi-lab requests
• multi_lab_responsible_persons: assigns staff responsibility for each lab in a multi-lab request
• component_requests: equipment/component request workflow
• component_loans: active loan lifecycle
• components: inventory records
• system_logs: audit trail
Important relational pattern
The system is not built around a single flat booking table. Instead, it uses:
• one main request record
• separate approval/status fields per role
• additional tables for multi-lab approvals and staff assignment
• separate audit/log tables for traceability
This supports multi-step workflows and makes the approval chain visible in the database.
6) Core business workflows
A. Lab booking workflow
This is one of the primary flows and spans several roles.
1. A user submits a booking request from a role-specific UI.
2. The request is stored in booking_requests.
3. Faculty approval happens first for student-originated requests.
4. Lab staff review follows.
5. Final approval comes from HOD or lab coordinator, depending on department configuration.
6. Approved bookings are visible in role-specific booking views.
7. Cron jobs send reminders before the booking starts.
The API sequence is role-driven and split across:
• app/api/student/booking-requests
• app/api/faculty/requests/[id]/action
• app/api/lab-staff/requests/[id]/action
• app/api/hod/requests/[id]/action
• app/api/lab-coordinator/requests/[id]/action
B. Component request / loan workflow
This is the equipment borrowing path.
1. A student or faculty member requests a component.
2. The request is stored in component_requests.
3. Faculty review occurs first for student requests.
4. Lab staff recommend/approve.
5. HOD can provide final approval.
6. Lab staff issue the equipment, creating a loan record in component_loans.
7. Return, extension, and reminder actions update the loan lifecycle.
8. Automated reminders are sent for due or overdue items.
Key endpoints are in:
• app/api/student/component-requests
• app/api/faculty/component-requests
• app/api/lab-staff/component-requests
• app/api/hod/component-requests
• app/api/lab-staff/component-loans
C. Multi-lab booking
A booking can span multiple labs. This is a distinct architectural feature, not just a field on the booking form.
• booking_requests.lab_ids stores the lab set
• multi_lab_approvals tracks each lab’s decision separately
• multi_lab_responsible_persons assigns the right staff member per lab
This means final approval depends on all participating labs agreeing, which is a separate aggregation step in the backend.
7) Authentication, authorization, and route protection
The application uses:
• session-based auth in lib/auth.ts
• route protection through middleware.ts
• role-based access checks in API handlers and UI navigation
This creates a clear security boundary:
• public routes: landing, login, password recovery, public lab listing
• authenticated routes: dashboards and most API endpoints
• role-restricted routes: admin, faculty, student, etc.
The repo also supports password reset flows and profile maintenance through dedicated auth/user endpoints.
8) Notification and email subsystem
Email is a central part of the architecture rather than an afterthought.
Where email is used
• booking request submission
• approval/rejection notifications
• component issuance and returns
• password reset
• reminder cron jobs
• admin digests
Email implementation
• Nodemailer with SMTP configuration
• Testing mode redirects messages to ADMIN_EMAIL
• template generation lives in lib/notifications.ts
This creates a clean separation:
• route handlers decide *when* to notify
• lib/notifications.ts decides *what* the message says
• lib/email.ts / lib/mailer.ts handle delivery
9) Logging, auditing, and observability
The application records operational history in two ways:
• system_logs for broad audit logging
• additional domain-specific log tables for booking and component activity
The intent is traceability across:
• who requested what
• who approved or rejected
• who issued or returned equipment
• when state changes happened
This is important for diagramming because it acts as a side-effect path from nearly every workflow, not a standalone feature.
10) Operational and maintenance endpoints
There is a separate operational subsystem under admin and cron routes:
• cleanup dummy data
• database migration triggers
• fix multi-lab status inconsistencies
• purge inactive or archived students
• send digest emails
These routes suggest the system is actively maintained through application-level admin operations, not only through external scripts.
Supporting SQL scripts in scripts/ provide schema creation and data migrations.
11) Performance and runtime characteristics
The README and code layout indicate the system is optimized around heavy relational queries:
• MySQL connection pooling in lib/database.ts
• batch queries to avoid N+1 behavior
• cached public lab data
• parallelized reminder dispatch
• lazy SMTP initialization
These details matter architecturally because they show the backend is designed for high-volume dashboard reads and periodic notification workloads.
12) Supporting assets and tooling
Static and styling
• app/globals.css and styles/globals.css
• public/ for static files
Tooling and project support
• components.json for Shadcn UI configuration
• next.config.mjs for app/runtime tuning
• tsconfig.json for TypeScript
• package.json and pnpm-lock.yaml
• documentation in README.md, SETUP.md, design.md, working.md
Dev/debug support
• app/debug-api
• app/api/debug/*
• test pages such as app/test-booked-slots
13) How to think about the architecture diagram
A clear diagram for this repository should show:
• Users by role entering separate dashboard UIs
• UI pages calling role-specific API route handlers
• API handlers using shared lib/ services
• lib/ services writing to MySQL
• notification flows going out through SMTP/Gmail
• cron jobs triggering reminder workflows
• audit/log tables receiving side effects from most state changes
The most important architectural boundary is between:
• the role-based frontend dashboards
• the server-side route handlers
• the shared persistence/notification layer
The second key concept is the workflow engine: bookings and component requests are not simple CRUD objects, but multi-stage approval pipelines with role-specific transitions and multi-table state tracking.
Main entry points: page.tsx Role router · database.ts Database · notifications.ts Notifications · activity-logger.ts Activity logs
Components 25
Presentation
Role-based dashboards and public pages
- Landing · Entry and auth-facing routes
app/page.tsx - Role router · Redirects users to the right dashboard
app/dashboard/page.tsx - Student UI · Student booking and request workspace
app/student/dashboard/page.tsx - Faculty UI · Faculty approvals and requests workspace
app/faculty/dashboard/page.tsx - Lab staff UI · Operations, approvals, inventory, and loans
app/lab-staff/dashboard/page.tsx - HOD UI · Department-level approvals and analytics
app/hod/dashboard/page.tsx - Coordinator UI · Final approval and analytics workspace
app/lab-coordinator/dashboard/page.tsx - Admin UI · Administration, maintenance, and reporting
app/admin/dashboard/page.tsx - Others UI · Non-student booking and request workspace
app/others/dashboard/page.tsx
API
Next.js route handlers for workflow operations
- Auth API · Login, logout, session, and password reset
app/api/auth - Student API · Student bookings, component requests, and loans
app/api/student - Faculty API · Faculty approvals, logs, and component reviews
app/api/faculty - Lab staff API · Staff approvals, issue-return, inventory, and timetables
app/api/lab-staff - HOD API · Department approvals and analytics
app/api/hod - Coordinator API · Final approval and lab analytics
app/api/lab-coordinator - Admin API · User, lab, department, report, and maintenance endpoints
app/api/admin - Cron API · Reminder and repair jobs
app/api/cron
Shared server
Reusable backend utilities and app-wide UI
- Shared UI · Dashboard shell and auth/report components
components/dashboard/dashboard-layout.tsx - Auth + roles · Sessions, password hashing, and role checks
lib/auth.ts - Database · Connection pool and query helpers
lib/database.ts - Notifications · Templates and outbound notification flow
lib/notifications.ts - Activity logs · Writes workflow and system audit events
lib/activity-logger.ts - Report export · PDF and spreadsheet generation
lib/report-generator.ts
Infrastructure
External services and persistent storage
- SMTP mail · Outgoing email delivery
- MySQL · Persistent relational workflow store
Connections 45
- Landing → Auth API: login/reset · Public auth flows reach server handlers
- Role router → Student UI: route · Users are sent to role dashboards
- Role router → Faculty UI: route · Users are sent to role dashboards
- Role router → Lab staff UI: route · Users are sent to role dashboards
- Role router → HOD UI: route · Users are sent to role dashboards
- Role router → Coordinator UI: route · Users are sent to role dashboards
- Role router → Admin UI: route · Users are sent to role dashboards
- Role router → Others UI: route · Users are sent to role dashboards
- Student UI → Student API: requests · Student UI drives booking and component workflows
- Faculty UI → Faculty API: requests · Faculty UI drives approval and review flows
- Lab staff UI → Lab staff API: requests · Staff UI drives operational workflows
- HOD UI → HOD API: requests · HOD UI drives department approvals
- Coordinator UI → Coordinator API: requests · Coordinator UI drives final approval flows
- Admin UI → Admin API: requests · Admin UI drives management and maintenance
- Others UI → Auth API: session · Authenticated access is mediated by auth routes
- Student API → Auth + roles: authz · Role and session checks are centralized
- Faculty API → Auth + roles: authz · Role and session checks are centralized
- Lab staff API → Auth + roles: authz · Role and session checks are centralized
- HOD API → Auth + roles: authz · Role and session checks are centralized
- Coordinator API → Auth + roles: authz · Role and session checks are centralized
- Admin API → Auth + roles: authz · Role and session checks are centralized
- Student API → Database: reads/writes · Workflow state is persisted in MySQL
- Faculty API → Database: reads/writes · Workflow state is persisted in MySQL
- Lab staff API → Database: reads/writes · Workflow state is persisted in MySQL
- HOD API → Database: reads/writes · Workflow state is persisted in MySQL
- Coordinator API → Database: reads/writes · Workflow state is persisted in MySQL
- Admin API → Database: reads/writes · Workflow state is persisted in MySQL
- Cron API → Database: scheduled reads/writes · Reminder and repair jobs touch persistent state
- Student API → Notifications: emails · Requests and reminders trigger notifications
- Faculty API → Notifications: emails · Approvals and updates trigger notifications
- Lab staff API → Notifications: emails · Issue-return and reminders trigger notifications
- HOD API → Notifications: emails · Approval events trigger notifications
- Coordinator API → Notifications: emails · Final decisions trigger notifications
- Admin API → Notifications: emails · Admin digests and password flows trigger notifications
- Notifications → SMTP mail: deliver · SMTP handles outbound email delivery
- Activity logs → Database: audit writes · Audit events are stored in MySQL tables
- Student API → Activity logs: audit · Workflow actions are logged
- Faculty API → Activity logs: audit · Workflow actions are logged
- Lab staff API → Activity logs: audit · Workflow actions are logged
- HOD API → Activity logs: audit · Workflow actions are logged
- Coordinator API → Activity logs: audit · Workflow actions are logged
- Admin API → Activity logs: audit · Maintenance and management actions are logged
- Admin API → Report export: exports · Reports are generated for admin use
- Shared UI → Auth + roles: uses · Shared UI relies on auth/session state
- Shared UI → Report export: uses · Report components use export generation