diff --git a/README.md b/README.md index 502fd99..8c0760c 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,40 @@ # 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 a global API structure designed to interact with a backend server. +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 modules for easy maintainability and scalability. -* **Responsive Design:** Built with Bootstrap 5.3 to ensure responsiveness across various devices. -* **Widget System:** Extensible widget system with two size types (default full-width and icon-type for sidebar). -* **Global API System:** Clearly defined API structure for communication with a backend (currently mocked). -* **Layout Modules:** Pre-built layouts (Centered, Three-Column, Split-Column) for different page structures. -* **Page Components:** Includes pre-built pages for Login, Register, Dashboard, Settings, Admin, Profile, and Manage Students. -* **Topbar Module:** Navigation and user profile dropdown. -* **Modal Module:** (To be implemented) For reusable modal components. -* **Basic Authentication Flow:** Login and logout functionality with token-based session management (localStorage). +* **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 type-safe and maintainable codebase. -* **Vite:** For fast and efficient development and build process. -* **Bootstrap v5.3:** For responsive layout and styling. -* **pnpm:** Package manager for efficient dependency management. -* **argon2-browser:** (For demonstration purposes - **Backend Hashing Recommended**) For frontend password hashing demonstration (Argon2id). **Important:** In a production environment, password hashing should be performed on the backend for security reasons. +* **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 + git clone cd lms-frontend ``` @@ -42,85 +44,86 @@ This is the frontend for a modular and responsive Learner Management System (LMS pnpm install ``` -3. **Start the development server:** +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 in the console (usually `http://localhost:5173/`). + 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 -├── pnpm-lock.yaml # pnpm lock file for dependency management -├── pnpm-workspace.yaml # pnpm workspace configuration -├── public/ # Public assets (images, etc.) +├── 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 interaction functions (mocked in api.ts) -│ ├── assets/ # Static assets (images, icons) -│ ├── components/ # Reusable components -│ │ ├── layouts/ # Page layout components (CenteredLayout, ThreeColumnLayout, SplitColumnLayout) -│ │ ├── modules/ # Modules (TopbarModule, ModalModule - to be implemented) -│ │ ├── widgets/ # Widget components (LoginWidget, ButtonWidget, etc.) -│ ├── main.ts # Main entry point for the application -│ ├── pages/ # Page components (LoginPage, DashboardPage, etc.) -│ ├── styles/ # Global styles and Bootstrap import (index.css) -│ ├── types/ # Typescript interfaces (Widget.ts, User.ts) -│ ├── utils/ # Utility functions (api.ts, auth.ts) -│ ├── vite-env.d.ts # Vite environment declaration -├── tsconfig.json # Typescript configuration -├── vite.config.ts # Vite configuration +│ ├── 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 frontend is built around a widget system. Widgets are independent, reusable components that display specific information or functionality. - -* **Widget Sizes:** - * `default`: Full column width, suitable for most widgets. - * `icon`: Smaller size, designed for use in collapsed sidebars or icon-based menus. - -* **Widget Components:** Located in `src/components/widgets/`. Examples include: - * `LoginWidget`: Login form. - * `RegisterWidget`: Registration information display. - * `ButtonWidget`: Reusable button component. - * `StudentCountWidget`, `TeacherCountWidget`, `ProfileInfoWidget`, `PostFeedWidget`, `StudentTableWidget`, `TuitionFeeWidget`: Placeholder widgets to be implemented. +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 -The frontend is designed to interact with a backend through a global API system defined in `src/utils/api.ts`. +Defined in `src/api/api.ts`, this module handles all communication with the backend API. -* **Current Implementation:** The `api.ts` file currently contains **mocked API calls** for demonstration purposes. It simulates API responses using timeouts and hardcoded data. -* **Backend Integration:** To connect to a real backend, you will need to replace the mocked API calls in `api.ts` with actual `fetch` requests to your backend endpoints. -* **Expected Backend Endpoints (Example):** - * `POST /api/login`: User login. - * `GET /api/user`: Get user data (requires authentication). - * `POST /api/logout`: User logout. - * `/api/students`, `/api/teachers`, `/api/admin/students`, etc.: Endpoints for managing students, teachers, and other LMS data. +* **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 ` 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 Considerations +## Backend Interaction Notes -* **Password Hashing (Backend Recommended):** While `argon2-browser` is included for frontend password hashing demonstration, **it is strongly recommended to implement password hashing (using Argon2id or similar) and salting on the backend for enhanced security.** The frontend should send passwords securely (HTTPS) to the backend, and the backend should handle the hashing and verification process. -* **Authentication and Authorization:** The backend should implement robust authentication (e.g., JWT or session-based) and authorization mechanisms to secure API endpoints and protect sensitive data. -* **Database:** The database schema outlined in the initial prompt should be implemented on the backend to store user data, course information, enrollments, etc. (Refer to the initial prompt for database schema details). -* **Backend Technology:** You can choose any suitable backend technology (Node.js, Python, Java, PHP, etc.) to build the API endpoints and connect to the database. +* **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 -* **Implement Modal Module:** Create a reusable `ModalModule` component in `src/components/modules/ModalModule.ts` to handle modals for various purposes (e.g., classrooms under construction, account settings). -* **Complete Widget Implementations:** Implement the remaining placeholder widgets in `src/components/widgets/` (e.g., `StudentCountWidget`, `TeacherCountWidget`, `ProfileInfoWidget`, `PostFeedWidget`, `StudentTableWidget`, `TuitionFeeWidget`) to display actual data from the backend. -* **Account Settings Modal:** Develop the Account Settings Modal to allow users to edit their profile information and change passwords. -* **Admin Page Functionality:** Implement the functionality for the Admin page, including student and teacher management, using appropriate widgets and API calls. -* **Student Table Widget:** Integrate a table library (e.g., Tabulator, DataTables) into the `StudentTableWidget` for enhanced table features like sorting, filtering, and pagination. -* **Classrooms Page/Modal:** Implement the Classrooms feature, potentially starting with a modal indicating "Under Construction" as initially requested, and then expanding to a full Classrooms page with relevant widgets. -* **Form Validation:** Add client-side form validation to login, registration (if implemented), and account settings forms for better user experience. -* **Error Handling:** Improve error handling in API calls and display user-friendly error messages. -* **Styling and UI Polish:** Enhance the visual design and user interface with custom CSS and Bootstrap components to create a polished and professional LMS frontend. -* **Backend Integration:** Replace the mocked API calls with real API calls to your backend endpoints to connect the frontend to the backend data and functionality. +* **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 @@ -128,4 +131,4 @@ The frontend is designed to interact with a backend through a global API system ## License -[View the License](./LICENSE) \ No newline at end of file +[View MIT License](./LICENSE) \ No newline at end of file