# Hostel Management System (HMS)
[](https://laravel.com)
[](https://php.net)
[](https://mysql.com)
[](https://tailwindcss.com)
[](https://github.com/1yakub/Hostel-Management-System-HMS-/actions/workflows/laravel.yml)
[](https://github.com/1yakub/Hostel-Management-System-HMS-/actions/workflows/deploy.yml)
## ๐ Live Demo
**โจ [View Live Demo](https://hms.yakub.website/) โจ**
> **๐ Custom Domain:** `hms.yakub.website` (Professional subdomain)
> **๐ SSL Certificate:** HTTPS enabled for secure access
### Demo Credentials:
- **Staff Login:** `staff@example.com` / `password`
- **Guest Login:** `guest@example.com` / `password`
- **Test User:** `test@example.com` / `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](#-live-demo)
- [Features](#-features)
- [Technology Stack](#๏ธ-technology-stack)
- [System Architecture](#๏ธ-system-architecture)
- [Prerequisites](#-prerequisites)
- [Installation](#-installation)
- [Deployment](#-deployment)
- [User Roles & Access](#-user-roles--access)
- [Testing](#-testing)
- [Performance Metrics](#-performance-metrics)
- [Security Features](#-security-features)
- [Screenshots](#-screenshots)
- [Future Enhancements](#-future-enhancements)
- [Contact](#-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**
```bash
git clone https://github.com/1yakub/Hostel-Management-System-HMS-.git
cd Hostel-Management-System-HMS-
```
2. **Install PHP dependencies**
```bash
composer install
```
3. **Install Node.js dependencies**
```bash
npm install
```
4. **Environment setup**
```bash
cp .env.example .env
php artisan key:generate
```
5. **Configure database**
For MySQL:
```env
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):
```env
DB_CONNECTION=sqlite
DB_DATABASE=/absolute/path/to/database/database.sqlite
```
6. **Run migrations and seeders**
```bash
php artisan migrate --seed
```
7. **Build frontend assets**
```bash
npm run build
```
8. **Start the development server**
```bash
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)
```bash
# 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:
```bash
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](https://github.com/1yakub/Hostel-Management-System-HMS-/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](docs/1830968_hms_report.pdf).
## ๐ค 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*
[](mailto:1830968@iub.edu.bd)
[](https://linkedin.com/in/yakubhossain)
[](https://github.com/1yakub)
---
### ๐จโ๐ซ **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.*