🏨 HMS - Hostel Management System

IIIT Sonepat

A mobile platform for day-to-day hostel operations

  

Built with ❤️ for Indian Institute of Information Technology, Sonepat featuring QR gate passes, GPS attendance, mess management, emergency SOS & real-time notifications.

---

📱 Features

For Students

• 🎫 Digital Gate Passes - Request, track, and validate passes with QR codes
• 📍 Smart Attendance - Geofence-based attendance with a configurable time window (default 7 PM - 10 PM IST)
• 🍽️ Mess Menu & Ratings - Weekly menu with time-windowed meal ratings
• 📢 Notice Board - Real-time notices from hostel staff
• 🛠️ Complaints - Submit and track maintenance requests
• 🚨 Emergency SOS - Send SOS with location and view emergency contacts
• 🔔 Push Notifications - Real-time alerts and updates

For Parents

• 👨‍👩‍👧 Linked Children - View linked student profiles
• ✅ Gate Pass Approval - Two-tier approval (Parent → Warden)
• 📊 Attendance Tracking - Today status + history
• 🧾 Pass History - Review past gate passes
• 🔔 Notifications - Gate pass and alert updates

For Guards

• 📷 QR Scanner - Validate gate passes quickly
• 📝 Activity Logs - Entry/exit tracking
• 🚶 Students Outside - Live list of students currently out
• ✅ Recent Entries - Return tracking for today

For Wardens

• ✓ Pass Management - Approve/reject gate passes
• 📋 Student Management - Student list, detail view, attendance marking
• 📚 Pass History - Review all gate passes
• 🚨 Emergency Alerts - View active SOS alerts

For Admins

• 👥 User Management - Create and manage all user types
• 🔗 Parent-Student Linking - Link parent accounts
• ⚙️ System Configuration - Geofence, attendance windows, pass limits
• 📊 System Statistics - Users, passes, attendance, complaints, notices

---

🏗️ Architecture

Frontend (Mobile App)

Technology Stack:
├── React Native 0.81.5
├── Expo SDK 54
├── Expo Router (File-based routing)
├── TypeScript 5.9
├── TanStack Query (State management)
├── Axios (HTTP client)
└── Expo Secure Store (Token storage)

Key Features:
├── QR Code generation/scanning (expo-camera + react-native-qrcode-svg)
├── Geolocation (expo-location)
├── Push notifications (expo-notifications)
├── Dark/Light theme toggle
└── React Query caching

Backend (API Server)

Technology Stack:
├── Node.js 18+
├── Express 4.21
├── MongoDB (Mongoose 8.9)
├── Redis (ioredis) - Caching
├── TypeScript 5.9
├── JWT (jsonwebtoken)
└── PM2 (Process management)

Security:
├── Helmet (HTTP headers)
├── CORS (Origin whitelisting)
├── Rate limiting (express-rate-limit)
├── Input sanitization
├── bcrypt (Password hashing)
├── Expo Push Notifications
└── Zod (Schema validation)

---

📂 Project Structure

HMS-Mobile/
│
├── Frontend/              # React Native Mobile App
│   ├── app/              # Expo Router screens
│   │   ├── admin/       # Admin screens
│   │   ├── guard/       # Guard-specific screens
│   │   ├── parent/      # Parent portal
│   │   └── warden/      # Warden tools
│   ├── components/       # Reusable UI components
│   ├── lib/             # Core utilities
│   │   ├── api.ts       # Axios instance
│   │   ├── hooks.ts     # React Query hooks
│   │   ├── services.ts  # API service layer
│   │   └── types.ts     # TypeScript types
│   ├── app.json         # Expo configuration
│   ├── eas.json         # EAS Build configuration
│   └── package.json
│
├── Backend/              # Express API Server
│   ├── src/
│   │   ├── controllers/ # Request handlers (12 files)
│   │   ├── models/      # MongoDB schemas (12 collections)
│   │   ├── routes/      # API endpoints (12 files)
│   │   ├── middleware/  # Auth, validation, error handling
│   │   ├── services/    # Business logic (JWT, notifications)
│   │   ├── utils/       # Helpers (logger, cache, pagination)
│   │   ├── schemas/     # Zod validation schemas
│   │   └── types/       # TypeScript interfaces
│   ├── dist/            # Compiled JavaScript (production)
│   ├── ecosystem.config.js  # PM2 configuration
│   ├── .env             # Environment variables
│   └── package.json
│
└── Documentation.md      # Detailed project documentation

---

🚀 Quick Start

Prerequisites

• Node.js 18+ (Download)
• MongoDB 5+ (Local or MongoDB Atlas)
• Redis 6+ (Optional but recommended)
• Git (Download)
• Expo CLI (will be installed automatically)

Backend Setup

# 1. Clone repository
git clone <repository-url>
cd HMS-Mobile/Backend

# 2. Install dependencies
npm install

# 3. Configure environment
cp .env.example .env
# Edit .env with your values:
#   - MONGODB_URI (your MongoDB connection)
#   - JWT_SECRET (generate with: node -e "console.log(require('crypto').randomBytes(64).toString('hex'))")
#   - REDIS_URL (if using Redis)

