bench get-app https://github.com/Gifted87/erpnext_hospitality_core

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=Gifted87%2Ferpnext_hospitality_core)](https://frappegems.com/gems/apps/Gifted87/erpnext_hospitality_core)

Hospitality Core for ERPNext: The Native Hotel Management System

Hospitality Core is a complete, enterprise-grade Property Management System (PMS) built natively within the Frappe Framework. It transforms your ERPNext instance into a powerful, single-source-of-truth solution for hotel operations, eliminating the need for fragile third-party integrations for core financial and inventory functions.

Designed for markets where robust internal controls, real-time inventory management, and sophisticated corporate billing are paramount, this application prioritizes operational integrity over costly and often unnecessary external API dependencies.

---

📖 Table of Contents

1. Our Philosophy: Control, Not Connectivity
2. Key Differentiators
3. In-Depth Feature Analysis
   • Front Office & Guest Management
   • Financial Engine & Folio Management
   • Housekeeping & Maintenance
   • Group & Corporate Bookings
   • Rate & Inventory Management
   • ERPNext Native Integrations
4. Operational Workflow Guides
   • Lifecycle of a Private Guest
   • Lifecycle of a Corporate Guest (City Ledger)
   • Processing a Restaurant Bill to a Room
   • Handling a Group Booking
5. The Reporting Suite
6. Installation & Configuration
   • Prerequisites
   • Installation Steps
   • Initial Setup Checklist
7. Technical Architecture Deep Dive
   • Core DocTypes & Their Relationships
   • Hooks & Event-Driven Logic
   • The Night Audit Engine
8. Contributing & Customization
9. License

---

Our Philosophy: Control, Not Connectivity

Hospitality Core is built on the philosophy of Internal Control. By leveraging the power of ERPNext, we provide a unified system where: * Finance is Live: Every charge posted to a room is a real-time entry impacting your ledgers. There is no "end-of-day sync" that can fail. * Inventory is Secure: A minibar item charged to a guest is immediately deducted from a specific room's warehouse, providing unparalleled control over stock shrinkage. * Data is Centralized: Guest history, corporate accounts, and financial performance data all reside in one database, enabling powerful, holistic reporting that is impossible with bridged systems.

This makes it the ideal solution for boutique hotels, business hotels, and serviced apartments that demand precision, security, and financial integrity from their management software.

✨ Key Differentiators

• True ERP Integration: This is not a "sync" or an "integration." The PMS is the ERP. Your front desk, restaurant, and accounting teams all work from the same live data.
• Sophisticated City Ledger Management: The system automates the complex accounting required for corporate clients. Charges can be automatically mirrored from individual guest folios to a master company folio, allowing guests to check out with a zero balance while their company's debt is tracked separately.
• Granular Inventory Control: Uniquely, each hotel room can be mapped to its own stock Warehouse. When a POS transaction for a minibar item is posted, the system deducts the stock from that specific room's inventory, providing a powerful tool against theft and for operational efficiency.
• Comprehensive Workspace & Visual Tools: From the Front Desk Console to the Tape Chart, the user interface is designed for the high-speed, visual nature of front office work, while still being backed by the robust structure of ERPNext.

---

🚀 In-Depth Feature Analysis

🏨 Front Office & Guest Management

1. Front Desk Console

• What it is: A single-page application serving as the command center for the front desk.
• How it Works: Powered by hospitality_core/page/front_desk_console/, the get_console_data function in front_desk_console.py runs a series of optimized SQL queries to calculate date-sensitive KPIs: pending arrivals, pending departures, in-house occupancy, and net room availability. The results are rendered by front_desk_console.js into an interactive dashboard with clickable links.
• Business Value: Provides the Manager on Duty with an instant, "at-a-glance" view of the day's operations, allowing for quick decisions on staffing and sales strategy.

2. Tape Chart (Reservation Calendar)

• What it is: A visual, grid-based calendar showing rooms on the Y-axis and dates on the X-axis.
• How it Works: The tape_chart.js frontend makes an AJAX call to get_chart_data in tape_chart.py. This function fetches all enabled rooms and overlays them with reservations that fall within the selected date range. The logic arrival_date < end AND departure_date > start correctly captures all overlapping bookings. Bookings are color-coded based on their status (Reserved vs. Checked In).
• Business Value: Allows reservation agents to visually identify gaps and booking patterns, making it faster to place new reservations and manage room assignments.

3. Guest 360 View

• What it is: A dedicated page to view the complete history and value of any guest.
• How it Works: The guest_360.js page takes a Guest ID and calls get_guest_details in guest_360.py. This function consolidates data from the Guest doctype, all associated Hotel Reservation documents, and aggregates financial data from Guest Folio documents to calculate metrics like Total Stays and Lifetime Spend.
• Business Value: Empowers staff to recognize and reward loyal customers. Identifying a high-value guest upon check-in can significantly enhance the guest experience.

4. Guest & Reservation Management

• DocTypes: Guest, Hotel Reservation
• How it Works: The Hotel Reservation document is the core operational record. Its Python class (hotel_reservation.py) contains the state machine logic for a guest's stay (process_check_in, process_check_out, process_cancel). The system enforces strict validation, such as using check_availability to prevent double bookings. Upon creation, it automatically triggers the creation of a Guest Folio via the after_insert hook.
• Business Value: A secure and auditable system for managing the entire guest lifecycle, with clear state transitions that prevent common operational errors.

💰 Financial Engine & Folio Management

1. The Folio System

• DocTypes: Guest Folio, Folio Transaction
• How it Works: The Guest Folio acts as the master bill for a guest's stay. All financial events are recorded as child documents in the Folio Transaction table. The core financial logic resides in hospitality_core/api/folio.py. The sync_folio_balance function is the heart of the system, triggered by doc_events in hooks.py whenever a transaction is saved or trashed. It uses an aggregation query to recalculate total_charges, total_payments, and outstanding_balance, ensuring the folio is always accurate.
• Business Value: Provides a clear, itemized, and always up-to-date bill for the guest, ensuring transparency and reducing checkout disputes.

2. City Ledger & Corporate Folio Mirroring

• What it is: The system's ability to manage bills owed by companies, separate from the guests who stayed.
• How it Works: When a reservation is marked as is_company_guest, a master folio for that company is created (ensure_company_folio in hotel_reservation.py). During the stay, any transaction posted to the guest's folio with bill_to = 'Company' triggers the mirror_to_company_folio function. This function creates an exact copy of the transaction on the Company's Master Folio, ensuring both ledgers are in sync. At checkout, the guest's folio balance related to company charges is transferred off, allowing the guest to leave while the debt remains with the company.
• Business Value: This is a critical feature for business hotels. It streamlines corporate billing, reduces checkout friction for corporate guests, and provides the accounting department with a clean, actionable list of corporate debtors (the City Ledger).

3. Financial Controls

• DocTypes: Allowance Reason Code
• How it Works: To void a charge, a user must select a reason from the Allowance Reason Code list. The void_transaction function in financial_control.py checks if the selected reason requires_manager_approval. If so, it verifies the user's roles before proceeding. This prevents unauthorized write-offs.
• Business Value: Enforces accountability and reduces revenue leakage from fraudulent or unwarranted voids and discounts.

🧹 Housekeeping & Maintenance

1. Housekeeping Board

• What it is: A visual grid of all hotel rooms, color-coded by their housekeeping status.
• How it Works: The housekeeping_view.js page calls get_room_statuses in housekeeping_view.py to fetch the live status of all rooms. Housekeeping staff can click a button to change a room's status from Dirty to Available (Clean). This action calls set_room_status, which includes a permission check to ensure only authorized staff can update statuses.
• Business Value: Creates a direct line of communication between housekeeping and the front desk, speeding up room turnover and ensuring guests are checked into clean rooms.

2. Maintenance Management

• DocType: Hotel Maintenance Request
• How it Works: When a maintenance request is created for a room (e.g., "Leaky Faucet"), the on_update logic in hotel_maintenance_request.py is triggered. If the request status is Reported or In Progress, the system automatically changes the Hotel Room status to Out of Order. When the request is Completed, the room status is set to Dirty, queuing it for housekeeping.
• Business Value: Prevents guest complaints and revenue loss by ensuring rooms with defects are automatically taken out of inventory and only returned after being serviced and cleaned.

🏢 Group & Corporate Bookings

• DocType: Hotel Group Booking
• How it Works: This document acts as a container for multiple individual reservations. The hotel_group_booking.js adds custom buttons to the form, allowing a user to Create Master Folio, Link Reservations, Check In Group, and Check Out Group. These buttons call whitelisted API functions in group_booking.py that loop through associated reservations and apply the state changes in bulk.
• Business Value: Massively improves efficiency when managing wedding parties, conference attendees, or tour groups, reducing dozens of clicks to a single action.

📈 Rate & Inventory Management

• DocTypes: Hotel Room Type, Room Rate Plan, Hotel Room
• How it works: The system uses a hierarchical rate structure. The base rate is set on the