🏠 HostelHub — Smart Hostel Management System

A modern, full-stack university hostel management system built on the PERN stack (PostgreSQL, Express.js, React, Node.js). HostelHub streamlines room allocations, maintenance tracking, fee management, and warden-student communication with role-based access control, real-time notifications, and a premium dark-themed UI.

---

✨ Features

🔐 Authentication & RBAC

• Secure JWT-based authentication with bcrypt password hashing
• Role-based access: Student, Warden, Admin
• Protected routes on both frontend and backend

🏢 Hostel & Room Management

• Full CRUD for hostels and rooms
• Real-time occupancy tracking
• Room availability toggles and capacity management

🛏️ Smart Room Allocation

• Students browse and apply for available rooms with live filtering
• Wardens review, approve, or reject allocation requests
• Automatic capacity management on approval
• Roommate compatibility scoring based on student preferences

🔧 Maintenance Ticket System

• Students file digital maintenance tickets with categories and urgency levels
• Wardens manage tickets in a Kanban-style pipeline (Pending → In Progress → Resolved)
• Real-time status tracking with instant notifications

📊 Analytics Dashboard

• Occupancy rates by hostel (donut charts)
• Maintenance distribution by category (bar charts)
• Payment status breakdowns
• Monthly trend visualizations

🔔 Real-Time Notifications

• Socket.io-powered instant notifications
• Polling-based fallback
• In-app notification center with unread badges

💰 Fee Management

• Payment tracking per semester
• Status management (Pending, Paid, Overdue, Refunded)
• Revenue analytics

---

🛠 Tech Stack

Layer	Technology
Frontend	React 18, Vite, Tailwind CSS 3, Recharts
Backend	Express.js, Node.js, Socket.io
Database	PostgreSQL with strict relational schemas
Auth	JWT (JSON Web Tokens), bcryptjs
Validation	Zod schema validation

---

📁 Project Structure

Hostel Management/
├── server/              # Express.js API
│   ├── db/              # SQL schema & seed data
│   ├── src/
│   │   ├── config/      # DB pool, environment
│   │   ├── controllers/ # Business logic
│   │   ├── middleware/   # Auth, validation, errors
│   │   ├── routes/       # API route definitions
│   │   ├── validators/   # Zod schemas
│   │   ├── utils/        # Helper functions
│   │   └── server.js     # Entry point
│   └── package.json
│
├── client/              # React (Vite) SPA
│   ├── src/
│   │   ├── api/         # Axios API modules
│   │   ├── components/  # Shared UI components
│   │   ├── context/     # Auth & Notification providers
│   │   ├── hooks/       # Custom React hooks
│   │   ├── pages/       # Page components
│   │   ├── utils/       # Formatters & helpers
│   │   ├── App.jsx      # Router & providers
│   │   └── main.jsx     # Vite entry
│   └── package.json
│
└── README.md

---

🚀 Getting Started

Prerequisites

• Node.js v18+ and npm
• PostgreSQL v14+

1. Clone & Install

# Install server dependencies
cd server
npm install

# Install client dependencies
cd ../client
npm install

2. Database Setup

# Create the database
psql -U postgres -p 5433 -c "CREATE DATABASE hostel_mgmt;"

# Run schema
psql -U postgres -p 5433 -d hostel_mgmt -f server/db/schema.sql

# Seed with mock data
psql -U postgres -p 5433 -d hostel_mgmt -f server/db/seed.sql

3. Configure Environment

Copy server/.env.example to server/.env and update your PostgreSQL credentials.

4. Run the Application

# Terminal 1: Start backend
cd server
npm run dev

# Terminal 2: Start frontend
cd client
npm run dev

• Backend API: http://localhost:5000
• Frontend App: http://localhost:5173

---

🔑 Test Accounts

Role	Email	Password
Admin	admin@hostel.edu	password123
Warden	anil.warden@hostel.edu	password123
Student	amit@student.edu	password123

---

📡 API Endpoints

Method	Endpoint	Auth	Description
POST	/api/auth/register	—	Register new user
POST	/api/auth/login	—	Login
GET	/api/auth/me	JWT	Get current user
GET	/api/hostels	JWT	List hostels
POST	/api/hostels	Admin	Create hostel
GET	/api/rooms	JWT	List rooms (with filters)
POST	/api/rooms	Admin	Create room
GET	/api/allocations	JWT	List allocations
POST	/api/allocations	JWT	Submit allocation request
PUT	/api/allocations/:id/approve	Admin	Approve allocation
PUT	/api/allocations/:id/reject	Admin	Reject allocation
GET	/api/maintenance	JWT	List maintenance requests
POST	/api/maintenance	JWT	File maintenance ticket
PUT	/api/maintenance/:id	Admin	Update ticket status
GET	/api/analytics/overview	Admin	Dashboard statistics
GET	/api/notifications	JWT	Get user notifications
GET	/api/payments	JWT	List payments

---

📄 License

This project is built for educational purposes.