Hostel Management System (HMS)

🚀 Live Demo

✨ View Live Demo ✨

🌐 Custom Domain: hms.yakub.website (Professional subdomain)
🔒 SSL Certificate: HTTPS enabled for secure access

Demo Credentials:

• Staff Login: [email protected] / password
• Guest Login: [email protected] / password
• Test User: [email protected] / password

---

A comprehensive web-based hostel management solution developed during an internship at Varygen Corp Ltd. This system streamlines hostel operations through automated booking management, room tracking, and integrated payment processing.

🏢 Project Overview

Developer: Md Yakub Hossain
Student ID: 1830968
Institution: Independent University, Bangladesh
Company: Varygen Corp Ltd
Duration: Spring 2025 (3 months)
Academic Supervisor: Razib Hayat Khan, Ph.D.
Industry Supervisor: Bimasha Zaman (CEO, Varygen Corp Ltd)

📋 Table of Contents

• Live Demo
• Features
• Technology Stack
• System Architecture
• Prerequisites
• Installation
• Deployment
• User Roles & Access
• Testing
• Performance Metrics
• Security Features
• Screenshots
• Future Enhancements
• Contact

✨ Features

🔐 Authentication & Authorization

• Secure user authentication with Laravel Breeze
• Role-based access control (Admin, Staff, Guest)
• Password reset and email verification
• Session management with timeout

🏠 Room Management

• Real-time room inventory tracking
• Dynamic pricing and availability updates
• Room maintenance status management
• Amenities tracking through JSON storage
• Room type categorization

📅 Booking System

• Advanced booking management with date validation
• Check-in/check-out processing
• Room availability checking
• Booking modification and cancellation
• Special requests handling

💳 Payment Processing

• Secure payment tracking and verification
• Automated invoice generation
• Payment history maintenance
• Financial transaction reporting

👥 Guest Management

• Guest registration and profiling
• Document verification system
• Contact information management
• Guest history tracking

📊 Reporting & Analytics

• Occupancy and revenue reports
• Performance metrics dashboard
• Business intelligence features
• Real-time operational statistics

🛠️ Technology Stack

Backend

• Framework: Laravel 11.x
• Language: PHP 8.2+
• Database: MySQL/SQLite
• ORM: Eloquent
• Authentication: Laravel Breeze

Frontend

• Markup: HTML5
• Styling: Tailwind CSS with custom luxury theme
• Scripting: JavaScript, Alpine.js
• Build Tool: Vite
• Responsive Design: Mobile-first approach

Development Tools

• Dependency Management: Composer, npm
• Version Control: Git
• Testing: PHPUnit
• CI/CD: GitHub Actions (auto-testing and deployment)
• Code Standards: PSR-12

🏗️ System Architecture

The HMS follows a modern MVC architecture pattern:

• Model Layer: Database interactions and business logic using Eloquent ORM
• View Layer: Blade templates with responsive Tailwind CSS components
• Controller Layer: RESTful controllers for request handling

Key Design Patterns

• MVC (Model-View-Controller)
• Repository Pattern through Eloquent
• Middleware Pattern for authentication
• Dependency Injection via Laravel's service container

📋 Prerequisites

• PHP >= 8.2
• Composer
• Node.js & npm
• MySQL >= 5.7 (or SQLite for development)
• Web server (Apache/Nginx)

🚀 Installation

1. Clone the repository

   git clone https://github.com/1yakub/Hostel-Management-System-HMS-.git
   cd Hostel-Management-System-HMS-

2. Install PHP dependencies

   composer install

3. Install Node.js dependencies

   npm install

4. Environment setup

   cp .env.example .env
   php artisan key:generate

5. Configure database

   For MySQL:

   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=hostel_management
   DB_USERNAME=your_username
   DB_PASSWORD=your_password

   For SQLite (default):

   DB_CONNECTION=sqlite
   DB_DATABASE=/absolute/path/to/database/database.sqlite

