# wtfloris/hestia architecture

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

- Interactive diagram: https://gitdiagram.com/wtfloris/hestia
- Repository: https://github.com/wtfloris/hestia

## Overview

Hestia collects rental listings from real-estate sites, parses them into homes, stores them, and notifies subscribers through Telegram and Apple push. Users can also manage filters and view listings through the website. The graph includes documented parser capabilities and the visible web authentication, dashboard, and device-registration surface. Some web routes and scraper internals were only partially excerpted, so unverified connections are omitted or dashed.

Main entry points: [`hestia/scraper.py`](https://github.com/wtfloris/hestia/blob/master/hestia/scraper.py) (Scraper runner), [`hestia/bot.py`](https://github.com/wtfloris/hestia/blob/master/hestia/bot.py) (Telegram bot), [`web/hestia_web/app.py`](https://github.com/wtfloris/hestia/blob/master/web/hestia_web/app.py) (Web application), [`hestia/hestia_utils/db.py`](https://github.com/wtfloris/hestia/blob/master/hestia/hestia_utils/db.py) (Database access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Listing collection"]
  node_scraper["Scraper runner<br/>[scraper.py]"]
  node_funda["Funda fetcher<br/>[funda_scraper.py]"]
  node_parsers["Agency parsers<br/>[parser.py]"]
end

subgraph group_delivery["Subscriber delivery"]
  node_telegram_bot["Telegram bot<br/>[bot.py]"]
  node_message_text["Localized messages<br/>[strings.py]"]
  node_telegram_utils["Bot utilities<br/>[meta.py]"]
  node_push_client["APNs client<br/>[apns.py]"]
end

subgraph group_web["Web experience"]
  node_web_app["Web application<br/>[app.py]"]
  node_dashboard["Dashboard interface<br/>[dashboard.js]"]
  node_web_templates["Page templates"]
end

subgraph group_storage["Shared state"]
  node_database_access["Database access<br/>[db.py]"]
  node_postgres[("PostgreSQL")]
end

node_renter(("Renter"))
node_property_sites["Property sites"]
node_telegram_service["Telegram"]
node_apple_push["Apple APNs"]
node_web_user(("Website user"))

node_renter -->|"uses bot"| node_telegram_bot
node_telegram_bot -->|"reads and updates"| node_database_access
node_telegram_bot -->|"gets messages"| node_message_text
node_message_text -->|"gets language"| node_database_access
node_message_text -->|"uses emoji"| node_telegram_utils
node_telegram_bot -->|"uses bot"| node_telegram_utils
node_telegram_bot -->|"sends messages"| node_telegram_service
node_scraper -->|"fetches listings"| node_property_sites
node_scraper -->|"uses fetcher"| node_funda
node_funda -->|"parses response"| node_parsers
node_scraper -->|"parses targets"| node_parsers
node_scraper -->|"stores homes"| node_database_access
node_scraper -->|"uses bot"| node_telegram_utils
node_scraper -->|"broadcasts listings"| node_telegram_service
node_scraper -->|"sends push"| node_push_client
node_push_client -->|"posts notifications"| node_apple_push
node_web_user -->|"manages listings"| node_web_app
node_web_app -.->|"renders pages"| node_web_templates
node_dashboard -.->|"requests updates"| node_web_app
node_web_app -.->|"queries and updates"| node_postgres
node_database_access -->|"queries and updates"| node_postgres

click node_scraper "https://github.com/wtfloris/hestia/blob/master/hestia/scraper.py"
click node_funda "https://github.com/wtfloris/hestia/blob/master/hestia/hestia_utils/funda_scraper.py"
click node_parsers "https://github.com/wtfloris/hestia/blob/master/hestia/hestia_utils/parser.py"
click node_telegram_bot "https://github.com/wtfloris/hestia/blob/master/hestia/bot.py"
click node_message_text "https://github.com/wtfloris/hestia/blob/master/hestia/hestia_utils/strings.py"
click node_telegram_utils "https://github.com/wtfloris/hestia/blob/master/hestia/hestia_utils/meta.py"
click node_push_client "https://github.com/wtfloris/hestia/blob/master/hestia/hestia_utils/apns.py"
click node_web_app "https://github.com/wtfloris/hestia/blob/master/web/hestia_web/app.py"
click node_dashboard "https://github.com/wtfloris/hestia/blob/master/web/static/dashboard.js"
click node_web_templates "https://github.com/wtfloris/hestia/tree/master/web/templates"
click node_database_access "https://github.com/wtfloris/hestia/blob/master/hestia/hestia_utils/db.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_scraper,node_funda,node_parsers,node_web_user toneBlue
class node_telegram_bot,node_message_text,node_telegram_utils,node_push_client toneAmber
class node_web_app,node_dashboard,node_web_templates toneMint
class node_database_access,node_postgres toneRose
class node_renter,node_property_sites,node_telegram_service,node_apple_push toneIndigo
```

## Components

### Listing collection

- [Scraper runner](https://github.com/wtfloris/hestia/blob/master/hestia/scraper.py): `hestia/scraper.py`
- [Funda fetcher](https://github.com/wtfloris/hestia/blob/master/hestia/hestia_utils/funda_scraper.py): `hestia/hestia_utils/funda_scraper.py`
- [Agency parsers](https://github.com/wtfloris/hestia/blob/master/hestia/hestia_utils/parser.py): `hestia/hestia_utils/parser.py`

### Subscriber delivery

- [Telegram bot](https://github.com/wtfloris/hestia/blob/master/hestia/bot.py): `hestia/bot.py`
- [Localized messages](https://github.com/wtfloris/hestia/blob/master/hestia/hestia_utils/strings.py): `hestia/hestia_utils/strings.py`
- [Bot utilities](https://github.com/wtfloris/hestia/blob/master/hestia/hestia_utils/meta.py): `hestia/hestia_utils/meta.py`
- [APNs client](https://github.com/wtfloris/hestia/blob/master/hestia/hestia_utils/apns.py): `hestia/hestia_utils/apns.py`

### Web experience

- [Web application](https://github.com/wtfloris/hestia/blob/master/web/hestia_web/app.py): `web/hestia_web/app.py`
- [Dashboard interface](https://github.com/wtfloris/hestia/blob/master/web/static/dashboard.js): `web/static/dashboard.js`
- [Page templates](https://github.com/wtfloris/hestia/tree/master/web/templates): `web/templates`

### Shared state

- [Database access](https://github.com/wtfloris/hestia/blob/master/hestia/hestia_utils/db.py): `hestia/hestia_utils/db.py`
- **PostgreSQL**

### Other components

- **Renter**
- **Property sites**
- **Telegram**
- **Apple APNs**
- **Website user**

## Connections

- Renter → Telegram bot: uses bot (evidence: `README.md`)
- Telegram bot → Database access: reads and updates (evidence: `hestia/bot.py`)
- Telegram bot → Localized messages: gets messages (evidence: `hestia/bot.py`)
- Localized messages → Database access: gets language (evidence: `hestia/hestia_utils/strings.py`)
- Localized messages → Bot utilities: uses emoji (evidence: `hestia/hestia_utils/strings.py`)
- Telegram bot → Bot utilities: uses bot (evidence: `hestia/bot.py`)
- Telegram bot → Telegram: sends messages (evidence: `hestia/bot.py`)
- Scraper runner → Property sites: fetches listings (evidence: `README.md`)
- Scraper runner → Funda fetcher: uses fetcher (evidence: `hestia/scraper.py`)
- Funda fetcher → Agency parsers: parses response (evidence: `hestia/hestia_utils/funda_scraper.py`)
- Scraper runner → Agency parsers: parses targets (evidence: `hestia/scraper.py`)
- Scraper runner → Database access: stores homes (evidence: `hestia/scraper.py`)
- Scraper runner → Bot utilities: uses bot (evidence: `hestia/scraper.py`)
- Scraper runner → Telegram: broadcasts listings (evidence: `hestia/scraper.py`)
- Scraper runner → APNs client: sends push (evidence: `hestia/scraper.py`)
- APNs client → Apple APNs: posts notifications (evidence: `hestia/hestia_utils/apns.py`)
- Website user → Web application: manages listings (evidence: `README.md`)
- Web application → Page templates: renders pages
- Dashboard interface → Web application: requests updates
- Web application → PostgreSQL: queries and updates
- Database access → PostgreSQL: queries and updates (evidence: `hestia/hestia_utils/db.py`)