SafeX Hostel Management System — Room Allocation Module

SafeX Solutions Internship Program — Week 4 Project Submission
Individual contribution for Group 85, SafeX Solutions Internship Program.

This repository contains the standalone Room Allocation Module for the SafeX Hostel Management System (HMS). It handles automated and manual student-to-room allocations based on real-time room availability, gender constraints, block/floor preferences, roommate requests, and special accommodation rules.

Stack: React 19 (Vite), FastAPI (Python 3.11+), PostgreSQL 16, Docker Compose

---

What this module does

• Room Directory — Register and manage rooms with block, floor, room type (single, double, triple, dorm), capacity, and gender restrictions.
• Student Directory — Register students alongside detailed allocation preferences (preferred room type, block, floor, roommate requests, and special requirements).
• Auto-Allocation Engine — One-click automated engine that matches every unallocated student to optimal rooms using a multi-criteria scoring algorithm (detailed in docs/DOCUMENTATION.md).
• Manual Allocation & Vacate — Admin controls to manually override allocations, assign specific rooms, or vacate occupied rooms when students check out.
• Live Occupancy Dashboard — Real-time metrics on overall occupancy rates, block-by-block breakdown, and an interactive floor room board.

---

Tech Stack

Layer	Technology	Description
Frontend	React 19 (Vite)	Modern React with React Router v7, Tailwind CSS, Recharts, Lucide Icons
Backend	FastAPI	Async Python REST API with SQLAlchemy 2.0 ORM & Pydantic v2 schemas
Database	PostgreSQL 16	Relational database storage with relational integrity and seed generators
Containerization	Docker & Docker Compose	Multi-container setup for one-command environment deployment

---

Quick Start / Running Locally

You can run this project locally using Docker Compose (recommended) or natively (manual environment setup).

Option A — Docker Compose (Recommended)

Prerequisites: Docker Desktop or Docker Engine + Docker Compose installed.

# 1. Clone the repository
git clone <repository-url>
cd hostel-allocation

# 2. Build and launch all services (Frontend, Backend, PostgreSQL)
docker compose up --build

Services will be accessible at:

• Frontend App: http://localhost:5173
• FastAPI Backend & API Docs: http://localhost:8000/docs
• PostgreSQL Database: localhost:5432

Seed Demo Data:
To populate the database with sample rooms (30 rooms) and students (60 students):

docker compose exec backend python -m app.seed

After seeding, open http://localhost:5173 and navigate to Allocations to run the auto-allocation engine.

---

Option B — Native Local Setup

1. Database Setup

Install PostgreSQL locally and initialize the database:

CREATE DATABASE hostel_db;
CREATE USER hostel_user WITH PASSWORD 'hostel_pass';
GRANT ALL PRIVILEGES ON DATABASE hostel_db TO hostel_user;

2. Backend Setup

cd backend
python -m venv venv
source venv/bin/activate        # On Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env            # Configure DATABASE_URL if needed
python -m app.seed              # Optional: Seed demo data
uvicorn app.main:app --reload

Backend API will be running at http://localhost:8000 (Interactive Swagger docs at /docs).

3. Frontend Setup

cd frontend
npm install
cp .env.example .env            # Points VITE_API_URL at http://localhost:8000
npm run dev

Frontend web app will be running at http://localhost:5173.

---

Project Structure

hostel-allocation/
├── backend/
│   ├── app/
│   │   ├── main.py          # FastAPI application & router registration
│   │   ├── models.py        # SQLAlchemy models (Room, Student, Allocation)
│   │   ├── schemas.py       # Pydantic request & response schemas
│   │   ├── database.py      # Database engine & session management
│   │   ├── allocation.py    # Auto-allocation scoring & matching engine
│   │   ├── seed.py          # Synthetic demo data generator
│   │   └── routers/         # API endpoints (rooms, students, allocations, dashboard)
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── pages/           # Dashboard, Rooms, Students, Allocations pages
│   │   ├── components/      # UI components (Layout, RoomBoard, Stats)
│   │   └── lib/api.js       # Axios API client wrapper
│   ├── index.html
│   └── Dockerfile
├── docs/
│   ├── DOCUMENTATION.md     # Architecture design, API specs & algorithm details
│   └── PROGRESS_REPORT.md
├── audit/
│   └── report/
│       └── WEEK4-AUDIT-REPORT.md  # Detailed Week 4 Audit Evidence & Analysis
├── docker-compose.yml
└── README.md

---

Integration with Shared Group Project

This module is self-contained and manages its own domain (rooms, students, allocations). To integrate into a larger enterprise Hostel Management System:

1. Shared students table: Can map directly to an overarching student/user table by matching primary key schemas in models.py.
2. Authentication / RBAC: Designed to accept JWT bearer tokens or sitting behind an API gateway authentication layer.

---

Known Limitations

• Application-Level Allocation Constraint: Active single-allocation policy per student is checked in application code (allocation.py) to support audit history tracking.
• Development CORS Policy: Default CORS configuration (allow_origins=["*"]) allows frictionless local testing; restricted origin lists should be configured for production deployment.

---

Week 4 — Performance & Accessibility Audit

As part of the SafeX Solutions Week 4 internship deliverables, a formal performance and accessibility audit was conducted on the Room Allocation Module frontend.

Audit Overview & Methodology

• Audited Component: Frontend Application (React 19 / Vite)
• Environment: Production Docker Build (docker compose up --build), serving compiled production assets via static file server (serve on port 5173) alongside FastAPI and PostgreSQL containers.
• Audit Tools: Google Chrome Lighthouse (Automated Audit) and axe DevTools (Accessibility Testing).

Verified Audit Results

Category	Before	After
Performance	26	80
Accessibility	93	98
Best Practices	100	100
SEO	82	82
axe Issues	1 Critical	0

Note: Scores reflect measured improvements in the production Docker environment following targeted frontend optimizations. Not all potential performance optimizations were applied, but measured scores improved significantly.

Three Fixes Implemented

1. Accessible Names for Interactive Elements: Added descriptive aria-label attributes to icon-only action buttons across user interface components, resolving 1 Critical axe DevTools violation (reducing critical issues to 0) and improving accessibility to 98.
2. Google Fonts Loading Strategy: Replaced render-blocking CSS @import rules with non-blocking HTML <link rel="stylesheet"> tags accompanied by <link rel="preconnect"> hints to Google Fonts domains in index.html.
3. Scoped Layout CSS Transitions: Eliminated global transition: width layout rules, scoping width transitions exclusively to the sidebar component to prevent browser layout thrashing and boost execution speed.

Business & User Impact

• Enhanced Responsiveness: Elevating performance from 26 to 80 significantly cuts page rendering delay and layout instability, delivering a smooth admin dashboard experience.
• Inclusive Accessibility: Achieving an Accessibility score of 98 with zero critical axe issues ensures screen reader compatibility and equal access for all users.
• Production Quality: Maintaining 100% Best Practices guarantees high code quality and security standards for enterprise integration.

Audit Evidence & Documentation

Full evidence and details can be found in the audit/ directory:

• Comprehensive Audit Report: audit/report/WEEK4-AUDIT-REPORT.md

Audit Conclusion

The Week 4 audit successfully resolved key frontend performance bottlenecks and accessibility gaps. Testing in a true production Docker setup confirmed real-world gains, elevating Lighthouse Performance from 26 to 80, improving Accessibility to 98, and eliminating all critical axe DevTools issues.