Enterprise Hotel Management API

A production-oriented FastAPI backend for multi-property hotels, resorts and serviced apartments. It is implemented as a modular monolith that can later be split into identity, reservation, property inventory, front-desk, operations, billing and analytics services.

Major capabilities

Identity and access

• Argon2 password hashing
• JWT access tokens and rotating refresh tokens
• Refresh-token family revocation after reuse
• Account lockout protection
• One-session and all-session logout
• Nine roles: super administrator, hotel manager, front desk, reservation agent, housekeeping, maintenance, accountant, concierge and guest
• Hotel-scoped data access
• Request IDs, security headers and audit events

Property, rooms and rates

• Multi-property hotel records
• Room types and physical rooms
• Floor, wing, smoking and accessibility attributes
• Room amenities
• Room status board
• Best-available and meal-plan rate plans
• Seasonal and day-of-week pricing rules
• Promotion codes with limits and minimum spend
• Occupancy limits and extra-person pricing

Reservations and guests

• Availability calculation with overlap protection
• Multi-room reservations
• Guest profiles, preferences, VIP levels and documents
• Immutable reservation totals
• Promotions, tax and service-charge calculations
• Confirmation, cancellation and no-show states
• Additional reservation guests
• Physical-room assignment with conflict detection
• Reservation timeline

Front desk and stay management

• Check-in and key-card generation
• In-house guest list
• Key-card replacement
• Deposits and expected checkout
• Balance-controlled checkout
• Automatic room-dirty transition
• Automatic checkout-cleaning task generation

Operations

• Housekeeping task assignment, completion and inspection
• Maintenance tickets and room blocking
• Service requests for transport, laundry, room service, concierge and other services
• Automatic service-charge posting to guest folios
• Live room board

Billing and reporting

• One folio per reservation
• Room, tax, service, minibar, laundry, spa, transport and custom charges
• Charge voiding with reasons
• Idempotent cash, card, UPI, transfer and wallet payments
• Partial and complete refunds
• Invoice payload generation
• Dashboard KPIs
• Occupancy forecast
• Revenue by charge type
• Night audit and no-show processing
• Searchable audit logs

Architecture

Web / Mobile / Kiosk / Staff Admin
                |
                v
           FastAPI Gateway
                |
 +--------------+----------------+----------------+
 |              |                |                |
Identity     Reservations     Hotel Ops       Finance
 |              |                |                |
 +--------------+----------------+----------------+
                |
          SQLAlchemy ORM
                |
        PostgreSQL / SQLite
                |
        Redis + Celery Worker

Run with Docker

Copy-Item .env.example .env
docker compose up --build

Seed demonstration records:

docker compose exec api python -m scripts.seed

Open:

• Swagger: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI: http://localhost:8000/openapi.json
• Health: http://localhost:8000/api/v1/health
• Readiness: http://localhost:8000/api/v1/ready

Local setup

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env

Use SQLite in .env:

DATABASE_URL=sqlite:///./hotel_management.db
REDIS_URL=
TRUSTED_HOSTS=localhost,127.0.0.1,testserver

Then:

alembic upgrade head
python -m scripts.seed
uvicorn app.main:app --reload

Demonstration accounts

All seeded users use Password@123.

Role	Email
Super administrator	admin@hotel.example.com
Hotel manager	manager@hotel.example.com
Front desk	frontdesk@hotel.example.com
Reservation agent	reservations@hotel.example.com
Housekeeping	housekeeping@hotel.example.com
Maintenance	maintenance@hotel.example.com
Accountant	accounts@hotel.example.com
Concierge	concierge@hotel.example.com
Guest	guest@hotel.example.com

Typical lifecycle

1. Create a property, room types, physical rooms and rate plans.
2. Configure seasonal rates and promotions.
3. Register or locate a guest and verify an identity document.
4. Check availability for dates and occupancy.
5. Create and confirm a reservation.
6. Assign a compatible physical room.
7. Check the guest in and issue a key card.
8. Post minibar, food, laundry, spa and transport charges.
9. Record idempotent partial or complete payments.
10. Resolve service and maintenance requests.
11. Check the guest out after folio reconciliation.
12. Complete the generated housekeeping task.
13. Review night audit, occupancy, revenue and audit reports.

Idempotent payment example

curl -X POST http://localhost:8000/api/v1/finance/folios/1/payments \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Idempotency-Key: folio-1-payment-0001" \
  -H "Content-Type: application/json" \
  -d '{"method":"card","amount":"25000.00","transaction_reference":"TXN-10001"}'

A retry with the same key returns the original payment instead of creating a duplicate.

Main route groups

Area	Base path
Authentication and staff	/api/v1/auth/*
Hotels, rooms and rates	/api/v1/hotels/*
Guest profiles	/api/v1/guests/*
Reservations	/api/v1/reservations/*
Check-in and checkout	/api/v1/stays/*
Folios and payments	/api/v1/finance/*
Housekeeping, maintenance and services	/api/v1/operations/*
Dashboard, reports and night audit	/api/v1/admin/*

Migrations

alembic upgrade head

After changing models:

alembic revision --autogenerate -m "describe the change"
alembic upgrade head

Tests

pytest -q

The lifecycle suite validates token rotation, availability, guest documents, promotions, reservation creation, room assignment, check-in, folio charges, service requests, maintenance room blocking, idempotent payment, checkout, housekeeping, invoice reconciliation and dashboard metrics.

Production notes

Read SECURITY.md before using this code with real guests or payments. Replace mock integrations, introduce MFA/SSO, encrypt sensitive identity data, configure managed infrastructure, and complete regional legal and compliance reviews.