# mrehank209/germany-wohnungsbot architecture

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

- Interactive diagram: https://gitdiagram.com/mrehank209/germany-wohnungsbot
- Repository: https://github.com/mrehank209/germany-wohnungsbot

## Overview

Wohnungsbot polls German rental portals, filters listings against a user’s city and apartment criteria, persists listing and delivery state, and sends matching alerts through Telegram. Kleinanzeigen can optionally contact new matches. The main loop owns scanning and delivery coordination; portal-specific parsing, shared filtering helpers, SQLite state, and Telegram delivery are separate responsibilities. The README documents the supported platforms and configuration workflow; links for some unsampled platform implementations are documented capabilities rather than inspected call paths.

Main entry points: [`bot/main.py`](https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/main.py) (Polling coordinator), [`bot/scrapers/__init__.py`](https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/scrapers/__init__.py) (Scraper registry), [`bot/scrapers/base.py`](https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/scrapers/base.py) (Scraper base), [`bot/scrapers/kleinanzeigen.py`](https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/scrapers/kleinanzeigen.py) (Kleinanzeigen scraper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Setup and preferences"]
  node_wizard["Setup wizard<br/>[wizard.py]"]
  node_config["Search configuration<br/>[config.py]"]
end

subgraph group_discovery["Portal discovery"]
  node_scraper_registry["Scraper registry<br/>[__init__.py]"]
  node_scraper_base["Scraper base<br/>[base.py]"]
  node_klein["Kleinanzeigen scraper<br/>[kleinanzeigen.py]"]
  node_scout["ImmoScout24 scraper<br/>[immoscout24.py]"]
  node_immowelt["Immowelt scraper<br/>[immowelt.py]"]
  node_wg["WG-Gesucht scraper<br/>[wg_gesucht.py]"]
  node_coops["Local co-op scrapers"]
  node_vonovia["Vonovia scraper<br/>[vonovia.py]"]
  node_browser["Persistent browser<br/>[browser.py]"]
end

subgraph group_processing["Matching and state"]
  node_main["Polling coordinator<br/>[main.py]"]
  node_location["City lookup<br/>[location.py]"]
  node_listing["Listing model<br/>[models.py]"]
  node_dates["Date parsing<br/>[dates.py]"]
  node_rent["Warm-rent lookup<br/>[rent.py]"]
  node_money["Euro parsing<br/>[money.py]"]
  node_storage[("Listing and delivery state<br/>[storage.py]")]
end

subgraph group_delivery["Alerts and contact"]
  node_telegram["Telegram delivery<br/>[telegram.py]"]
  node_contact["Kleinanzeigen contact<br/>[contact.py]"]
end

node_user(("Apartment seeker"))
node_telegram_service(("Telegram"))
node_rental_sites(("Rental platforms"))

node_user -->|"sets preferences"| node_wizard
node_wizard -->|"writes settings"| node_config
node_main -->|"loads settings"| node_config
node_main -->|"selects scrapers"| node_scraper_registry
node_scraper_registry -->|"registers"| node_klein
node_scraper_registry -->|"registers"| node_scout
node_scraper_registry -->|"registers"| node_immowelt
node_scraper_registry -->|"registers"| node_wg
node_scraper_registry -->|"registers"| node_coops
node_scraper_registry -->|"registers"| node_vonovia
node_main -->|"fetches listings"| node_scraper_base
node_scraper_base -->|"provides shared behavior"| node_klein
node_scraper_base -->|"provides shared behavior"| node_scout
node_main -->|"opens browser"| node_browser
node_main -->|"checks city"| node_location
node_klein -->|"resolves city"| node_location
node_main -->|"filters listings"| node_listing
node_scraper_base -->|"builds listings"| node_listing
node_klein -->|"parses publication dates"| node_dates
node_scout -->|"parses publication dates"| node_dates
node_scout -->|"enriches rent"| node_rent
node_scraper_base -->|"looks up rent"| node_rent
node_config -->|"parses rent limits"| node_money
node_main -->|"reads and updates state"| node_storage
node_main -->|"sends alerts"| node_telegram
node_telegram -->|"delivers messages"| node_telegram_service
node_main -->|"contacts new matches"| node_contact
node_contact -.->|"uses browser session"| node_browser
node_klein -.->|"fetches listings"| node_rental_sites
node_scout -.->|"fetches listings"| node_rental_sites
node_immowelt -.->|"fetches listings"| node_rental_sites
node_wg -.->|"fetches listings"| node_rental_sites
node_coops -.->|"fetches listings"| node_rental_sites
node_vonovia -.->|"fetches listings"| node_rental_sites

click node_wizard "https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/wizard.py"
click node_config "https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/config.py"
click node_main "https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/main.py"
click node_scraper_registry "https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/scrapers/__init__.py"
click node_scraper_base "https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/scrapers/base.py"
click node_klein "https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/scrapers/kleinanzeigen.py"
click node_scout "https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/scrapers/immoscout24.py"
click node_immowelt "https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/scrapers/immowelt.py"
click node_wg "https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/scrapers/wg_gesucht.py"
click node_coops "https://github.com/mrehank209/germany-wohnungsbot/tree/main/bot/scrapers"
click node_vonovia "https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/scrapers/vonovia.py"
click node_location "https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/location.py"
click node_listing "https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/models.py"
click node_dates "https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/dates.py"
click node_rent "https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/rent.py"
click node_money "https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/money.py"
click node_storage "https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/storage.py"
click node_telegram "https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/telegram.py"
click node_contact "https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/contact.py"
click node_browser "https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/browser.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_wizard,node_config toneBlue
class node_scraper_registry,node_scraper_base,node_klein,node_scout,node_immowelt,node_wg,node_coops,node_vonovia,node_browser toneAmber
class node_main,node_location,node_listing,node_dates,node_rent,node_money,node_storage toneMint
class node_telegram,node_contact toneRose
class node_user,node_telegram_service,node_rental_sites toneIndigo
```

## Components

### Setup and preferences

- [Setup wizard](https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/wizard.py): `bot/wizard.py`
- [Search configuration](https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/config.py): `bot/config.py`

### Portal discovery

- [Scraper registry](https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/scrapers/__init__.py): `bot/scrapers/__init__.py`
- [Scraper base](https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/scrapers/base.py): `bot/scrapers/base.py`
- [Kleinanzeigen scraper](https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/scrapers/kleinanzeigen.py): `bot/scrapers/kleinanzeigen.py`
- [ImmoScout24 scraper](https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/scrapers/immoscout24.py): `bot/scrapers/immoscout24.py`
- [Immowelt scraper](https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/scrapers/immowelt.py): `bot/scrapers/immowelt.py`
- [WG-Gesucht scraper](https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/scrapers/wg_gesucht.py): `bot/scrapers/wg_gesucht.py`
- [Local co-op scrapers](https://github.com/mrehank209/germany-wohnungsbot/tree/main/bot/scrapers): `bot/scrapers`
- [Vonovia scraper](https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/scrapers/vonovia.py): `bot/scrapers/vonovia.py`
- [Persistent browser](https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/browser.py): `bot/browser.py`

### Matching and state

- [Polling coordinator](https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/main.py): `bot/main.py`
- [City lookup](https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/location.py): `bot/location.py`
- [Listing model](https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/models.py): `bot/models.py`
- [Date parsing](https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/dates.py): `bot/dates.py`
- [Warm-rent lookup](https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/rent.py): `bot/rent.py`
- [Euro parsing](https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/money.py): `bot/money.py`
- [Listing and delivery state](https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/storage.py): `bot/storage.py`

### Alerts and contact

- [Telegram delivery](https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/telegram.py): `bot/telegram.py`
- [Kleinanzeigen contact](https://github.com/mrehank209/germany-wohnungsbot/blob/main/bot/contact.py): `bot/contact.py`

### Other components

- **Apartment seeker**
- **Telegram**
- **Rental platforms**

## Connections

- Apartment seeker → Setup wizard: sets preferences (evidence: `README.md`)
- Setup wizard → Search configuration: writes settings (evidence: `README.md`)
- Polling coordinator → Search configuration: loads settings (evidence: `bot/main.py`)
- Polling coordinator → Scraper registry: selects scrapers (evidence: `bot/main.py`)
- Scraper registry → Kleinanzeigen scraper: registers (evidence: `bot/scrapers/__init__.py`)
- Scraper registry → ImmoScout24 scraper: registers (evidence: `bot/scrapers/__init__.py`)
- Scraper registry → Immowelt scraper: registers (evidence: `bot/scrapers/__init__.py`)
- Scraper registry → WG-Gesucht scraper: registers (evidence: `bot/scrapers/__init__.py`)
- Scraper registry → Local co-op scrapers: registers (evidence: `bot/scrapers/__init__.py`)
- Scraper registry → Vonovia scraper: registers (evidence: `bot/scrapers/__init__.py`)
- Polling coordinator → Scraper base: fetches listings (evidence: `bot/main.py`)
- Scraper base → Kleinanzeigen scraper: provides shared behavior (evidence: `bot/scrapers/kleinanzeigen.py`)
- Scraper base → ImmoScout24 scraper: provides shared behavior (evidence: `bot/scrapers/immoscout24.py`)
- Polling coordinator → Persistent browser: opens browser (evidence: `bot/main.py`)
- Polling coordinator → City lookup: checks city (evidence: `bot/main.py`)
- Kleinanzeigen scraper → City lookup: resolves city (evidence: `bot/scrapers/kleinanzeigen.py`)
- Polling coordinator → Listing model: filters listings (evidence: `bot/main.py`)
- Scraper base → Listing model: builds listings (evidence: `bot/scrapers/base.py`)
- Kleinanzeigen scraper → Date parsing: parses publication dates (evidence: `bot/scrapers/kleinanzeigen.py`)
- ImmoScout24 scraper → Date parsing: parses publication dates (evidence: `bot/scrapers/immoscout24.py`)
- ImmoScout24 scraper → Warm-rent lookup: enriches rent (evidence: `bot/scrapers/immoscout24.py`)
- Scraper base → Warm-rent lookup: looks up rent (evidence: `bot/scrapers/base.py`)
- Search configuration → Euro parsing: parses rent limits (evidence: `bot/config.py`)
- Polling coordinator → Listing and delivery state: reads and updates state (evidence: `bot/main.py`)
- Polling coordinator → Telegram delivery: sends alerts (evidence: `bot/main.py`)
- Telegram delivery → Telegram: delivers messages (evidence: `bot/telegram.py`)
- Polling coordinator → Kleinanzeigen contact: contacts new matches (evidence: `bot/main.py`)
- Kleinanzeigen contact → Persistent browser: uses browser session
- Kleinanzeigen scraper → Rental platforms: fetches listings (evidence: `README.md`)
- ImmoScout24 scraper → Rental platforms: fetches listings (evidence: `README.md`)
- Immowelt scraper → Rental platforms: fetches listings (evidence: `README.md`)
- WG-Gesucht scraper → Rental platforms: fetches listings (evidence: `README.md`)
- Local co-op scrapers → Rental platforms: fetches listings (evidence: `README.md`)
- Vonovia scraper → Rental platforms: fetches listings (evidence: `README.md`)