Ananas4444/hotel-reconciliation

Hotel Intelligence Platform

New to the repo? Start at `NAVIGATION.md` — it's the map of every top-level file and folder.

Hospitality-tech platform that combines credit-card reconciliation RCA, review intelligence, and staff schedule optimization into one FastAPI application. Built for hotels running OnQ (Hampton / Hilton family) with Adyen settlements, but architected to extend to any PMS + card processor pair.

What it does

1. Credit-card reconciliation with root-cause attribution

Compares daily Adyen settlements against OnQ account-detail postings and explains every difference. Catches patterns a spreadsheet cannot see:

• —INTERFACE contamination — bar/restaurant POS transactions tagged as Visa/MC in OnQ but settling under the INTERFACE merchant in Adyen
• —PIN/VPay absorption — debit transactions invisible inside the workbook's Visa sum formula
• —Grouped cross-date clearings — Expedia/Booking.com batch settlements that span two business dates
• —Night-audit late posting — transactions posted between 02:30-04:00 that land on the wrong business date
• —Refund not posted — Adyen SentForRefund with no matching negative OnQ row
• —Near-exact matching — tip/rounding diffs under EUR 1.00 auto-matched instead of flagged

Across 30 real dates at Hampton Schiphol, the tool reached 92.2% agreement with the manual Night Sheet and surfaced an additional EUR 1,079 of signal the workbook's sum formulas were hiding.

2. Review intelligence

Pulls reviews from Google, TripAdvisor, Booking.com, Expedia via Apify and produces:

• —Rating health score (0-100, grade A-D)
• —Complaint priority matrix (critical / high / medium / low)
• —Staff 360° rankings (composite of rating × positive-mention rate)
• —Platform performance + response-rate tracking
• —Competitive positioning + SWOT across configured competitor set

3. Schedule optimization

OR-Tools CP-SAT solver that generates weekly shift schedules respecting:

• —Max-hours per contract type (0-hour, 3-day, 4-day, 5-day, outsource)
• —Zero-hour-locked-only mode (only assigned when explicitly locked)
• —Outsource staff (BJ 1 / BJ 2) restricted to night shifts, penalty bias for use
• —Per-person unavailable dates, days, and shifts
• —Must-work-with pairings (e.g., Anas only with Sara or Davina)
• —No morning-after-night (11-hour rest)
• —Max consecutive working days
• —Solves in ~100 ms with Day / Week / Month views

4. Supporting modules

• —AI Assistant — Claude-backed Q&A over property SOPs
• —Guest Reply — AI-generated review responses in brand tone
• —SOP Manager — upload / browse / search operational docs
• —Multi-property — session-based property switching with isolated data directories

Quick start

Requirements

• —Python 3.11+
• —Node.js 20+ (only for generating decks and docs)
• —~500 MB RAM

Local development

# Install
make dev

# Run server
make run
# → http://localhost:8000

# Run fast test suite
make test

# Run everything
make test-all

Docker (mirrors HuggingFace deployment)

docker build -t hotel-intel .
docker run -p 7860:7860 --env-file .env hotel-intel

Authentication

• —Admin: seeded on first boot as ASMAA / ASMAA (change immediately on production)
• —Viewer: seeded as joey / joey2026
• —Guest mode: click "Continue as Guest" on /login for read-only 24-hour session

Environment

Required HuggingFace Space secrets (or local .env):

Verify configuration via GET /api/claude-status (authenticated).

Architecture

Local modular monolith following SOLID principles:

src/reconciliation/
├── domain/           # Core business concepts (no I/O)
├── application/      # Use-case orchestration
├── infrastructure/   # Adapters — Excel, DB, HTTP, LLM
└── presentation/     # FastAPI + Jinja2 templates + static CSS

• —Multi-property via data/properties.json + session cookie routing
• —Knowledge base in SQLite (data/knowledge.db) with 10,247 OnQ transactions + 1,896 Adyen settlements + 3,297 reconciled pairs
• —Mobile-first CSS with 44 px tap targets, table scroll wrappers, day/week/month schedule views

See `docs/ARCHITECTURE.md` for the deep dive.

Testing

make test-fast        # 383 E2E tests, ~3s
make test-full        # 533 full platform tests, ~20s
make test-schedule    # 246 schedule-optimizer tests
make test-all         # everything

# Performance benchmarks
make test-perf

# Lint + format
make lint
make format

# Local CI equivalent (lint + all tests)
make ci

CI runs automatically on push/PR via .github/workflows/ci.yml against Python 3.11 and 3.12. Performance benchmarks run only on main and upload artifacts for regression tracking.

Deployment

Currently a single-region deployment on HuggingFace Spaces with Docker SDK.

make deploy-hf         # git push hf main

The Space includes a Weaviate sidecar for vector search and runs both services under supervisord. See `Dockerfile` and `supervisord.conf`.

Commercialization

This project is commercially operated. Revenue model:

• —Starter EUR 800/mo — Reviews + Schedule only
• —Pro EUR 1,500/mo — Everything including Reconciliation RCA (the main offering)
• —Enterprise EUR 3,000+/mo — Multi-property, SSO, priority support
• —Implementation EUR 5,000 one-time
• —Consulting EUR 200/hr — finance workbook retrofit, custom Adyen rules, PMS migration

The 180-day go-to-market plan targets EUR 20,000/month net profit by Q4 2026. See Commercialization_Plan_20k.docx and 180-Day_Schedule.xlsx at the repo root.

Documentation

Contributing

See CONTRIBUTING.md for the workflow. All contributions require:

1. 1.An issue describing the work (use one of the three templates)
2. 2.A branch off main
3. 3.Tests for new code
4. 4.make ci passing locally
5. 5.Review + approval via GitHub pull request

License

Proprietary. All rights reserved. Contact the maintainer for commercial licensing, OEM / reseller terms, or enterprise pilots.