wohnbot/.github/copilot-instructions.md

Copilot Instructions for wohn-bot

Project Overview

A Python-based apartment monitoring bot for Berlin's public housing portal (inberlinwohnen.de) and WG rooms (wgcompany.de). Monitors listings from 6 housing companies (HOWOGE, Gewobag, Degewo, Gesobau, Stadt und Land, WBM) plus WGcompany, and sends Telegram notifications with optional auto-application via Playwright browser automation.

Architecture

Modularized structure with the following key components:

• main.py: Entry point for the bot.
• handlers/: Contains company-specific handlers for auto-apply functionality. Each handler is responsible for automating the application process for a specific housing company. Includes:
  • howoge_handler.py
  • gewobag_handler.py
  • degewo_handler.py
  • gesobau_handler.py
  • stadtundland_handler.py
  • wbm_handler.py
  • base_handler.py: Provides shared functionality for all handlers.
• application_handler.py: Delegates application tasks to the appropriate handler based on the company.
• telegram_bot.py: Handles Telegram bot commands and notifications.

Data flow: Fetch listings → Compare with listings.json / wgcompany_listings.json → Detect new → Log to CSV → Auto-apply if autopilot enabled → Save to applications.json → Send Telegram notification.

Key Patterns

Company-specific handlers

Each housing company has a dedicated handler in the handlers/ directory. When adding support for a new company:

1. Create a new handler file in handlers/ (e.g., newcompany_handler.py).
2. Implement the handler by extending BaseHandler and overriding necessary methods.
3. Update application_handler.py to include the new handler in the handlers dictionary.

Listing identification

Listings are hashed by md5(key_fields)[:12] to generate stable IDs:

• InBerlin: md5(rooms+size+price+address)
• WGcompany: md5(link+price+size)

State management

• state.json - Runtime state (autopilot toggle)
• listings.json - Previously seen inberlinwohnen listings
• wgcompany_listings.json - Previously seen WGcompany listings
• applications.json - Application history with success/failure status
• listing_times.csv / wgcompany_times.csv - Time-series data for pattern analysis

Development

Run locally

# Install dependencies (requires Playwright)
pip install -r requirements.txt
playwright install chromium

# Set env vars and run
export TELEGRAM_BOT_TOKEN=... TELEGRAM_CHAT_ID=...
python main.py

Docker (production)

cp .env.example .env  # Configure credentials
docker compose up -d
docker compose logs -f

Debugging

• Screenshots saved to data/ on application failures (*_nobtn_*.png)
• HTML saved to data/debug_page.html (inberlin) and data/wgcompany_debug.html
• Full logs in data/monitor.log

Environment Variables

Required: TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID InBerlin login: INBERLIN_EMAIL, INBERLIN_PASSWORD Form data: FORM_ANREDE, FORM_VORNAME, FORM_NACHNAME, FORM_EMAIL, FORM_PHONE, FORM_STRASSE, FORM_HAUSNUMMER, FORM_PLZ, FORM_ORT, FORM_PERSONS, FORM_CHILDREN, FORM_INCOME WGcompany: WGCOMPANY_ENABLED, WGCOMPANY_MIN_SIZE, WGCOMPANY_MAX_SIZE, WGCOMPANY_MIN_PRICE, WGCOMPANY_MAX_PRICE, WGCOMPANY_BEZIRK

Common Tasks

Fix a broken company handler

Check data/*_nobtn_*.png screenshots and data/debug_page.html to see actual page structure. Update selectors in the corresponding handler file in handlers/.

Add Telegram command

1. Add a case in TelegramBot._handle_update().
2. Implement the corresponding _handle_{command}_command() method.

Modify listing extraction

• InBerlin: Update regex patterns in InBerlinMonitor.fetch_listings(). Test against data/debug_page.html.
• WGcompany: Update parsing in WGCompanyMonitor.fetch_listings(). Test against data/wgcompany_debug.html.

Unit Tests

Overview

The project includes unit tests to ensure functionality and reliability. Key test files:

• tests/test_telegram_bot.py: Tests the Telegram bot's commands and messaging functionality.
• tests/test_error_rate_plot.py: Tests the error rate plot generator for autopilot applications.

Running Tests

To run the tests, use:

pytest tests/

Ensure all dependencies are installed and the environment is configured correctly before running the tests.