Hostel Management System

What you need to run HMS on your computer.

Technology Stack

Activating your copy of HMS before first use.

The very first time you open HMS, you will see the Activation Screen. This is a security gate that verifies your license before allowing access to the software. HMS uses a combination of AES encryption and SHA-based machine binding to protect your license.

Activation Options

License Security Details

Creating the main administrator account — done only once on fresh install.

After activation, HMS checks whether any user accounts exist. On a fresh installation, it takes you directly to the Admin Registration page. This is where you create the primary administrator account for your hostel system.

Registration Form Fields

1. Fill All Required Fields

   Enter your full name, choose a unique username, set a strong password, and provide your email and a recovery word you will remember.

2. Click Register

   HMS validates all fields. If anything is missing or passwords don't match, an error message guides you to fix it.

3. Account Created

   Your admin account is created instantly in the local database. HMS moves automatically to the Hostel Registration step.

Setting up your hostel profile — the foundation of all reports and invoices.

Immediately after creating your admin account, HMS takes you to Hostel Registration. Before managing anything, the system needs to know which hostel it is running for. This information appears on all invoices, receipts, and official reports.

Hostel Profile Fields

Accessing your account and leaving it securely.

Logging In

After initial setup, HMS shows the Login Screen every time the application is opened. Enter your username and password, then click Login.

1. Enter Username

   Type the username you registered with. Usernames are case-sensitive.

2. Enter Password

   Type your password. Characters are hidden for security.

3. Click Login

   HMS verifies your credentials against the local database. If correct, the dashboard loads immediately.

4. Role-Based Access Applied

   Based on your role (Admin / Manager / Staff), the sidebar shows only the menu items you are permitted to access.

Forgot Password

If you forget your password, click Forgot Password on the login screen.

Logging Out

Your hostel command center — everything at a glance.

After login, HMS takes you directly to the Dashboard. This is a live overview of your hostel's current status, updated in real time from the database every time you refresh.

Dashboard Layout

Summary Statistics Shown

Charts & Graphs

The dashboard uses Matplotlib to render interactive charts directly inside the application:

Sidebar Navigation

The dark sidebar on the left is your navigation hub. Click any menu item to switch modules instantly. The sidebar can be collapsed by clicking the ☰ Main Menu button — giving you more screen space when working on data entry.

Register, manage, and track every student in your hostel.

The Students module is the central record of every person who lives (or has lived) in your hostel. All other operations — allocations, payments, invoices, checkouts — are linked back to a student profile.

Student List View

The main Students page shows a table with all registered students. Each row displays:

Adding a New Student

1. Click "➕ Add Student"

   Opens the Add Student form.

2. Fill Personal Information

   Full Name, Father's Name, Date of Birth, Age, Gender, National ID (CNIC), Phone Number, Email Address.

3. Emergency Contact

   Name, relationship (e.g., Father, Mother), and contact number of the person to call in an emergency.

4. Academic Information

   College / University, Year of Study, Roll Number.

5. Upload Photo (Optional)

   Click the photo area to upload a profile picture from your computer. Supported formats: JPG, PNG.

6. Click Save

   The student is saved to the database with status "Inactive". Their status becomes "Active" once they are allocated a room.

Editing a Student

Select any student in the table, then click "✏ Edit Student". All fields are editable. Click Save to update the record.

Searching Students

Type any name, phone number, or ID into the Search bar and click 🔍 Search. Results filter instantly. Click ⟳ Refresh to show all students again.

Viewing Student Details (Admin/Manager)

Select a student and click "👁 View Detail" to see their complete profile including photo, all personal information, allocation history, and payment summary.

Deleting a Student (Admin/Manager)

Student Status Values

Managing your hostel's physical space with a three-level hierarchy.

HMS uses a three-level structure to organize your hostel space: Room Types → Rooms → Beds. This allows complete flexibility — from basic single rooms to large dormitories.

Step 1 — Setting Up Room Types

Before adding rooms, define your room categories. Go to Rooms → Room Types.

Step 2 — Adding Rooms

After creating room types, add individual rooms. Go to Rooms → Rooms.

Step 3 — Adding Beds

Within each room, register individual beds. Go to Rooms → Beds.

Bed Status Meanings

Managing food service costs as part of monthly fees.

The Meal Plans module lets you define different meal packages that students can be subscribed to. Meal plan costs are automatically added to a student's monthly fee during allocation.

Adding a Meal Plan

Navigate to Meal Plans from the sidebar and click Add Meal Plan.

How Meal Plans Work in Allocations

Officially assigning students to rooms and beds — the core workflow of HMS.

An Allocation is the formal assignment of a student to a specific bed in a specific room. This is what makes a student "Active" and starts their financial tracking. All payments, invoices, and checkout processes are linked to an allocation.

Creating a New Allocation

1. Navigate to Allocations

   Click "📋 Allocations" in the sidebar, then click "Allocate Now".

2. Select the Student

   Choose from the dropdown list of registered students. Only students not currently allocated are shown.

