134 lines
7.1 KiB
Markdown
134 lines
7.1 KiB
Markdown
# Learner Management System Frontend
|
|
|
|
This is the frontend for a modular and responsive Learner Management System (LMS), built with Vanilla Typescript, Vite, and Bootstrap v5.3. It utilizes a widget-based system and interacts with a dedicated backend server via a RESTful API using PAKE SRP for authentication.
|
|
|
|
## Features
|
|
|
|
* **Modular Architecture:** Organized into distinct modules (widgets, layouts, pages, API) for maintainability and scalability.
|
|
* **Responsive Design:** Uses Bootstrap 5.3 for a consistent experience across desktops, tablets, and mobiles.
|
|
* **Widget System:** Extensible widgets with `default` (full-width) and `icon` (sidebar) sizes.
|
|
* **API Integration:** Connects to a live backend API (default: `http://localhost:8080/api`) for data fetching and actions.
|
|
* **Secure Authentication:** Implements Password-Authenticated Key Exchange (PAKE SRP) for secure login via the `thin-srp` library.
|
|
* **Token-Based Sessions:** Manages user sessions using tokens obtained from the backend upon successful login (stored in localStorage by default).
|
|
* **Layout Modules:** Provides pre-built layouts: `CenteredLayout`, `ThreeColumnLayout`, `SplitColumnLayout`.
|
|
* **Core Pages:** Includes pages for Login, Register (info only), Dashboard, Profile, Account Settings (Modal), Admin Dashboard, Manage Students.
|
|
* **Topbar Module:** Features main navigation and a user profile dropdown with account actions.
|
|
* **Modal Module:** Provides a reusable container for modal dialogs (e.g., Account Settings, notifications).
|
|
|
|
## Technologies Used
|
|
|
|
* **Vanilla Typescript:** For a robust, type-safe, and maintainable codebase without framework overhead.
|
|
* **Vite:** For an extremely fast development server and optimized build process.
|
|
* **Bootstrap v5.3:** For responsive layout, styling components, and utility classes.
|
|
* **pnpm:** Efficient package manager for dependency management.
|
|
* **thin-srp:** JavaScript client library for Secure Remote Password (SRP) protocol implementation.
|
|
|
|
## Prerequisites
|
|
|
|
* **Node.js** (>= 18 recommended)
|
|
* **pnpm** (Install globally: `npm install -g pnpm`)
|
|
* **Running Backend:** The LMS backend service must be running (see backend README) and accessible (defaults to `http://localhost:8080`).
|
|
|
|
## Installation and Setup
|
|
|
|
1. **Clone the repository:**
|
|
|
|
```bash
|
|
git clone <your-frontend-repository-url>
|
|
cd lms-frontend
|
|
```
|
|
|
|
2. **Install dependencies using pnpm:**
|
|
|
|
```bash
|
|
pnpm install
|
|
```
|
|
|
|
3. **Configure API Base URL (Optional):**
|
|
* If your backend runs on a different address or port, update the `API_BASE_URL` constant in `src/api/api.ts`.
|
|
|
|
4. **Start the development server:**
|
|
|
|
```bash
|
|
pnpm dev
|
|
```
|
|
|
|
This will start the Vite development server. Open your browser and navigate to the address provided (usually `http://localhost:5173`).
|
|
|
|
## Project Structure
|
|
|
|
```bash
|
|
lms-frontend/
|
|
├── index.html # Main HTML entry point
|
|
├── package.json # Project dependencies and scripts
|
|
├── pnpm-lock.yaml # pnpm lock file
|
|
├── public/ # Static assets served directly
|
|
├── README.md # This README file
|
|
├── src/ # Source code directory
|
|
│ ├── api/
|
|
│ │ └── api.ts # Functions for interacting with the backend API (SRP, data fetching)
|
|
│ ├── assets/ # Static assets processed by Vite (images, icons)
|
|
│ ├── components/
|
|
│ │ ├── layouts/ # Page layout components
|
|
│ │ ├── modules/ # Larger UI modules (TopbarModule, ModalModule)
|
|
│ │ └── widgets/ # Reusable UI widgets
|
|
│ ├── main.ts # Application entry point, initializes router/app state
|
|
│ ├── pages/ # Page-level components/logic
|
|
│ ├── styles/
|
|
│ │ └── index.css # Global styles, Bootstrap import
|
|
│ ├── types/ # TypeScript interfaces and type definitions
|
|
│ ├── utils/
|
|
│ │ └── utils.ts # Utility functions (auth state management, storage)
|
|
│ └── vite-env.d.ts # Vite environment type declarations
|
|
├── tsconfig.json # TypeScript configuration
|
|
├── tsconfig.node.json # TypeScript configuration for Node contexts (e.g., Vite config)
|
|
└── vite.config.ts # Vite build tool configuration
|
|
```
|
|
|
|
## Widget System
|
|
|
|
The UI is composed of reusable widgets found in `src/components/widgets/`. Each widget encapsulates specific functionality or displays data. They support different sizes (`default`, `icon`) for adaptability within various layouts.
|
|
|
|
## API System
|
|
|
|
Defined in `src/api/api.ts`, this module handles all communication with the backend API.
|
|
|
|
* **Live Interaction:** Functions use `fetch` to make requests to the running backend (default: `http://localhost:8080/api`).
|
|
* **SRP Flow:** The `login` function implements the two-step SRP authentication handshake with the backend.
|
|
* **Authenticated Requests:** Other API functions automatically include the stored authentication token in the `Authorization: Bearer <token>` header for protected endpoints.
|
|
* **Error Handling:** Includes basic error handling and detection of unauthorized (401) responses.
|
|
* **Key Endpoints Used:**
|
|
* `POST /api/auth/srp/start`
|
|
* `POST /api/auth/srp/verify`
|
|
* `POST /api/auth/logout`
|
|
* `GET /api/profile/{user_id}`
|
|
* `PUT /api/profile/settings`
|
|
* `GET /api/admin/dashboard`
|
|
* `GET /api/admin/students`
|
|
* `GET /api/admin/students/{student_id}/financials`
|
|
|
|
## Backend Interaction Notes
|
|
|
|
* **Authentication:** The backend handles the secure verification of passwords using SRP. The frontend never stores or hashes the raw password itself after the initial SRP calculation during login.
|
|
* **Authorization:** Access to specific API endpoints (e.g., admin routes) is controlled by the backend based on the user's role/permissions associated with their session token.
|
|
* **Data Source:** All dynamic data (user info, student lists, etc.) is fetched from the backend, which interacts with the MariaDB database.
|
|
|
|
## Further Development
|
|
|
|
* **Complete Widget Functionality:** Ensure all widgets fetch and display real data from the backend API.
|
|
* **Admin Page Enhancements:** Implement full CRUD operations for student/teacher management, filtering, batch actions, and enrollment assignments.
|
|
* **Student Table Widget:** Integrate a robust table library (e.g., Tabulator, TanStack Table) for improved sorting, filtering, and pagination.
|
|
* **Classrooms Module:** Build out the Classrooms feature beyond the placeholder modal.
|
|
* **Robust Error Handling:** Implement more comprehensive error handling and user feedback mechanisms throughout the UI.
|
|
* **Client-Side Validation:** Add more input validation for forms (e.g., account settings).
|
|
* **UI/UX Polish:** Refine styling, transitions, and interactions for a smoother user experience.
|
|
* **Testing:** Implement unit and potentially end-to-end tests.
|
|
* **State Management:** For larger applications, consider introducing a dedicated state management library (like Zustand, Pinia, Redux Toolkit) instead of relying solely on `utils.ts`.
|
|
|
|
## Contributing
|
|
|
|
[Link to Contribution Guidelines](./CONTRIBUTION.md)
|
|
|
|
## License
|
|
|
|
[View MIT License](./LICENSE) |