Smart Hostel Management System

A comprehensive full-stack web platform designed to digitize and streamline hostel facility management. It replaces informal complaint methods with a structured, accountable, and traceable digital system.

Overview

The Smart Hostel Management System enables students to report issues, track status in real-time, and receive updates on announcements. Management can view all issues, assign tasks to staff, generate reports, and post announcements.

Tech Stack

Frontend

• Framework: Next.js 16 (React 19)
• Language: TypeScript
• Styling: Tailwind CSS
• State Management: Zustand
• Data Fetching: TanStack Query
• Forms: React Hook Form + Zod
• UI Components: Radix UI
• Real-time: Socket.io Client

Backend

• Runtime: Node.js
• Framework: Express.js
• Language: TypeScript
• Database: PostgreSQL with Prisma ORM
• Cache: Redis
• Authentication: Passport.js (Local + Google OAuth)
• File Storage: Cloudinary
• Real-time: Socket.io
• Validation: Zod

Features

User Management

• User registration and authentication
• Role-based access control (Student, Staff, Management)
• Profile management
• Password reset functionality

Issue Tracking

• Create, view, and track issues
• Image and document attachments
• Status updates and tracking
• Priority-based handling
• Category-based organization

Announcements

• Create and manage announcements
• Target-specific hostels, blocks, and roles
• Priority announcements
• Mark as read tracking

Lost & Found

• Report lost items
• Claim found items
• Verification process
• Status tracking

Analytics

• Issue statistics and trends
• Category-wise breakdown
• Resolution time metrics
• Visual dashboards

Notifications

• Real-time notifications
• Email notifications
• In-app notification center

Project Structure

├── hostel-backend/          # Backend API server
│   ├── src/
│   │   ├── config/         # Configuration files
│   │   ├── modules/        # Feature modules
│   │   │   ├── auth/       # Authentication
│   │   │   ├── issues/     # Issue management
│   │   │   ├── announcements/  # Announcements
│   │   │   ├── lost-found/    # Lost & Found
│   │   │   ├── notifications/  # Notifications
│   │   │   └── analytics/     # Analytics
│   │   └── shared/         # Shared utilities
│   └── prisma/             # Database schema
│
├── hostel-frontend/         # Next.js frontend
│   ├── src/
│   │   ├── app/           # Next.js App Router pages
│   │   ├── components/    # Reusable components
│   │   ├── store/         # Zustand stores
│   │   ├── lib/           # Utilities
│   │   └── types/         # TypeScript types
│
└── README.md               # This file

Getting Started

Prerequisites

• Node.js 20+
• PostgreSQL 15+
• Redis 7+

Backend Setup

cd hostel-backend

# Install dependencies
npm install

# Copy environment file
cp .env.example .env
# Edit .env with your database and service credentials

# Generate Prisma client
npm run prisma:generate

# Run database migrations
npm run prisma:migrate

# Start development server
npm run dev

Backend runs on http://localhost:5000

Frontend Setup

cd hostel-frontend

# Install dependencies
npm install

# Copy environment file
cp .env.local.example .env.local
# Edit .env.local with your API URL

# Start development server
npm run dev

Frontend runs on http://localhost:3000

Environment Variables

Backend (.env)

NODE_ENV=development
PORT=5000
DATABASE_URL=postgresql://user:password@localhost:5432/hostel
REDIS_URL=redis://localhost:6379
JWT_SECRET=your-secret-key
CLOUDINARY_CLOUD_NAME=xxx
CLOUDINARY_API_KEY=xxx
CLOUDINARY_API_SECRET=xxx
GOOGLE_CLIENT_ID=xxx
GOOGLE_CLIENT_SECRET=xxx
FRONTEND_URL=http://localhost:3000
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=xxx
EMAIL_PASS=xxx

Frontend (.env.local)

NEXT_PUBLIC_API_URL=http://localhost:5000/api/v1
NEXT_PUBLIC_SOCKET_URL=http://localhost:5000
NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME=xxx

Available Scripts

Backend

Command	Description
npm run dev	Start development server
npm run build	Build for production
npm run start	Start production server
npm run prisma:generate	Generate Prisma client
npm run prisma:migrate	Run database migrations
npm run typecheck	Check TypeScript

Frontend

Command	Description
npm run dev	Start development server
npm run build	Build for production
npm run start	Start production server
npm run lint	Run ESLint

API Endpoints

Authentication

• POST /api/v1/auth/register - User registration
• POST /api/v1/auth/login - User login
• POST /api/v1/auth/logout - User logout
• GET /api/v1/auth/google - Google OAuth
• POST /api/v1/auth/forgot-password - Request password reset
• POST /api/v1/auth/reset-password - Reset password

Issues

• GET /api/v1/issues - List issues
• POST /api/v1/issues - Create issue
• GET /api/v1/issues/:id - Get issue details
• PATCH /api/v1/issues/:id - Update issue
• PATCH /api/v1/issues/:id/status - Update issue status
• DELETE /api/v1/issues/:id - Delete issue

Announcements

• GET /api/v1/announcements - List announcements
• POST /api/v1/announcements - Create announcement
• GET /api/v1/announcements/:id - Get announcement
• PATCH /api/v1/announcements/:id - Update announcement
• DELETE /api/v1/announcements/:id - Delete announcement

Lost & Found

• GET /api/v1/lost-found - List items
• POST /api/v1/lost-found - Report lost/found item
• GET /api/v1/lost-found/:id - Get item details
• PATCH /api/v1/lost-found/:id - Update item
• POST /api/v1/lost-found/:id/claim - Claim item

Analytics

• GET /api/v1/analytics/issues - Issue analytics
• GET /api/v1/analytics/dashboard - Dashboard stats

Notifications

• GET /api/v1/notifications - Get notifications
• PATCH /api/v1/notifications/:id/read - Mark as read
• DELETE /api/v1/notifications/read-all - Mark all as read

User Roles

Role	Description
STUDENT	Can report issues, view announcements
STAFF	Can view and resolve assigned issues
MANAGEMENT	Full access to all features

License

ISC