lms-frontend/docs/CONTRACT.md

Contract Proposal: Learner Management System (LMS)

INTERNAL NOTES FOR THOSE WRITING THE CONTRACT:

Check the source code in order to see the following:

• <!-- FOR INTERNAL TEAM USE -->: Marks a section primarily for the development team's reference.
• <!-- PLACEHOLDER: [Instruction] -->: Indicates specific information the team needs to fill in or verify before finalizing for a client.
• Regular text without markers is intended for the final client-facing proposal.

Executive Summary

1. Development Approach (SDLC):

We will utilize an Agile (Iterative and Incremental) methodology. This approach ensures flexibility, allowing the LMS to adapt to evolving needs through regular feedback loops and the delivery of working software components in short cycles (sprints). This minimizes risk and maximizes alignment with your requirements.

2. Key Advantages:

• Modern & Performant: Built with a cutting-edge stack ([Specify frontend tech: e.g., Vite Vanilla, React], Rust/Actix backend, MariaDB) for speed, scalability, and long-term maintainability.
• User-Focused Design: An intuitive, responsive interface ensures ease of use for learners, instructors, and administrators across all devices.
• Modular & Scalable: The architecture is designed for future growth, allowing seamless integration of new features and modules as your needs expand.
• Collaborative & Transparent: Our Agile process emphasizes clear communication and regular updates, ensuring you are involved and informed throughout development.

3. Potential Considerations & Mitigation:

• Evolving Scope: Agile's flexibility requires careful scope management. We mitigate this through prioritized backlogs and a clear change request process.
• Initial Setup: LMS implementation involves initial setup and potential data migration. We provide dedicated onboarding support, training, and documentation to ensure a smooth transition.

4. Video Demonstration:

A concise video demonstration will showcase the LMS's core functionalities, user roles (learner, instructor, admin), and key workflows like course interaction and progress tracking.

5. System Overview:

The LMS features a user-friendly interface with a standard layout (top navigation, optional sidebar, main content area) and a robust backend architecture ensuring efficient data management and processing. (Detailed diagrams follow in the full version).

6. Estimated Timeframe:

The project is estimated to take approximately [Calculate total weeks from Gantt, e.g., 35 weeks], broken down into phases: Planning & Design (5 weeks), Development (18 weeks), Testing & Deployment (8 weeks), and Training & Handover (4 weeks). (A detailed Gantt chart is provided in the full version).

---

Full Proposal Document

Contract Proposal: Learner Management System (LMS) Development and Implementation

1. SDLC (Software Development Life Cycle) Used: Agile - Iterative and Incremental Methodology

For the development of the Learner Management System (LMS), we will employ an Agile Software Development Life Cycle (SDLC) methodology, specifically focusing on an iterative and incremental approach.

• Methodology Description: Agile development breaks down the project into smaller, manageable cycles called iterations or sprints (typically 2-4 weeks). Each iteration includes planning, design, development, testing, and stakeholder review, culminating in a potentially shippable increment of the software. This process repeats, with each increment building upon the previous ones, allowing the LMS to evolve based on feedback and real-world usage.

• Why Agile for this LMS?

  • Adaptability: The educational landscape and user needs can change. Agile allows us to incorporate feedback and adjust priorities effectively throughout the project without derailing progress.
  • Early Value & Feedback: You will see working parts of the LMS early and often. This provides tangible progress and crucial opportunities to provide feedback, ensuring the final product truly meets your needs.
  • Collaboration & Transparency: Agile fosters close collaboration between our team and your stakeholders through regular meetings (e.g., sprint reviews, planning sessions) and clear communication channels.
  • Risk Management: Addressing challenges in small iterations allows for early identification and mitigation of risks, preventing them from escalating into major roadblocks.
  • User-Centricity: Continuous feedback loops ensure the development remains focused on delivering the best possible experience for learners, instructors, and administrators.

Our commitment to Agile principles ensures a collaborative, flexible, and results-oriented development process tailored to delivering a high-quality LMS.

2. Advantages: Key Benefits of the Proposed Learner Management System

This LMS project is meticulously designed to provide substantial advantages through its technology, design, and the project management approach employed.

