# som3adr/hotelrunner-daily architecture

> Architecture diagram of the GitHub repository som3adr/hotelrunner-daily, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/som3adr/hotelrunner-daily
- Repository: https://github.com/som3adr/hotelrunner-daily
- Video tour (about a minute): https://gitdiagram.com/som3adr/hotelrunner-daily/video

## Overview

This repository combines a read-only HotelRunner daily reporting tool with a broader hostel-operations manager workflow. The main report path fetches and caches reservations, builds operational summaries and conflict audits, then writes Markdown and an HTML dashboard; it explicitly does not modify bookings. The wider source tree also indicates Telegram delivery and Q&A, morning operations, and reservation-monitoring capabilities. The sampled excerpts support the normalization and several rule-engine responsibilities, but not all wiring among these wider features, so uncertain links are omitted.

Main entry points: [`manager_report.py`](https://github.com/som3adr/hotelrunner-daily/blob/main/manager_report.py) (Manager report), [`hotelrunner_daily_summary.py`](https://github.com/som3adr/hotelrunner-daily/blob/main/hotelrunner_daily_summary.py) (Daily report runner), [`operations_monitor.py`](https://github.com/som3adr/hotelrunner-daily/blob/main/operations_monitor.py) (Operations monitor), [`morning_delivery.py`](https://github.com/som3adr/hotelrunner-daily/blob/main/morning_delivery.py) (Morning delivery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_report["Daily report"]
  node_reporter["Daily report runner"]
  node_cache[("Reservation cache")]
  node_blocks["Manual room blocks"]
  node_markdown["Markdown report"]
  node_dashboard["HTML dashboard"]
  node_audit["Reservation audit"]
end

subgraph group_domain["Operations rules"]
  node_model["Normalized reservations<br/>[data_model.py]"]
  node_extras["Extras classification<br/>[extras_engine.py]"]
  node_conflicts["Conflict detection<br/>[conflict_engine.py]"]
  node_meals["Meal entitlements<br/>[meal_engine.py]"]
  node_transfers["Transfer planning<br/>[transfer_engine.py]"]
  node_settlement["Checkout settlement"]
  node_manager["Manager report<br/>[manager_report.py]"]
end

subgraph group_delivery["Messaging"]
  node_morning["Morning delivery"]
  node_telegram["Telegram bot<br/>[telegram_bot.py]"]
  node_sender["Telegram sender<br/>[telegram_send.py]"]
  node_monitor["Operations monitor"]
  node_qa["Operations Q&amp;A<br/>[operations_qa.py]"]
  node_state[("Alert state<br/>[alert_state.py]")]
end

subgraph group_integrations["External services"]
  node_hotelrunner["HotelRunner"]
  node_sheets[("Google Sheets")]
  node_telegram_service["Telegram"]
  node_gemini["Gemini client<br/>[gemini_client.py]"]
end

node_operator(("Operator"))

node_operator -->|"runs"| node_reporter
node_reporter -->|"fetches reservations"| node_hotelrunner
node_reporter -->|"reads and updates"| node_cache
node_reporter -.->|"reads optional blocks"| node_blocks
node_reporter -->|"writes report"| node_markdown
node_reporter -->|"writes dashboard"| node_dashboard
node_reporter -->|"writes audit"| node_audit
node_manager -->|"loads reservations"| node_cache
node_manager -->|"loads Sunrise data"| node_sheets
node_manager -->|"normalizes records"| node_model
node_manager -->|"classifies extras"| node_extras
node_manager -->|"checks conflicts"| node_conflicts
node_manager -->|"computes meals"| node_meals
node_manager -->|"checks transfers"| node_transfers
node_manager -->|"checks settlements"| node_settlement
node_morning -->|"builds briefing"| node_manager
node_morning -->|"dispatches briefing"| node_sender
node_sender -->|"sends messages"| node_telegram_service
node_monitor -->|"checks updates"| node_hotelrunner
node_monitor -->|"reads and updates"| node_state
node_monitor -->|"sends alerts"| node_telegram_service
node_telegram -->|"handles questions"| node_qa
node_qa -.->|"requests answers"| node_gemini

click node_reporter "https://github.com/som3adr/hotelrunner-daily/blob/main/hotelrunner_daily_summary.py"
click node_blocks "https://github.com/som3adr/hotelrunner-daily/blob/main/hotelrunner_blocks.example.json"
click node_audit "https://github.com/som3adr/hotelrunner-daily/blob/main/hotelrunner_daily_summary.py"
click node_model "https://github.com/som3adr/hotelrunner-daily/blob/main/data_model.py"
click node_extras "https://github.com/som3adr/hotelrunner-daily/blob/main/extras_engine.py"
click node_conflicts "https://github.com/som3adr/hotelrunner-daily/blob/main/conflict_engine.py"
click node_meals "https://github.com/som3adr/hotelrunner-daily/blob/main/meal_engine.py"
click node_transfers "https://github.com/som3adr/hotelrunner-daily/blob/main/transfer_engine.py"
click node_settlement "https://github.com/som3adr/hotelrunner-daily/blob/main/settlement_engine.py"
click node_manager "https://github.com/som3adr/hotelrunner-daily/blob/main/manager_report.py"
click node_morning "https://github.com/som3adr/hotelrunner-daily/blob/main/morning_delivery.py"
click node_telegram "https://github.com/som3adr/hotelrunner-daily/blob/main/telegram_bot.py"
click node_sender "https://github.com/som3adr/hotelrunner-daily/blob/main/telegram_send.py"
click node_monitor "https://github.com/som3adr/hotelrunner-daily/blob/main/operations_monitor.py"
click node_qa "https://github.com/som3adr/hotelrunner-daily/blob/main/operations_qa.py"
click node_state "https://github.com/som3adr/hotelrunner-daily/blob/main/alert_state.py"
click node_gemini "https://github.com/som3adr/hotelrunner-daily/blob/main/gemini_client.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_reporter,node_cache,node_blocks,node_markdown,node_dashboard,node_audit toneBlue
class node_model,node_extras,node_conflicts,node_meals,node_transfers,node_settlement,node_manager toneAmber
class node_morning,node_telegram,node_sender,node_monitor,node_qa,node_state toneMint
class node_hotelrunner,node_sheets,node_telegram_service,node_gemini toneRose
class node_operator toneIndigo
```

## Components

### Daily report

- [Daily report runner](https://github.com/som3adr/hotelrunner-daily/blob/main/hotelrunner_daily_summary.py): `hotelrunner_daily_summary.py`
- **Reservation cache**
- [Manual room blocks](https://github.com/som3adr/hotelrunner-daily/blob/main/hotelrunner_blocks.example.json): `hotelrunner_blocks.example.json`
- **Markdown report**
- **HTML dashboard**
- [Reservation audit](https://github.com/som3adr/hotelrunner-daily/blob/main/hotelrunner_daily_summary.py): `hotelrunner_daily_summary.py`

### Operations rules

- [Normalized reservations](https://github.com/som3adr/hotelrunner-daily/blob/main/data_model.py): `data_model.py`
- [Extras classification](https://github.com/som3adr/hotelrunner-daily/blob/main/extras_engine.py): `extras_engine.py`
- [Conflict detection](https://github.com/som3adr/hotelrunner-daily/blob/main/conflict_engine.py): `conflict_engine.py`
- [Meal entitlements](https://github.com/som3adr/hotelrunner-daily/blob/main/meal_engine.py): `meal_engine.py`
- [Transfer planning](https://github.com/som3adr/hotelrunner-daily/blob/main/transfer_engine.py): `transfer_engine.py`
- [Checkout settlement](https://github.com/som3adr/hotelrunner-daily/blob/main/settlement_engine.py): `settlement_engine.py`
- [Manager report](https://github.com/som3adr/hotelrunner-daily/blob/main/manager_report.py): `manager_report.py`

### Messaging

- [Morning delivery](https://github.com/som3adr/hotelrunner-daily/blob/main/morning_delivery.py): `morning_delivery.py`
- [Telegram bot](https://github.com/som3adr/hotelrunner-daily/blob/main/telegram_bot.py): `telegram_bot.py`
- [Telegram sender](https://github.com/som3adr/hotelrunner-daily/blob/main/telegram_send.py): `telegram_send.py`
- [Operations monitor](https://github.com/som3adr/hotelrunner-daily/blob/main/operations_monitor.py): `operations_monitor.py`
- [Operations Q&A](https://github.com/som3adr/hotelrunner-daily/blob/main/operations_qa.py): `operations_qa.py`
- [Alert state](https://github.com/som3adr/hotelrunner-daily/blob/main/alert_state.py): `alert_state.py`

### External services

- **HotelRunner**
- **Google Sheets**
- **Telegram**
- [Gemini client](https://github.com/som3adr/hotelrunner-daily/blob/main/gemini_client.py): `gemini_client.py`

### Other components

- **Operator**

## Connections

- Operator → Daily report runner: runs
- Daily report runner → HotelRunner: fetches reservations
- Daily report runner → Reservation cache: reads and updates
- Daily report runner → Manual room blocks: reads optional blocks
- Daily report runner → Markdown report: writes report
- Daily report runner → HTML dashboard: writes dashboard
- Daily report runner → Reservation audit: writes audit
- Manager report → Reservation cache: loads reservations
- Manager report → Google Sheets: loads Sunrise data
- Manager report → Normalized reservations: normalizes records
- Manager report → Extras classification: classifies extras
- Manager report → Conflict detection: checks conflicts
- Manager report → Meal entitlements: computes meals
- Manager report → Transfer planning: checks transfers
- Manager report → Checkout settlement: checks settlements
- Morning delivery → Manager report: builds briefing
- Morning delivery → Telegram sender: dispatches briefing
- Telegram sender → Telegram: sends messages
- Operations monitor → HotelRunner: checks updates
- Operations monitor → Alert state: reads and updates
- Operations monitor → Telegram: sends alerts
- Telegram bot → Operations Q&A: handles questions
- Operations Q&A → Gemini client: requests answers