3. Choose Room Type

   Select the category of room (e.g., Single, Double Sharing). This filters the available rooms.

4. Select Room & Bed

   Only available rooms and beds are shown. Choose the specific room number and then the specific bed within that room.

5. Choose Meal Plan

   Select a meal plan (or "No Meals" if none). The monthly total updates automatically.

6. Set Check-In Date

   Use the calendar picker to select the date the student moves in. Defaults to today.

7. Set Expected Checkout Date

   Optional — if you know when the student will leave.

8. Review Monthly Charges

   The system shows the total monthly fee: Room Rent + Meal Plan + any additional charges or discounts you add.

9. Confirm Allocation

   Click "Confirm Allocation". The student status changes to Active, the bed status changes to Occupied, and fee tracking begins.

Allocation Management Page

The Allocation Management page shows all active and historical allocations in a table.

Viewing Allocation Details

Click on any allocation in the list to see its full detail page — including payment history, total paid, outstanding balance, and the complete breakdown of all charges since move-in date.

Advance reservations — hold a room before the student arrives.

The Bookings module allows you to reserve a specific bed for a student who will arrive on a future date. This is especially useful for students coming from out of town who need to confirm their room in advance.

Three Types of Bookings

Creating a Booking — Step by Step

1. Open Booking from Students Page

   Select a student from the Students list and click "📌 Pre Booking". Alternatively, access from the Bookings menu.

2. Booking Date (Locked)

   The booking date is always set to today automatically. It cannot be changed — this is a security feature to ensure accurate records.

3. Set Allocation/Arrival Date

   Use the calendar to pick the date the student will actually arrive and move in. Can be any future date.

4. Select Room Type, Room & Bed

   Choose the desired room type, then the specific room and bed. Only available beds are shown.

5. Select Meal Plan

   Choose the meal plan the student will be on after moving in.

6. Choose Booking Mode

   Select Pre Book, Confirm Book, or Paid Book. If Paid Book is selected, enter the advance amount paid.

7. Save Booking

   Click Save. The student status and bed status update immediately. The booking is now visible in the Bookings management page.

Converting a Booking to an Allocation

When the booked student arrives on their date:

1. Go to Students

   Find the student (they will show as "Pre Booked", "Confirm Booked", or "Paid Booked").

2. Select the Student

   Click on their row. A contextual "🛏 Allocate Now" button appears at the top of the page.

3. Click Allocate Now

   The booking details are pre-filled into the allocation form. Confirm and the booking converts to an active allocation. Any advance paid is recorded in their payment history.

Cancelling or Editing a Booking

Navigate to Bookings in the sidebar. Select the booking, then use the Edit or Cancel/Refund options. Cancelling a booking releases the bed back to "Available" status. This action is restricted to Admin and Manager roles.

Recording and tracking every fee payment from your students.

The Payments module is your financial ledger. Every time a student pays their monthly fee, you record it here. HMS keeps a running balance for each student — showing exactly how much they've paid and how much is still due.

Payment Page Layout

Recording a Payment

1. Search for the Student

   Use the search field to find the student by name or ID. Select them to load their allocation and balance details.

2. View Pending Fees

   The "Pending Fees" panel shows all outstanding monthly fees — which months are due and the total amount owed.

3. Enter Payment Details

   Fill in: Amount Paid, Payment Date (calendar picker), Payment Method (Cash / Bank Transfer / Online / Cheque), and optional Remarks.

4. Submit Payment

   Click the payment button. An invoice number is auto-generated (format: INV-YYYYMMDDHHMMSS-XXXX) and the payment is recorded instantly.

5. Print Receipt (Optional)

   After recording, you can immediately print or save the payment receipt / invoice as PDF.

Payment Methods Supported

Viewing Payment History

The "Payment Receipts" section shows every payment ever made for the selected student — date, amount, method, invoice number, and who recorded it. Full financial transparency for every student.

Professional receipts for every payment — printable and PDF-ready.

The Invoices module lets you view, generate, and print professional invoices for all student payments. An invoice is automatically created every time a payment is recorded.

What's Included on an HMS Invoice

Generating & Printing an Invoice

1. Go to Invoices

   Click "📄 Invoices" in the sidebar. All invoices are listed with date, student name, amount, and invoice number.

2. Search or Filter

   Find a specific invoice by student name, invoice number, or date range.

3. Select an Invoice

   Click on any invoice to open the full preview.

4. Print or Save as PDF

   Click Print to send to a physical printer, or save as PDF to share digitally with the student (email, WhatsApp, etc.).

Processing a student's departure from the hostel — complete and official.

The Checkout module handles the complete process when a student leaves your hostel. It calculates their final balance, processes any last payments, and formally ends their allocation — releasing their bed for new students.

Checkout Process — Step by Step

1. Open Checkout

   Click "📦 Checkout" in the sidebar. The page shows two panels: Active Allocations (left) and Checkout Summary (right).