6. Run migrations and seeders

   php artisan migrate --seed

7. Build frontend assets

   npm run build

8. Start the development server

   php artisan serve

Visit http://localhost:8000 to access the application.

🚀 Deployment

This project includes automatic deployment to production. When you push to the main branch:

1. Tests run automatically (25 tests, takes ~3 minutes)
2. If tests pass, the code deploys to the live server automatically
3. Website updates without any manual work

The deployment handles composer updates, asset building, database migrations, and server restart. Pretty neat for a student project!

Live demo: https://hms.yakub.website

Manual Deployment (if needed)

# SSH to your server
ssh user@your-server

# Pull changes and update
git pull origin main
composer install --no-dev
npm run build
php artisan migrate --force

👤 User Roles & Access

Administrator

• Complete system oversight
• User management
• Financial reporting
• System configuration

Staff Members

• Daily operational management
• Guest service coordination
• Room and facility maintenance
• Booking management

Guests

• Online booking and payment
• Service requests
• Stay management
• Profile updates

🧪 Testing

Run the test suite:

php artisan test

Test Coverage

• Authentication testing
• Room management operations
• Booking system functionality
• Payment processing
• API endpoints

🔄 CI/CD Pipeline

This project includes automated GitHub Actions workflow that:

• ✅ Runs automatically on every push/pull request to main
• 🐘 Tests with PHP 8.2 and Laravel 11
• 🗃️ Uses SQLite for fast testing
• 📦 Installs dependencies (Composer & NPM)
• 🧪 Executes all tests (PHPUnit/Pest)
• 🎨 Builds frontend assets (Vite/Tailwind)
• 📊 Reports status via GitHub badge

View CI/CD Results: GitHub Actions

📊 Performance Metrics

• Response Time: < 2 seconds average page load
• Concurrent Users: Successfully tested with 100+ simultaneous users
• Database Operations: < 100ms average query execution
• API Response: < 200ms REST endpoint response time

🔒 Security Features

• XSS protection
• CSRF token verification
• SQL injection prevention
• Role-based access control
• Data encryption for sensitive information
• Session security with timeout

📱 Screenshots

🏠 Landing Page

Modern, responsive landing page with room showcase and booking interface

📊 Staff Dashboard

Comprehensive dashboard with real-time statistics and quick actions

🏨 Room Management

Intuitive room management interface with status tracking

📅 Booking Interface

User-friendly booking system with date validation and room selection

🚧 Future Enhancements

Technical Improvements

• Mobile application development (iOS/Android)
• AI-powered room recommendations
• Advanced analytics with predictive modeling
• Real-time chat support
• Third-party booking platform integration

Business Features

• Loyalty program integration
• Dynamic pricing system
• Multi-language support
• Advanced reporting tools

📄 Project Documentation

For detailed technical documentation, please refer to the full internship report.

🤝 Contributing

This project was developed as part of an academic internship. For educational purposes and learning:

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 developed for academic and learning purposes. Please contact the author for usage permissions.

📞 Contact

👨‍💻 Md Yakub Hossain

Computer Science & Engineering Student
Independent University, Bangladesh

---

👨‍🏫 Academic Supervisor

Razib Hayat Khan, Ph.D.
Associate Professor, CSE Department
Independent University, Bangladesh

---

👩‍💼 Industry Supervisor

Bimasha Zaman
CEO, Varygen Corp Ltd

🙏 Acknowledgments

• Varygen Corp Ltd for providing the internship opportunity
• Bimasha Zaman (CEO, Varygen Corp Ltd) for industry guidance and mentorship
• Razib Hayat Khan, Ph.D. for academic supervision and support
• Independent University, Bangladesh for academic framework and resources
• Department of Computer Science & Engineering for comprehensive education

📈 Project Stats

---

⭐ Star this repository if you found it helpful!

This system was developed as part of an undergraduate internship program and demonstrates the practical application of modern web development technologies in solving real-world business challenges.