• Technological Advantages:

  • Modern Technology Stack: The LMS leverages a robust and contemporary technology stack:
    • Frontend: [Specify frontend tech: e.g., Vite Vanilla for rapid prototyping and performance, potentially transitioning to React/Vue for larger-scale features if needed]
    • Backend: Rust with the Actix framework, chosen for its exceptional performance, memory safety, and concurrency capabilities, ensuring a highly responsive and scalable backend.
    • Database: MariaDB, a reliable and performant open-source relational database, well-suited for structured LMS data.
    • Deployment: Containerized using Docker and orchestrated with Docker Compose for consistent environments and easier deployment/scaling.
  • Performance & Scalability: The chosen technologies are optimized for speed and efficiency, capable of handling a growing number of users and concurrent activity without performance degradation.
  • Security Focused: Security is integrated from the start, employing secure authentication (PAKE SRP), data validation, appropriate data handling practices, and readiness for standard security protocols (HTTPS).
  • API-Ready Architecture: The backend is designed with API principles in mind, facilitating potential future integrations with other institutional systems or third-party educational tools.

• Design Advantages:

  • Intuitive User Experience (UX): Prioritizing ease of use, the interface will feature clear navigation, logical workflows, and a clean layout, minimizing the learning curve for all user types.
  • Responsive & Accessible UI: The user interface will adapt seamlessly to various screen sizes (desktops, tablets, mobiles) and will adhere to accessibility best practices (WCAG guidelines where applicable) to ensure usability for everyone.
  • Visually Engaging: A modern aesthetic will be applied to create a professional and engaging learning environment.
  • Modular Layout: The frontend utilizes a widget-based system and distinct layout modules (centered, three-column, split-column), promoting code reusability and simplifying future enhancements or modifications.

• Project Management Advantages:

  • Experienced Team: Our team comprises skilled developers proficient in Rust, modern frontend frameworks, database management, and experienced project managers adept at Agile methodologies.
  • Transparent Process: We ensure transparency through regular progress updates, sprint demonstrations, access to project tracking tools (), and open communication channels.
  • Quality Assurance: Rigorous testing is embedded in our process, including automated tests (unit, integration where feasible) and manual testing (functional, usability, UAT) to deliver a stable and reliable platform.
  • On-Time Delivery Focus: Our Agile planning and execution aim for predictable delivery of milestones outlined in the project timeframe.

3. Disadvantages: Potential Limitations and Mitigation Strategies

Transparency is key to a successful partnership. While we are confident in delivering an exceptional LMS, we acknowledge potential challenges and have proactive mitigation strategies in place.

• Potential for Scope Creep (Agile Flexibility):

  • Challenge: The iterative nature of Agile can sometimes lead to requests for additional features ("scope creep") that were not initially planned, potentially impacting timelines or budget.
  • Mitigation:
    • Clear Initial Scope: We begin with a thorough requirements gathering phase to establish a clear baseline scope documented in a product backlog.
    • Prioritization: Features in the backlog are prioritized based on value and effort, ensuring focus remains on core objectives.
    • Structured Change Management: A formal process will be used for any new feature requests. Each request will be evaluated for its impact on scope, timeline, and budget, requiring stakeholder approval before being added to the backlog.
    • Sprint Goal Focus: Each sprint will have a clear goal, helping the team stay focused on delivering the agreed-upon functionality for that iteration.

• Complexity of Initial Setup and Data Migration:

  • Challenge: Implementing any new system, particularly one replacing an existing platform, involves initial configuration, user setup, and potentially migrating data, which can be complex.
  • Mitigation:
    • Dedicated Support: We will provide dedicated support during the onboarding phase to assist with system configuration and user setup.
    • Data Migration Planning: If data migration is required, we will collaborate with you to develop a detailed migration plan, including data mapping, validation, and testing, to ensure accuracy and minimize disruption.
    • Comprehensive Training: Role-specific training materials (documentation, videos, potentially live sessions) will be provided for administrators, instructors, and learners.
    • Phased Rollout Option: We can discuss a phased rollout strategy (e.g., by department, by feature set) if desired, to allow for gradual adoption and focused support.
    • Ongoing Documentation: Clear and accessible documentation will be maintained for ongoing reference.

4. Video Explanation: Demonstrating the LMS Functionality

To provide a tangible preview of the LMS, we will produce a short video walkthrough. This video will cover:

• Platform Navigation: A guided tour of the main dashboard, navigation elements (top bar, sidebar where applicable), and overall layout.
• Key User Journeys:
  • Learner: How a learner finds and enrolls in a course, accesses learning materials (lessons, resources), submits assignments, checks grades, and views their progress.
  • Instructor: How an instructor manages their courses, uploads content, creates assignments/quizzes, grades submissions, communicates with learners, and monitors class progress.
  • Administrator: How an administrator manages users (students, teachers), oversees courses, configures system settings, and accesses basic reporting.
• Core Feature Highlights: Demonstrations of key modules like the dashboard widgets, profile management, course interaction pages, and admin management interfaces.
• Responsiveness: Briefly showcasing how the interface adapts to different screen sizes.

This video aims to give stakeholders a clear visual understanding of the system's look, feel, and core capabilities before full deployment.