# 4. Run development server
npm run dev

# Server starts at http://localhost:5000
# Health check: http://localhost:5000/health

Frontend Setup

# 1. Navigate to frontend
cd ../Frontend

# 2. Install dependencies
npm install

# 3. Configure API URL
# Edit .env file:
EXPO_PUBLIC_API_URL=http://YOUR_LOCAL_IP:5000/api
# Note: Use your computer's local IP (not localhost) for physical device testing

# 4. Start Expo
npx expo start

# Options:
# - Press 'a' for Android emulator
# - Press 'i' for iOS simulator (Mac only)
# - Scan QR code with Expo Go app on your phone

---

🔧 Environment Variables

Backend .env

# Server
PORT=5000
NODE_ENV=development

# MongoDB
MONGODB_URI=mongodb://localhost:27017/hms
# Or MongoDB Atlas: mongodb+srv://username:password@cluster.mongodb.net/database

# JWT
JWT_SECRET=your-super-secret-key-CHANGE-THIS
JWT_EXPIRES_IN=7d

# Redis (optional)
REDIS_URL=redis://localhost:6379

# CORS (production domains)
ALLOWED_ORIGINS=https://yourdomain.com

Frontend .env

# API Configuration
EXPO_PUBLIC_API_URL=http://192.168.1.33:5000/api

# For production:
# EXPO_PUBLIC_API_URL=https://your-backend-domain.com/api

---

📦 Building for Production

Android APK

# 1. Install EAS CLI
npm install -g eas-cli

# 2. Login to Expo
eas login

# 3. Build APK
cd Frontend
eas build --platform android --profile preview

# Wait 15-20 minutes -> Download APK -> Share with users

iOS IPA (Requires Mac + Apple Developer Account)

# Build for TestFlight
cd Frontend
eas build --platform ios --profile preview

# Submit to App Store
eas submit --platform ios

Backend Deployment (Render)

Already deployed at: https://hostel-management-system-backend-jde3.onrender.com

To deploy your own:

1. Create account at render.com
2. Connect GitHub repository
3. Add environment variables
4. Deploy with one click

---

🧪 Testing

Backend Tests

cd Backend
npm test          # Run all tests
npm run test:watch # Watch mode

API Testing

# Health Check
curl https://hostel-management-system-backend-jde3.onrender.com/health

# Login
curl -X POST https://your-backend/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"student@test.com","password":"password123"}'

---

📊 Project Statistics

Component	Files	Lines of Code
Frontend	~5,206 lines	React Native, TypeScript
Backend	~5,755 lines	Node.js, Express, TypeScript
Total	~10,961 lines	Production code

Database Collections (12 total)

• users - All user accounts (students, parents, staff)
• gatepasses - Gate pass requests
• gatepasslogs - Entry/exit activity
• attendance - Daily attendance records
• notices - Notice board posts
• complaints - Maintenance complaints
• messmenus - Weekly meal schedules
• foodratings - Meal ratings
• emergencies - SOS alerts
• notifications - In-app notifications
• parentstudents - Parent-child links
• systemconfigs - System settings

---

🔒 Security Features

✅ JWT Authentication - Secure token-based auth
✅ Password Hashing - bcrypt with salt rounds
✅ Role-Based Access Control - Student, Parent, Guard, Warden, Admin
✅ Rate Limiting - Protect against brute force (3 tiers)
✅ Input Validation - Zod schemas for all endpoints
✅ XSS Protection - Input sanitization middleware
✅ CORS Whitelisting - Configurable allowed origins
✅ Helmet Security - HTTP headers hardening
✅ Geofencing - Location-based attendance verification
✅ QR Code Security - Unique codes for gate pass validation

---

🌟 Key Highlights

• ✅ Mobile-First Design - Optimized for students on the go
• ✅ Real-Time Updates - Push notifications for instant alerts
• ✅ Smart Caching - React Query caching for faster reloads
• ✅ Dark Mode - System-aware theme switching
• ✅ Production-Ready - PM2 cluster mode, Redis caching, structured logging
• ✅ Type-Safe - Full TypeScript on frontend and backend
• ✅ Scalable Architecture - Supports 1000+ concurrent users

---

📚 Documentation

• Documentation.md - Full project breakdown
• Backend API Documentation - API endpoints reference
• Deployment Guide - Production deployment steps
• Build Testing Guide - APK/IPA build instructions

---

🛠️ Development

Running Locally

# Terminal 1 - Backend
cd Backend
npm run dev
# Server at http://localhost:5000

# Terminal 2 - Frontend
cd Frontend
npx expo start
# Scan QR with Expo Go app

Code Quality

# Backend build check
cd Backend
npm run build

# TypeScript check
npx tsc --noEmit

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License.

---

👥 Team

Developed at Indian Institute of Information Technology, Sonepat (IIIT Sonepat)

---

🆘 Support

For issues or questions:

• Check Documentation.md
• Review API docs
• Open an issue on the GitHub repository
• Contact the team at IIIT Sonepat

Built with ❤️ at IIIT Sonepat for smarter hostel management