Frontend Architecture
High-level overview of the Next.js App Router frontend — directory structure, Edge middleware, design patterns, and technology stack.
Frontend Architecture
The SLMS frontend is a modern, responsive web application built with Next.js 15, React 19, TypeScript, and Tailwind CSS, using the App Router paradigm.
Technology Stack
| Technology | Purpose |
|---|---|
| Next.js 15 (App Router) | File-based routing, server components, edge middleware |
| NextAuth.js (Auth.js v5) | Session management and JWT handling |
| React 19 | Component-based UI library |
| Zustand | Global state management (Loaders, Banners) |
| Tailwind CSS 4 | Utility-first styling |
| Shadcn UI + Radix | Pre-built accessible component primitives |
| Axios | HTTP client with automatic interceptors |
| Sonner | Toast notification system |
| React Hook Form + Zod | Form handling and validation |
Directory Structure
frontend/src/
├── app/ # Next.js App Router (pages & layouts)
│ ├── layout.tsx # Root layout — global providers (Session, Theme)
│ ├── page.tsx # Landing page
│ ├── globals.css # Tailwind config, CSS variables
│ │
│ ├── (auth)/ # Auth route group (no URL segment)
│ │ ├── layout.tsx # Centered auth layout
│ │ ├── login/page.tsx # Login form
│ │ ├── register/page.tsx # Registration form
│ │ └── forgot-password/page.tsx
│ │
│ ├── admin/ # Admin portal (10 pages)
│ ├── librarian/ # Librarian portal (6 pages)
│ ├── student/ # Student portal (7 pages)
│ └── staff/ # Staff/Faculty portal (6 pages)
│
├── middleware.ts # Edge middleware (RBAC routing enforcement)
├── auth.ts # NextAuth configuration and providers
├── auth.config.ts # NextAuth edge-compatible config
│
├── components/ # Reusable UI components
│ ├── feedback/ # Error Boundary, Confirm Dialog
│ ├── ui/ # Shadcn UI primitives (Skeleton, FormField, etc.)
│ └── theme-provider.tsx
│
├── constants/ # Static definitions
│ └── errorCodes.ts # Error Code Registry (UI mapping for errors)
│
├── hooks/ # Custom React hooks
│ └── useOfflineDetection.ts # Detects network connectivity
│
├── lib/ # Utility libraries
│ ├── api.ts # NextAuth-aware API client
│ └── utils.ts # Tailwind cn() utility
│
├── services/ # Business logic and external communication
│ ├── api/client.ts # Enterprise API client (Interceptors)
│ └── notification.service.ts # Notification Manager (Toasts/Banners)
│
└── stores/ # Zustand state management
├── useBannerStore.ts # Global alert banner state
└── useLoadingStore.ts # Request-level loading statesKey Design Patterns
1. Edge Middleware RBAC
Role-based access control is enforced at the Edge using Next.js Middleware (src/middleware.ts). Before a page even renders, the middleware intercepts the request, reads the NextAuth session, and ensures the user has the correct role for the URL namespace (e.g., /admin/*).
2. Centralized Feedback Loop
Instead of parsing arbitrary string errors from the backend, the frontend intercepts responses centrally via Axios (services/api/client.ts), maps the backend code to a predefined UI object via the Error Code Registry, and dispatches it through the Notification Manager.
3. Automatic Token Rotation
The frontend manages token expiration transparently. If an API request returns 401 Unauthorized, the Axios interceptor pauses all outgoing requests, attempts to refresh the token via NextAuth, and then replays the queued requests.
4. Headless Form Validation
Forms are built with react-hook-form and validated using zod schemas. The <FormField> component automatically wires up error states, ARIA attributes, and accessible labels.
5. Skeleton Loading
To prevent Layout Shift and improve perceived performance, pages display pre-configured <Skeleton> layouts (Tables, Cards, Forms) while client-side requests fetch data.