5. System Architecture & User Interface Overview

5.1. User Interface (UI) Wireframe & Layout

The LMS user interface is designed for clarity, consistency, and ease of navigation. The core layout principles are:

• Header (Top Navigation Bar): Consistently visible at the top, providing access to main menu pages (e.g., Dashboard, Classrooms, Admin), user profile information (picture, name), and account actions (Profile, Settings, Logout) via a dropdown.
• Sidebar (Contextual Navigation): Appears in specific layouts (like the Split Column Layout). It provides quick access to subsections or features relevant to the current module (e.g., course navigation, admin sub-menus). It supports a collapsed icon-only mode for maximizing content space.
• Main Content Area: The primary workspace where module-specific content, widgets, forms, tables, and learning materials are displayed dynamically based on user interaction. Layouts include Centered (for Login/Register), Three-Column (for Admin Dashboard), and Split Column (for pages requiring a sidebar).
• Footer: Contains essential links (e.g., support, privacy policy), copyright information.

The following diagram illustrates a high-level flow and component relationship within the user interface:

flowchart TD
  %% Layout Types (Vertical)
  subgraph Layouts["Layouts"]
    Centered["🎯 Centered Layout (Login, Register)"]
    ThreeCol["🏛️ Three-Column Layout (Admin Dash)"]
    SplitCol["| Sidebar | Content | (Split Column Layout)"]
  end

  %% Core Components
  Header["🧭 Header (Logo, Menu, User Profile Dropdown)"]
  Sidebar["📚 Sidebar (Optional, Collapsible)"]
  MainContent["🖥️ Main Content Area (Hosts Widgets/Pages)"]
  Footer["📎 Footer (Links, Copyright)"]
  Modal["P M Modal Container"]

  %% Page Examples & Widget Hosting
  LoginPage["🔑 Login Page"]
  LoginWidget["🧩 Login Widget (SRP)"]
  RegisterButtonWidget["🧩 Button Widget -> Register"]

  RegisterPage["✍️ Register Page"]
  RegisterInfoWidget["🧩 Register Info Widget"]
  LoginButtonWidget["🧩 Button Widget -> Login"]

  DashboardPage["📊 Dashboard Page"]
  VariousWidgets["🧩 Various Dashboard Widgets"]

  ProfilePage["👤 Profile Page"]
  ProfileInfoWidget["🧩 Profile Info Widget (Pic, Name, ID, DOB)"]
  PostFeedWidget["🧩 Post Feed Widget"]

  AdminPage["⚙️ Admin Dashboard"]
  StudentsWidget["🧩 Students Widget"]
  TeachersWidget["🧩 Teachers Widget"]

  ManageStudentsPage["📋 Manage Students Page"]
  StudentTableWidget["🧩 Student Table Widget"]

  %% Layout usage relationships (vertical chaining)
  LoginPage --> Centered
  RegisterPage --> Centered
  DashboardPage --> SplitCol
  ProfilePage --> SplitCol
  AdminPage --> ThreeCol
  ManageStudentsPage --> SplitCol

  %% Containment relationships
  LoginPage --> LoginWidget
  LoginPage --> RegisterButtonWidget

  RegisterPage --> RegisterInfoWidget
  RegisterPage --> LoginButtonWidget

  DashboardPage --> VariousWidgets

  ProfilePage --> ProfileInfoWidget
  ProfilePage --> PostFeedWidget

  AdminPage --> StudentsWidget
  AdminPage --> TeachersWidget

  ManageStudentsPage --> StudentTableWidget

  %% Core Component Relationships (chained vertically)
  Header --> Sidebar
  Sidebar --> MainContent
  MainContent --> Footer

  %% Modal Triggering (vertical flow)
  UserProfile["User Profile"] --> Modal
  Modal --> AccountSettingsWidget["🧩 Account Settings Widget"]
  MenuLinks["Menu Links"] --> Modal
  Modal --> UnderConstructionWidget["🧩 'Under Construction' Widget (e.g., Classrooms)"]

Diagram: High-level UI Component Relationships and Layout Usage.

5.2. Backend Architecture (Internal Reference)

The backend is built using Rust and the Actix web framework, interacting with a MariaDB database via SQLx. It's designed to be modular and performant.

Code Structure:

The project follows a standard Rust structure with modules for configuration (config.rs), database interactions (db.rs), request handling (handlers.rs), data models (models.rs), and error handling (errors.rs). The main.rs file initializes the application, database pool, middleware, and routes.

Request Flow:

1. Request Received: Actix server receives an HTTP request.
2. Middleware: Passes through Logging, CORS, and (future) Auth middleware.
3. Routing: Matched to a handler function in handlers.rs.
4. Handler Execution: Logic is executed, potentially using injected DB pool, AppState (for temporary SRP/session data - Note: Requires replacement for production), and deserialized request data.
5. DB Interaction: Handler calls functions in db.rs which use SQLx to query MariaDB.
6. Response/Error: Handler returns a JSON response (using models from models.rs) or an AppError which is converted to a standard JSON error response.

Component Diagram:

flowchart TD
  subgraph A["🌐 Client (Browser)"]
    direction LR
    Frontend["Vite App"]
  end

  subgraph B["🐳 Docker Environment"]
    direction TB
    subgraph C["🚦 Actix Backend Container (lms-backend)"]
        direction LR
        ActixServer["🚀 Actix HTTP Server"] --> Middleware["🛡️ Middleware (CORS, Log, Auth*)"]
        Middleware --> Router["🗺️ Router (handlers.rs)"]
        Router --> Handlers["⚙️ Route Handlers"]
        Handlers -- Uses --> DBPool["💾 DB Pool (SQLx)"]
        Handlers -- Uses --> Models["📝 Data Models (models.rs)"]
        Handlers -- Uses --> Errors["❗ Error Handling (errors.rs)"]
        Handlers -- Uses --> AppState["🧠 App State (Temp SRP/Session*)"]
        Handlers -- Calls --> DBModule["🗃️ DB Logic (db.rs)"]
        DBModule -- Uses --> DBPool
        DBModule -- Uses --> Models
    end
    subgraph D["🗄️ MariaDB Container (db)"]
        MariaDB["MariaDB Server"] -- Stores --> LMSData["LMS Database (lms_db)"]
    end
    C -- Connects via Network --> D
  end

  A --> B

  %% Notes

Diagram: Backend Component Interaction and Deployment Structure.

6. Timeframe (Gantt Chart): Project Schedule and Milestones

The following Gantt chart provides an estimated schedule for the LMS project, outlining key phases, tasks, dependencies, and durations. This timeline is based on our Agile methodology and assumes standard workweeks. Actual sprint-level timelines will be refined during project execution.

gantt
    title LMS Development Timeframe (Estimated)
    dateFormat  YYYY-MM-DD
    axisFormat %Y-%m-%d
    todayMarker stroke-width:3px,stroke:#E67E22,stroke-opacity:0.8
    %% Define Sections based on Phases
    section Phase 1: Planning & Design (Approx. 5 Weeks)
    Requirements Gathering & Analysis  :req, 2024-01-15, 10d
    System Architecture Design         :design, after req, 10d
    UI/UX Wireframing & Prototyping    :wireframe, after design, 10d
    Tech Stack Finalization & Setup    :setup, after design, 5d
    Phase 1 Review & Approval         :p1review, after wireframe, 5d

    section Phase 2: Core Development (Approx. 18 Weeks)
    Database Schema Implementation     :dbdev, after setup, 15d
    Backend Core & Auth Dev (Rust)     :backend, after setup, 50d
    Frontend Foundational Setup        :frontend_setup, after setup, 15d
    API Development & Integration      :api, after backend, 30d
    Frontend UI Development            :frontend_ui, after frontend_setup, 40d
    Widget System Implementation       :frontend_widget, after frontend_setup, 20d
    Module Development (Iterative)     :modules, after api, 60d
    Initial Dev Testing & Integration  :devtest, after modules, 15d

    section Phase 3: Testing & Deployment (Approx. 8 Weeks)
    Comprehensive QA Testing           :qatest, after devtest, 20d
    User Acceptance Testing (UAT)      :uat, after qatest, 10d
    Feedback Implementation & Bug Fixing :fixes, after uat, 10d
    Deployment Preparation             :deployprep, after fixes, 5d
    Production Deployment & Go-Live    :deploy, after deployprep, 5d

    section Phase 4: Post-Launch (Approx. 4 Weeks)
    System Monitoring & Stabilization  :monitor, after deploy, 10d
    Admin & Instructor Training        :admintrain, after deploy, 10d
    Learner Onboarding Materials       :learnertrain, after admintrain, 10d
    Final Documentation & Handover     :handover, after admintrain, 10d

    %% Milestones (Aligned with phase ends where logical)
    milestone Phase 1 Complete : 2024-02-16
    milestone Core Backend Complete : 2024-04-19
    milestone Core Frontend Complete : 2024-05-31
    milestone Development Complete : 2024-07-26
    milestone Testing Complete : 2024-08-23
    milestone Project Go-Live : 2024-08-30
    milestone Project Handover : 2024-09-27

Note: Dates are estimates and subject to refinement based on detailed sprint planning and potential scope adjustments.