🏠 HostelGatePassForm

HostelGatePassForm is a comprehensive hostel management system that automates the gate pass request and approval workflow for educational institution hostels.

The system provides role-based access control for Students, Floor-in-Charge staff, and Administrators, enabling efficient management of hostel operations and gate pass requests.

---

✨ Features

👥 User Management

• Student Registration & Profile Management: Complete student information with room assignments
• Floor-in-Charge Management: Staff administration for floor supervision
• Admin Dashboard: System-wide oversight and user management
• Role-based Access Control: Secure authentication with JWT tokens

🎫 Gate Pass Management

• Gate Pass Requests: Students can submit leave requests with dates and reasons
• Approval Workflow: Floor-in-Charge can approve/reject gate pass requests
• Status Tracking: Real-time status updates (PENDING, APPROVED, REJECTED)
• HOD Letter Upload: Upload approval letters for verification

🏢 Hostel Management

• Room Management: Room allocation and capacity management
• Floor Type Configuration: Different floor types and blocks
• Student-Room Assignment: Automated room assignment system

🔐 Security Features

• JWT Authentication with refresh tokens
• Password Recovery: OTP-based password reset via email
• Image Upload: Secure student profile image management
• HTTP-Only Cookies: Enhanced token security

---

🛠 Technology Stack

Backend

• Framework: Spring Boot 3.2.5
• Security: Spring Security + JWT (0.11.5)
• Database: MySQL (Production) / H2 (Testing)
• ORM: Spring Data JPA
• Email: Spring Mail for OTP delivery
• Validation: Bean Validation
• Build Tool: Maven
• Java: 17 / 21

Frontend

• Framework: React 19.1.0
• Build Tool: Vite 7.0.0
• Routing: React Router DOM 7.6.3
• UI Components: React Icons 5.5.0
• Notifications: React Toastify 11.0.5
• Authentication: JWT Decode 4.0.0

---

🏗 System Architecture

• Frontend Layer: React SPA with component-based architecture
• API Layer: RESTful controllers with role-based endpoints
• Security Layer: JWT authentication and authorization
• Service Layer: Business logic implementation
• Data Layer: JPA repositories with MySQL database

---

⚙️ Prerequisites

• Java: JDK 17+
• Node.js: v16+
• MySQL: v8.0+
• Maven: Installed or use wrapper

---

🚀 Installation & Setup

1) Clone the Repository

git clone https://github.com/rgl456/HostelGatePassForm.git
cd HostelGatePassForm

2) Database Setup

Create a MySQL database and note the JDBC URL, username, and password.

3) Environment Configuration

Configure environment variables (recommended via OS env or .env/application.properties as you prefer).

Backend (examples):

# application.properties (Spring Boot)
spring.datasource.url=${DB_URL}
spring.datasource.username=${DB_USERNAME}
spring.datasource.password=${DB_PASSWORD}

jwt.secret=${SECRET_KEY}
jwt.expiration=${JWT_EXPIRATION}
jwt.refresh.expiration=${JWT_REFRESH_EXPIRATION}

spring.mail.host=${MAIL_HOST}
spring.mail.port=${MAIL_PORT}
spring.mail.username=${MAIL_USERNAME}
spring.mail.password=${MAIL_PASSWORD}

app.otp.expired-seconds=${OTP_EXPIRED_SECONDS}

Required Variables:

• DB_URL – MySQL JDBC URL
• DB_USERNAME – DB user
• DB_PASSWORD – DB password
• SECRET_KEY – JWT secret
• JWT_EXPIRATION – Access token TTL (ms)
• JWT_REFRESH_EXPIRATION – Refresh token TTL (ms)
• MAIL_HOST, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD – SMTP config
• OTP_EXPIRED_SECONDS – OTP expiry seconds

4) Backend Setup

# Using Maven wrapper (recommended)
./mvnw clean install
./mvnw spring-boot:run

# Or using installed Maven
mvn clean install
mvn spring-boot:run

Default API base URL: http://localhost:8080

5) Frontend Setup

cd client
npm install
npm run dev

Default dev URL: http://localhost:5173

---

🔌 API Endpoints

Base path: /api/v1

AuthController

• POST /login – User authentication
• POST /refresh-token – Token refresh
• POST /logout – User logout
• POST /register/students – Student registration
• POST /register/floor-in-charges – Floor-in-Charge registration
• POST /register/admins – Admin registration

StudentController

