docs/plan.md

# Project Plan for Hostel Grievance Redressal System

## Table of Contents

1. [Web Pages Design](#1-web-pages-design)
    - [High-Level Design](#high-level-design)
    - [Low-Level Design](#low-level-design)
2. [Workflow and Event Flow](#2-workflow-and-event-flow)
3. [Directory Structure and File Division](#3-directory-structure-and-file-division)
4. [Backend and Frontend Separation](#4-backend-and-frontend-separation)
5. [Performance Dashboard for Students](#5-performance-dashboard-for-students)

---

## 1. Web Pages Design

### High-Level Design

The Hostel Grievance Redressal System consists of several web pages tailored for different user roles: **Residents (Students)** and **Administrators (Wardens)**. Each page is designed to provide specific functionalities to enhance user experience and ensure efficient grievance management.

#### Pages Overview

1. **Authentication Pages**
    - **Login Page**
    - **Signup Page**

2. **Resident Pages**
    - **Student Dashboard**
    - **Student Profile Information**
    - **Submit Grievance**
    - **View Submitted Grievances**
    - **Grievance Details and Chatroom**

3. **Administrator Pages**
    - **Warden Dashboard**
    - **Manage Grievances**
    - **Resolve Grievance**
    - **Performance Dashboard**

4. **Common Components**
    - **Navigation Bar**
    - **Footer**
    - **Notification System**

### Low-Level Design

#### 1. Authentication Pages

##### Login Page
- **Components:**
    - **LoginForm**
        - Email Input
        - Password Input
        - Submit Button
    - **Forgot Password Link**
    - **Signup Redirect Link**
- **Functionality:**
    - User enters credentials and submits to authenticate.
    - Validation for input fields.
    - Error handling for incorrect credentials.

```markdown
````react:src/frontend/components/LoginPage.js
function LoginPage() {
    return (
        <div className="login-container">
            <LoginForm />
            <a href="/forgot-password">Forgot Password?</a>
            <a href="/signup">Don't have an account? Sign Up</a>
        </div>
    );
}
```
````

##### Signup Page
- **Components:**
    - **SignupForm**
        - Name Input
        - Email Input
        - Password Input
        - Confirm Password Input
        - Submit Button
- **Functionality:**
    - User registers by providing necessary details.
    - Validation for input fields.
    - Password strength indicator.

```markdown
````react:src/frontend/components/SignupPage.js
function SignupPage() {
    return (
        <div className="signup-container">
            <SignupForm />
            <a href="/login">Already have an account? Login</a>
        </div>
    );
}
```
````

#### 2. Resident Pages

##### Student Dashboard
- **Components:**
    - **Sidebar Navigation**
    - **Recent Grievances**
    - **Statistics Overview**
    - **Quick Submit Button**
- **Functionality:**
    - Overview of submitted grievances.
    - Quick access to submit new grievances.
    - Visual statistics on grievance statuses.

```markdown
````react:src/frontend/pages/StudentDashboard.js
function StudentDashboard() {
    return (
        <div className="dashboard-container">
            <Sidebar />
            <div className="dashboard-content">
                <RecentGrievances />
                <StatisticsOverview />
                <QuickSubmitButton />
            </div>
        </div>
    );
}
```
````

##### Student Profile Information
- **Components:**
    - **ProfileForm**
        - Editable fields: Name, Email, Contact Number, Address
        - Save Button
    - **ProfilePictureUpload**
- **Functionality:**
    - View and edit personal information.
    - Update profile picture.

```markdown
````react:src/frontend/pages/StudentProfile.js
function StudentProfile() {
    return (
        <div className="profile-container">
            <Sidebar />
            <div className="profile-content">
                <ProfileForm />
                <ProfilePictureUpload />
            </div>
        </div>
    );
}
```
````

##### Submit Grievance
- **Components:**
    - **GrievanceForm**
        - Title Input
        - Description Textarea
        - Category Dropdown
        - Attachments Upload
        - Voice-to-Text Input
        - Submit Button
- **Functionality:**
    - Allow residents to submit grievances with text or voice input.
    - Attach relevant files if necessary.
    - Categorize grievance for proper routing.

```markdown
````react:src/frontend/pages/SubmitGrievance.js
function SubmitGrievance() {
    return (
        <div className="submit-grievance-container">
            <Sidebar />
            <div className="grievance-form-container">
                <GrievanceForm />
            </div>
        </div>
    );
}
```


##### View Submitted Grievances
- **Components:**
    - **GrievanceList**
        - List Item (GrievanceTitle, Status, Submission Date)
    - **Filter and Search Bar**
- **Functionality:**
    - Display a list of grievances submitted by the student.
    - Filter and search functionality for easy navigation.

```markdown
````react:src/frontend/pages/ViewGrievances.js
function ViewGrievances() {
    return (
        <div className="view-grievances-container">
            <Sidebar />
            <div className="grievances-list-container">
                <FilterSearchBar />
                <GrievanceList />
            </div>
        </div>
    );
}
```


##### Grievance Details and Chatroom
- **Components:**
    - **GrievanceDetails**
        - Grievance Information (Title, Description, Status, Assigned Warden)
    - **Chatroom**
        - Message List
        - Input Box
        - Send Button
- **Functionality:**
    - View detailed information about a specific grievance.
    - Real-time chat with assigned warden for updates and communication.

```markdown
````react:src/frontend/pages/GrievanceDetails.js
function GrievanceDetails({ grievanceId }) {
    return (
        <div className="grievance-details-container">
            <Sidebar />
            <div className="details-and-chat">
                <GrievanceDetails />
                <Chatroom grievanceId={grievanceId} />
            </div>
        </div>
    );
}
```


#### 3. Administrator Pages

##### Warden Dashboard
- **Components:**
    - **Sidebar Navigation**
    - **Grievances Overview**
    - **Assigned Grievances**
    - **Performance Metrics**
- **Functionality:**
    - Overview of all grievances.
    - Manage assignments and track resolution progress.
    - View performance metrics of handled grievances.

```markdown
````react:src/frontend/pages/WardenDashboard.js
function WardenDashboard() {
    return (
        <div className="warden-dashboard-container">
            <Sidebar />
            <div className="warden-dashboard-content">
                <GrievancesOverview />
                <AssignedGrievances />
                <PerformanceMetrics />
            </div>
        </div>
    );
}
```


##### Manage Grievances
- **Components:**
    - **GrievanceManagementList**
        - Grievance Item (Title, Status, Assigned To, Actions)
    - **Filter and Sort Options**
- **Functionality:**
    - View and manage all grievances.
    - Assign grievances to appropriate personnel.
    - Update grievance statuses.

```markdown
````react:src/frontend/pages/ManageGrievances.js
function ManageGrievances() {
    return (
        <div className="manage-grievances-container">
            <Sidebar />
            <div className="management-content">
                <FilterSortOptions />
                <GrievanceManagementList />
            </div>
        </div>
    );
}
```


##### Resolve Grievance
- **Components:**
    - **ResolutionForm**
        - Resolution Description
        - Status Update Dropdown
        - Attachments Upload
        - Submit Resolution Button
- **Functionality:**
    - Provide resolution details for a grievance.
    - Update the status to "Completed" or other relevant states.
    - Notify the resident upon resolution.

```markdown
````react:src/frontend/pages/ResolveGrievance.js
function ResolveGrievance({ grievanceId }) {
    return (
        <div className="resolve-grievance-container">
            <Sidebar />
            <div className="resolution-form-container">
                <ResolutionForm grievanceId={grievanceId} />
            </div>
        </div>
    );
}
```


#### 4. Common Components

##### Navigation Bar
- **Components:**
    - **Logo**
    - **Navigation Links**
    - **User Profile Dropdown**
    - **Notifications Icon**
- **Functionality:**
    - Provide easy navigation across different pages.
    - Access user profile and notifications.

```markdown
````react:src/frontend/components/NavigationBar.js
function NavigationBar() {
    return (
        <nav className="navigation-bar">
            <Logo />
            <NavigationLinks />
            <UserProfileDropdown />
            <NotificationsIcon />
        </nav>
    );
}
```


##### Footer
- **Components:**
    - **Links**
    - **Contact Information**
    - **Social Media Icons**
- **Functionality:**
    - Provide additional navigation and contact information.
    - Enhance the overall aesthetics of the application.

```markdown
````react:src/frontend/components/Footer.js
function Footer() {
    return (
        <footer className="footer">
            <Links />
            <ContactInfo />
            <SocialMediaIcons />
        </footer>
    );
}
```


##### Notification System
- **Components:**
    - **NotificationList**
        - Individual Notification Items
    - **Real-time Notification Badge**
- **Functionality:**
    - Display real-time notifications for updates on grievances.
    - Alert users for new messages or status changes.

```markdown
````react:src/frontend/components/NotificationSystem.js
function NotificationSystem() {
    return (
        <div className="notification-system">
            <NotificationBadge />
            <NotificationList />
        </div>
    );
}
```


---

## 2. Workflow and Event Flow

### User Roles and Actions

#### Resident (Student) Workflow

1. **Registration and Authentication**
    - **Events:**
        - User navigates to Signup Page.
        - Submits registration form.
        - System validates and creates user account.
        - User logs in via Login Page.

2. **Submitting a Grievance**
    - **Events:**
        - User accesses Submit Grievance Page.
        - Fills out grievance form or uses voice-to-text feature.
        - Submits grievance.
        - System categorizes and routes grievance using AI-powered routing.
        - A chatroom is created for real-time communication.
        - User receives confirmation and grievance status updates.

3. **Tracking Grievances**
    - **Events:**
        - User views Student Dashboard.
        - Navigates to View Grievances.
        - Selects a grievance to view details and participate in chat.

4. **Profile Management**
    - **Events:**
        - User accesses Profile Information page.
        - Updates personal details or profile picture.
        - Saves changes, and system updates the database.

#### Administrator (Warden) Workflow

1. **Authentication**
    - **Events:**
        - Warden logs in via Login Page.
        - Accesses Warden Dashboard upon successful authentication.

2. **Managing Grievances**
    - **Events:**
        - Warden views all grievances in Manage Grievances page.
        - Assigns grievances to appropriate personnel.
        - Updates grievance statuses as they progress.
        - Resolves grievances by providing resolution details.

3. **Performance Monitoring**
    - **Events:**
        - Warden accesses Performance Dashboard.
        - Views metrics on grievance handling efficiency, resolution times, and staff performance.
        - Generates reports for administrative review.

4. **Real-time Communication**
    - **Events:**
        - Warden participates in chatrooms for assigned grievances.
        - Sends and receives messages for updates and clarifications.

### AI/ML Functionalities Integration

1. **Automated Grievance Categorization**
    - **Event Flow:**
        - Upon grievance submission, text is processed by ML models.
        - Category is automatically assigned.
        - Grievance is routed based on the category.

2. **Sentiment Analysis for Prioritization**
    - **Event Flow:**
        - Grievance text is analyzed for sentiment.
        - Negative sentiments trigger higher priority assignments.
        - Dashboard highlights high-priority grievances.

3. **Predictive Resolution Time Estimation**
    - **Event Flow:**
        - System predicts resolution time based on historical data.
        - Estimated time is displayed to the user and warden.
        - Helps in managing expectations and resources.

4. **Anomaly Detection in Grievance Patterns**
    - **Event Flow:**
        - System continuously monitors grievance submissions.
        - Detects unusual spikes or patterns.
        - Alerts administrators to investigate potential systemic issues.

5. **Voice-to-Text Integration for Complaint Submission**
    - **Event Flow:**
        - User submits grievance via voice input.
        - Voice data is transcribed to text using speech recognition.
        - Transcribed text is processed for categorization and sentiment analysis.

6. **Proactive Grievance Prediction and Prevention**
    - **Event Flow:**
        - System analyzes trends to predict potential future grievances.
        - Suggests preventive measures to administrators.
        - Helps in mitigating issues before they escalate.

7. **Intelligent Routing and Workflow Automation**
    - **Event Flow:**
        - System assigns grievances to personnel based on AI-driven suggestions.
        - Continuously learns and adapts routing based on outcomes.
        - Ensures optimal workload distribution.

8. **Advanced Sentiment and Emotional Intelligence Analysis**
    - **Event Flow:**
        - Grievance submissions are analyzed for complex emotional states.
        - Responses are tailored based on detected emotions.
        - Enhances empathetic communication.

9. **Knowledge Graph Integration for Insight Generation**
    - **Event Flow:**
        - Grievances are integrated into a knowledge graph.
        - Enables advanced querying and pattern detection.
        - Provides actionable insights for improving the grievance resolution process.

---

## 3. Directory Structure and File Division

### Frontend Directory Structure

```markdown
````language:frontend
src/
├── assets/
│   ├── images/
│   │   └── *.png
│   └── styles/
│       └── tailwind.css
├── components/
│   ├── Authentication/
│   │   ├── LoginForm.js
│   │   └── SignupForm.js
│   ├── Common/
│   │   ├── NavigationBar.js
│   │   ├── Footer.js
│   │   └── NotificationSystem.js
│   ├── Dashboard/
│   │   ├── RecentGrievances.js
│   │   ├── StatisticsOverview.js
│   │   └── QuickSubmitButton.js
│   ├── Grievances/
│   │   ├── GrievanceForm.js
│   │   ├── GrievanceList.js
│   │   └── GrievanceDetails.js
│   ├── Profile/
│   │   ├── ProfileForm.js
│   │   └── ProfilePictureUpload.js
│   └── Chat/
│       └── Chatroom.js
├── pages/
│   ├── LoginPage.js
│   ├── SignupPage.js
│   ├── StudentDashboard.js
│   ├── StudentProfile.js
│   ├── SubmitGrievance.js
│   ├── ViewGrievances.js
│   ├── GrievanceDetails.js
│   ├── WardenDashboard.js
│   ├── ManageGrievances.js
│   ├── ResolveGrievance.js
│   └── PerformanceDashboard.js
├── services/
│   ├── api.js
│   ├── authService.js
│   ├── grievanceService.js
│   └── chatService.js
├── utils/
│   ├── validation.js
│   └── helpers.js
├── App.js
├── index.js
└── routes.js
```


### Backend Directory Structure

```markdown
````language:backend
src/
├── config/
│   ├── db.js
│   └── config.js
├── controllers/
│   ├── authController.js
│   ├── grievanceController.js
│   ├── userController.js
│   └── chatController.js
├── models/
│   ├── User.js
│   ├── Grievance.js
│   └── ChatMessage.js
├── routes/
│   ├── authRoutes.js
│   ├── grievanceRoutes.js
│   ├── userRoutes.js
│   └── chatRoutes.js
├── services/
│   ├── sentimentAnalysisService.js
│   ├── categorizationService.js
│   ├── routingService.js
│   └── knowledgeGraphService.js
├── middleware/
│   ├── authMiddleware.js
│   ├── errorHandler.js
│   └── validationMiddleware.js
├── utils/
│   ├── logger.js
│   └── helpers.js
├── app.js
└── server.js
```


### Explanation

- **Frontend (`src/frontend/`):**
    - **assets/**: Static assets like images and styles.
    - **components/**: Reusable React components categorized by functionality.
    - **pages/**: Page-level components representing different routes.
    - **services/**: API interaction logic.
    - **utils/**: Utility functions and helpers.
    - **App.js**: Root component.
    - **index.js**: Entry point.
    - **routes.js**: Application routing.

- **Backend (`src/backend/`):**
    - **config/**: Configuration files for database and environment variables.
    - **controllers/**: Business logic handling requests and responses.
    - **models/**: Database models using ORM (e.g., Sequelize for PostgreSQL).
    - **routes/**: API route definitions.
    - **services/**: AI/ML and other service integrations.
    - **middleware/**: Express middleware for authentication, error handling, etc.
    - **utils/**: Utility functions and helpers.
    - **app.js**: Express app setup.
    - **server.js**: Server initialization.

---

## 4. Backend and Frontend Separation

### Frontend

- **Technology Stack:**
    - **Framework**: React.js
    - **Styling**: Tailwind CSS
    - **State Management**: Redux or Context API
    - **Real-time Communication**: Socket.io-client

- **Responsibilities:**
    - User Interface and User Experience.
    - Making API calls to the backend.
    - Handling client-side routing.
    - Managing user authentication state.
    - Displaying real-time updates and notifications.

- **Key Components:**
    - **Pages**: Represent different routes/views.
    - **Components**: Reusable UI elements.
    - **Services**: Handle API communications.
    - **Utilities**: Helper functions and validation.

### Backend

- **Technology Stack:**
    - **Runtime Environment**: Node.js
    - **Framework**: Express.js
    - **Database**: PostgreSQL
    - **Real-time Communication**: Socket.io
    - **AI/ML Integration**: Python scripts or external services
    - **Authentication**: JWT (JSON Web Tokens)

- **Responsibilities:**
    - API Endpoints for frontend communication.
    - Business logic and data processing.
    - Database interactions and ORM management.
    - Authentication and authorization.
    - AI/ML functionalities like sentiment analysis, categorization.
    - Managing real-time chatrooms and notifications.

- **Key Components:**
    - **Controllers**: Handle incoming requests, interact with services.
    - **Models**: Define database schemas and ORM models.
    - **Routes**: Define API endpoints.
    - **Services**: Business logic and AI/ML integrations.
    - **Middleware**: Authentication, validation, error handling.

### Communication Between Frontend and Backend

- **RESTful APIs**: For standard CRUD operations and data retrieval.
- **WebSockets (Socket.io)**: For real-time features like chatrooms and live notifications.
- **Authentication**: JWT tokens stored in HTTP-only cookies or local storage for secure communication.

---

## 5. Performance Dashboard for Students

### Overview

The Performance Dashboard provides insights into the performance of different students regarding their grievance handling. This feature is accessible to administrators to monitor and improve the efficiency of the grievance redressal process.

### Components

1. **Dashboard Overview**
    - **Total Grievances Handled**: Number of grievances each student has submitted and their current status.
    - **Average Resolution Time**: Time taken to resolve grievances per student.
    - **Success Rate**: Percentage of grievances successfully resolved.

2. **Graphs and Charts**
    - **Bar Chart**: Number of grievances submitted by each student.
    - **Line Chart**: Resolution time trends over a period.
    - **Pie Chart**: Distribution of grievance statuses (Resolved, Pending, In Progress).

3. **Filters and Search**
    - **Date Range Picker**: Filter data based on specific time frames.
    - **Student Selector**: Choose specific students to view detailed performance.
    - **Grievance Category Filter**: Analyze performance across different categories.

4. **Detailed Tables**
    - **Grievance List**: Detailed list of grievances with columns for Student Name, Grievance Title, Status, Submission Date, Resolution Date.
    - **Export Options**: Export data in CSV or PDF formats for reporting.

### Functionality

- **Data Aggregation**: Fetch data from the backend to display aggregated statistics.
- **Real-time Updates**: Reflect real-time changes in grievance statuses.
- **Responsive Design**: Ensure the dashboard is accessible on various devices.
- **User Interactions**: Allow administrators to interact with charts and tables for deeper insights.

### Implementation

```markdown
react:src/frontend/pages/PerformanceDashboard.js
function PerformanceDashboard() {
    const [data, setData] = useState({});
    const [filters, setFilters] = useState({
        dateRange: { start: null, end: null },
        student: '',
        category: ''
    });

    useEffect(() => {
        // Fetch dashboard data based on filters
        fetchDashboardData(filters).then(response => setData(response));
    }, [filters]);

    return (
        <div className="performance-dashboard-container">
            <Sidebar />
            <div className="dashboard-content">
                <FiltersComponent filters={filters} setFilters={setFilters} />
                <Graphs />
                <DetailedTables data={data} />
            </div>
        </div>
    );
}
```


```markdown
javascript:src/frontend/services/dashboardService.js:fetchDashboardData
async function fetchDashboardData(filters) {
    try {
        const response = await axios.get('/api/dashboard', { params: filters });
        return response.data;
    } catch (error) {
        console.error('Error fetching dashboard data:', error);
        throw error;
    }
}
```


```markdown
````javascript:src/backend/controllers/dashboardController.js:getDashboardData
async function getDashboardData(req, res) {
    const { dateRange, student, category } = req.query;
    try {
        const data = await DashboardService.aggregatePerformanceData({ dateRange, student, category });
        res.status(200).json(data);
    } catch (error) {
        res.status(500).json({ message: 'Failed to fetch dashboard data.' });
    }
}
```


```markdown
javascript:src/backend/services/dashboardService.js:aggregatePerformanceData
async function aggregatePerformanceData(filters) {
    const { dateRange, student, category } = filters;
    // Build query based on filters
    let query = { /* ... */ };

    const grievances = await Grievance.findAll({ where: query });

    // Aggregate data
    const totalHandled = /* logic to calculate */;
    const avgResolutionTime = /* logic to calculate */;
    const successRate = /* logic to calculate */;
    const perStudent = /* logic to calculate */;

    return {
        totalHandled,
        avgResolutionTime,
        successRate,
        perStudent,
        // Additional aggregated data
    };
}
```


### Backend API Endpoint

```markdown
````language:backend
// src/backend/routes/dashboardRoutes.js

const express = require('express');
const router = express.Router();
const dashboardController = require('../controllers/dashboardController');
const authMiddleware = require('../middleware/authMiddleware');

router.get('/dashboard', authMiddleware.verifyAdmin, dashboardController.getDashboardData);

module.exports = router;
```


### Frontend API Integration

```markdown
````language:frontend
// src/frontend/services/dashboardService.js

import axios from 'axios';

export async function fetchDashboardData(filters) {
    try {
        const response = await axios.get('/api/dashboard', { params: filters });
        return response.data;
    } catch (error) {
        console.error('Error fetching dashboard data:', error);
        throw error;
    }
}
```


### UI Implementation

- **Graphs and Charts**: Utilize charting libraries like **Chart.js** or **Recharts** to create interactive and responsive charts.
- **Filters Component**: Allows administrators to apply various filters to the data.
- **Detailed Tables**: Implement sortable and searchable tables using libraries like **React Table**.

### Security Considerations

- **Authentication and Authorization**: Ensure that only authorized administrators can access the Performance Dashboard.
- **Data Protection**: Secure sensitive performance data and ensure compliance with data protection regulations.

---

# Conclusion

This comprehensive project plan outlines the detailed structure and workflow for the Hostel Grievance Redressal System. By following this plan, the development team can ensure a well-organized, efficient, and feature-rich application that effectively addresses the grievances of hostel residents. The integration of AI/ML functionalities will further enhance the system's capability to manage and resolve issues promptly and intelligently.