2. Search and Select Student

   Use the search bar to find the departing student, or scroll through the Active Allocations list. Click their row to load their details.

3. Review Financial Summary

   The right panel shows: Total Rent Due (from allocation start to today), Total Amount Paid, Outstanding Balance, and any advance deposit paid.

4. Record Final Payment (if any)

   If the student owes a balance, record their final payment here before confirming checkout.

5. Apply Deductions / Security Deposit

   If there are damages or the student had a security deposit to refund, enter these amounts. The system adjusts the final balance accordingly.

6. Confirm Checkout

   Click the "Confirm Checkout" button. HMS asks for confirmation, then: sets allocation status to Completed, sets bed status to Available, sets student status to Checked Out.

7. Print Checkout Receipt

   After checkout is confirmed, print the final checkout receipt / clearance document for the student.

After Checkout

Tracking every rupee spent in running your hostel.

The Expenses module records all operational costs of running your hostel. By tracking expenses alongside income (payments), you get a true picture of your profitability.

Recording an Expense

1. Click "➕ Add Expense"

   Opens the Add Expense form.

2. Select Category

   Choose from: Electricity, Water, Gas, Maintenance, Salary, Grocery, Internet, Rent, Repair, Other.

3. Enter Amount

   The exact amount spent, in your hostel's configured currency.

4. Set Date

   When the expense was incurred (defaults to today).

5. Add Description

   Brief note explaining the expense — e.g., "Monthly electricity bill", "Plumber for room 205 repair".

6. Save

   The expense is recorded and appears in the list, searchable by keyword or date.

Managing Expenses

Business-grade reports and analytics for your hostel.

The Reports module is your business intelligence center. Generate detailed reports filtered by any date range — print them or export as PDF for your accountant, owner review, or audit purposes.

Available Report Types

Generating a Report

1. Select Report Type

   Choose the type of report you need from the navigation tabs.

2. Set Date Range

   Use the date pickers to set your Start Date and End Date. You can select daily, weekly, monthly, or any custom period.

3. Apply Filters

   Some reports allow additional filters — e.g., by room type, payment method, or student status.

4. Generate

   Click the Generate button. The report loads with data, tables, and charts based on your selected parameters.

5. Print or Export PDF

   Click Print to send to a printer. The PDF includes your hostel header, the data tables, and charts — formatted professionally using ReportLab.

Charts in Reports

Reports include Matplotlib-powered charts — bar charts for monthly revenue, pie charts for payment status, line charts for occupancy trends. These charts are also included when you export to PDF.

Configuring HMS for your hostel's specific needs.

The Settings page is organized into four tabs: General, Users, System, and Backup.

Tab 1 — General Settings

Tab 2 — User Management

Tab 3 — System Settings

Tab 4 — Backup Settings

Complete audit trail — every action, by every user, at every time.

HMS automatically logs every significant action performed in the system. This creates a complete, tamper-evident audit trail — essential for hostels with multiple staff members.

What Gets Logged

Log Entry Structure

Filtering Logs

The Logs page includes filters to help you find specific events quickly:

Log Retention & Cleanup

Logs are stored in a separate database file (hms_logs.db) and are automatically cleaned up based on the retention period set in Settings → System. This prevents the log database from growing too large over time.

Displaying and enforcing your hostel's rules within the system.

The Policies module allows you to store and display your hostel's rules, terms, and conditions directly within HMS. This creates a digital record of your policies — visible to all staff and students who use the system.

Policy Acceptance

When a user first logs in, HMS can require them to read and accept the hostel policy before accessing the system. The policy_accepted flag is stored in the user record — creating a permanent digital acknowledgment that the user has read and agreed to your rules.

Who Can Access Policies

Built-in documentation and application information.

Help Page

Click 💡 Help in the sidebar to access the built-in Help section. This is a comprehensive in-app guide covering how to use every module. It is always available offline — no internet needed.

About Page

Click 👤 About to see information about the HMS software and its developer.

Understanding who can do what in HMS.

HMS implements a Role-Based Access Control (RBAC) system with three user roles. Each role has a specific set of permissions designed to give team members the access they need — without exposing sensitive data to those who shouldn't see it.

Detailed Permission Matrix

How HMS keeps your data safe and recoverable.

Security Features

Database Location

Auto-Backup System

When Auto Backup is enabled in Settings → Backup:

Recovering from a Backup

1. Locate Your Backup File

   Go to your configured backup folder (default: Documents/HMS/Backups). Find the backup file from the date before your data was lost.

2. Close HMS

   Make sure HMS is not running.

3. Replace the Database File

   Copy your backup .db file to Documents/HMS/database/ and rename it to hostel_management.db (replacing the current file).

4. Restart HMS

   Open HMS normally. It will load from the restored backup.

Speed up your workflow with built-in keyboard shortcuts.

Common questions and solutions.

Get help from the developer — directly and personally.

HMS is built and maintained by an independent solo developer who provides direct, personal support. When you contact us, you speak to the person who actually built the software.

What We Can Help With