• PUT /students/{studentId}/profile – Update own profile
• PUT /students/{studentId}/profile/update – Admin/FIC profile update
• GET /students/me/profile – Get current student profile
• GET /students/{studentId} – Get student by ID
• GET /students/room/{roomNo} – Get students by room no
• GET /students – Get all students
• POST /students/me/upload-image – Upload image
• GET /students/{studentId}/profile-image – View profile image

GatePassRequestController

• POST /gate-passes – Create gate pass request
• GET /gate-passes – Get all (Admin only)
• PUT /gate-passes/{id} – Update gate pass request
• GET /gate-passes/floor-in-charge – By FIC
• GET /gate-passes/student – By student
• GET /gate-passes/filter-by-status – Filter by status
• PUT /gate-passes/{id}/update-status – Update status

FloorInChargeController

• PUT /floor-in-charges/me/profile – Update FIC profile
• GET /floor-in-charges/me/students – Assigned students
• GET /floor-in-charges/{id}/students – Students for a FIC
• GET /floor-in-charges/me/profile – Current FIC profile
• GET /floor-in-charges/{id} – Get FIC by ID
• GET /floor-in-charges – Get all
• DELETE /floor-in-charges/{id} – Delete FIC

RoomController

• POST /rooms – Create room
• POST /rooms/bulk-add – Add multiple rooms
• GET /rooms/{roomNo} – Get room by number
• GET /rooms – Get all rooms
• PUT /rooms/{roomNo} – Update room
• DELETE /rooms/{roomNo} – Delete room

FloorTypeController

• POST /floor-types – Create floor type
• GET /floor-types – Get all
• PUT /floor-types/{id}/assign-floor-in-charge – Assign FIC
• DELETE /floor-types/{id} – Delete floor type
• GET /floor-types/all/block – Get all blocks
• GET /floor-types/all/floor – Get all floors

ForgotPasswordController

• POST /forgot-password/{email} – Verify email & send OTP
• POST /forgot-password/verify-otp/{otp}/{email} – Verify OTP
• POST /forgot-password/reset/{email} – Reset password

---

🗂 Project Structure

Backend

src/main/java/com/project/HostelGatePassForm/
├── config/         # Configuration classes
├── controller/     # REST controllers
├── dto/            # Data Transfer Objects
├── exceptions/     # Custom exceptions
├── jwt/            # JWT utilities
├── mapper/         # Entity-DTO mappers
├── model/          # Entity classes and enums
├── repository/     # JPA repositories
├── security/       # Security configuration
├── service/        # Business logic services
└── HostelGatePassFormApplication.java

Frontend

client/src/
├── auth/           # Authentication components
├── components/     # Reusable UI components
├── data/           # Static data and constants
├── pages/          # Page components
├── styles/         # CSS styles
├── App.jsx         # Main application component
└── main.jsx        # Application entry point

---

🔐 Security Overview

Authentication Flow

1. Users log in with email/password
2. Server issues JWT access & refresh tokens in HTTP-only cookies
3. Access token used for protected endpoints
4. Refresh token provides extended sessions

Role Permissions

Role	Permissions
STUDENT	Create/update own gate passes, manage own profile
FLOOR_IN_CHARGE	Approve/reject gate passes, manage assigned students
ADMIN	Full access: user management, rooms & floor types, system configuration

---

📱 Usage

For Students

• Register and complete profile (with room assignment)
• Upload profile image
• Submit gate pass requests (dates, reasons)
• Track request status

For Floor-in-Charge

• Log in with FIC credentials
• View assigned students
• Review & approve/reject gate pass requests
• Manage floor operations

For Administrators

• Access admin dashboard
• Manage users (students, FIC, admins)
• Configure rooms & floor types
• Monitor system-wide activity

---

🔧 Development

Build

# Backend
./mvnw clean package

# Frontend
cd client
npm run build

Run Tests

# Backend tests
./mvnw test

# Frontend (lint)
cd client
npm run lint

---

📝 Configuration Notes

• File uploads are stored in: E:/uploads/
• Database schema is auto-updated via Hibernate DDL
• Email service requires valid SMTP configuration for OTP delivery
• JWT tokens are stored in secure HTTP-only cookies

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch (feat/your-feature)
3. Make your changes + add tests if applicable
4. Submit a Pull Request 🚀

---

📜 License

This project is licensed under the Apache License 2.0.

You are free to use, modify, and distribute this project under the terms of the license.
However, you must preserve copyright notices and include a copy of the license in any redistribution.

👉 See the LICENSE file for full details.

---

Note: This is a Spring Boot application with a React frontend. Ensure all environment variables are properly configured before running the application.