fiery-hostel System Requirements Document

1. Introduction

The "fiery-hostel" project is a medium-sized full-stack web application designed to manage hostel maintenance complaints. The system allows students to report issues and enables hostel administrators to manage, prioritize, assign, and resolve these complaints efficiently. The focus is on creating a streamlined complaint and maintenance workflow without incorporating additional hostel-management features.

2. System Overview

2a. Product Interpretation and Delivery Boundary

• Domain Descriptor: Complaint Management System

  • Source Evidence: The system focuses on managing and resolving hostel maintenance complaints.
  • Confidence: High

• Project Scope:

  • Included: Student complaint submission, AI-powered complaint analysis, admin complaint management, dashboards, and analytics.
  • Excluded: Rent/payment management, room allocation, visitor management, leave management, hostel property management, complex staff management, real payment gateway, complex messaging system.

• Custom Pages:

  • Student Login
  • Student Dashboard
  • Complaint Submission
  • Admin Dashboard
  • Complaint Details

• Access: Application-owned identity with JWT authentication and role-based authorization.

• Behavior Contracts:

  • Student Login: Students login to access the system.
  • Submit Complaint: Students submit complaints with optional images and receive AI suggestions.
  • Manage Complaints: Admins manage complaints and update statuses.
  • View Complaint Details: Both students and admins view complaint details and history.
  • Show Role-Based Actions: Display actions based on user roles in complaint details.
  • Authenticate User with JWT and bcrypt: Secure user authentication.

2b. Page Content and Component Coverage

• Student Dashboard:

  • Components: Complaint summary cards, status chart
  • States: Empty, loading, populated
  • Actions: View complaints, navigate to complaint submission

• Complaint Submission:

  • Components: Complaint form, image upload, AI suggestion review
  • States: Draft, submitted, error
  • Actions: Submit complaint, edit AI suggestions

• Admin Dashboard:

  • Components: Analytics charts, complaint list
  • States: Loading, populated, error
  • Actions: Filter complaints, view details

• Complaint Details:

  • Components: Complaint information, comments section
  • States: Loading, error, resolved
  • Actions: Add comments, change status, assign complaint

3. Functional Requirements as Story Points

• As a Student, I should be able to submit a complaint with an optional image and receive AI suggestions for category and priority. explicit
• As a Student, I should be able to view my complaint history and details. explicit
• As a Student, I should be able to add comments to my complaints and receive notifications on status changes. explicit
• As an Admin, I should be able to login and access the admin dashboard to manage complaints. explicit
• As an Admin, I should be able to search, filter, and view complaint details. explicit
• As an Admin, I should be able to change complaint statuses, assign complaints, and add comments. explicit
• As a User, I should be able to authenticate using JWT and bcrypt for secure access. required_inference

4. User Personas

• Student: Primary user who submits and tracks complaints.
• Admin: User who manages and resolves complaints.

5. Core User Flows

Student Flow (Revised)

1. Login to the system.
2. Access the student dashboard to view complaint summaries.
3. Submit a new complaint with optional image upload.
4. Review and edit AI-suggested category and priority.
5. View complaint details and add comments.
6. Receive notifications on complaint status changes.

Admin Flow

1. Login to the admin dashboard.
2. View analytics and complaint summaries.
3. Search and filter complaints.
4. View detailed complaint information.
5. Change complaint status, assign tasks, and add comments.

6. Visuals Colors and Theme

• Primary: #1A73E8
• Primary Light: #E8F0FE
• Secondary: #34A853
• Accent: #EA4335
• Highlight: #FBBC05
• Background: #FFFFFF
• Surface: #F1F3F4
• Text: #202124
• Text Muted: #5F6368
• Border: #DADCE0

7. Signature Design Concept

The fiery-hostel application will feature a modern, clean SaaS-style interface with a focus on usability and clarity. The design will incorporate a sidebar navigation for easy access to different sections, professional cards for displaying complaint summaries, and a consistent color scheme to enhance the user experience. The student dashboard will prominently feature complaint status charts and summary cards, providing a clear overview of complaint progress. The admin dashboard will include analytics charts to help visualize complaint data by category, status, and priority.

8. Interaction Model & Motion Direction

• Interaction Model: Animated
  • Moderate scroll-triggered reveals and hover transitions will be used to enhance user interaction.
  • The student dashboard will feature animated complaint status charts for a dynamic user experience.

9. Non-Functional Requirements

• JWT Authentication: Secure access with JWT and role-based authorization. explicit
• Responsive Design: The application must be fully responsive to ensure usability across devices. explicit

10. Tech Stack

• Frontend: React, Vite, Tailwind CSS, React Router, Recharts
• Backend: Node.js, Express.js
• Database: MongoDB, Mongoose
• Authentication: JWT, bcrypt
• AI: Configurable LLM API through environment variables
• File Upload: Cloudinary or simple configurable upload implementation

11. Assumptions and Constraints

• The application will not include features such as rent/payment management, room allocation, visitor management, leave management, hostel property management, complex staff management, real payment gateway, or complex messaging systems.
• The database will be kept simple with proper relationships and timestamps.

12. Glossary

• JWT: JSON Web Token, a compact, URL-safe means of representing claims to be transferred between two parties.
• LLM: Large Language Model, used for AI-powered text analysis.
• CRUD: Create, Read, Update, Delete, the four basic functions of persistent storage.