Note: This repository was generated by the 🍪 CookieBlueprint.

FlatPulse 🏠⚡

Alertes immobilières en temps réel pour le marché suisse — Plus rapide que les portails, plus intelligent que Comparis, 10x moins cher que MieterPlus.

---

Le problème

En Suisse, un bon appartement part en heures. Les locataires paient CHF 30+/mois pour MieterPlus (qui donne accès à 23 annonces sur 863 à Zürich). Comparis agrège les portails, mais lentement et sans filtres intelligents.

La solution

FlatPulse scrape les agences directement à la source (Naef, Burger, Comptoir, etc.) pour détecter les annonces avant qu'elles n'apparaissent sur les portails. Un LLM gratuit extrait les données structurées des descriptions (machine à laver, animaux, balcon...), un moteur de matching score chaque annonce, et les notifications arrivent sur Telegram en < 3 minutes.

---

Architecture

[Sites d'agences]                [Utilisateurs]
  Naef, Burger,                    Telegram, Email
  Comptoir, ...                         ↑
       ↓                               |
  ┌─────────┐   ┌───────┐   ┌─────────┐   ┌────────────┐
  │ Scrapers │──→│ Dedup │──→│ LLM     │──→│ Matching   │──→ Notifications
  │ httpx +  │   │ SHA-  │   │ Groq /  │   │ Hard+Soft  │
  │ parsel   │   │ 256   │   │ Gemini  │   │ Score 0-100│
  └─────────┘   └───────┘   └─────────┘   └────────────┘
       ↓                          ↓              ↓
  ┌──────────────────────────────────────────────────────┐
  │              PostgreSQL 16 + Redis 7                 │
  └──────────────────────────────────────────────────────┘
       ↓
  ┌──────────────────────────────────────────────────────┐
  │           Prometheus + Grafana (monitoring)          │
  └──────────────────────────────────────────────────────┘

Stack technique

Composant	Technologie	Pourquoi
Langage	Python 3.12+	Écosystème scraping mature, async natif
Scraping	httpx + parsel	Async HTTP + parsing CSS/XPath rapide (lxml-based)
LLM	Groq (Llama 3.3 70B), Gemini Flash	Gratuit, rapide, fallback chain
Base de données	PostgreSQL 16	JSONB pour données flexibles, GIN index
Cache	Redis 7	Rate limiting, dedup rapide
Notifications	python-telegram-bot, aiosmtplib	Telegram temps réel, email fallback
Monitoring	Prometheus + Grafana	Métriques, dashboards, alertes
Logging	logging (JSON structuré)	Debug en prod
Tests	unittest	Bibliothèque standard, contract tests
Hosting	Infomaniak VPS Lite	Suisse, ~CHF 7/mois

Getting Started

After runnig the Cookiecutter script, you'll have to create a repository to add your code to Github:

git init
git add --all
git commit -m "Initial commit"
git remote add origin git@github.com:Julien-hae/FlatPulse.git
git branch -M master
git push -u origin master

This is a basic project you can fork. So far, the only things it can do is just "Hello World" but you can call it directly in the terminal after the installation using the command poetry run entrypoint -w World

Setup

Install WSL

If not already installed, install WSL. Once thise is done make sure you run the following command

 # Update the package index and install the build-essential packace (C/C++ compiler, Make, Librariey like libc6-dev, etc):
sudo apt update
sudo apt install -y make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

Install Python

If not already installed, install Python. The recommended way is to use pyenv, which allows multiple parallel Python installations which can be automatically selected per project you're working on.

# Install Python if necessary
pyenv install 3.11
pyenv shell 3.11

Install Poetry

If not already installed, get Poetry using pipx according to https://python-poetry.org/docs/#installation. If your are new to Poetry, you may find https://python-poetry.org/docs/basic-usage/ interesting.

Create Environment

Execute the following in a terminal:

# Create venv and install all dependencies
make

# Cleanup venv
make clean

Do not forget to activate your virtualenv when done with the makefile

Usage

Contents and Concepts

At first glance one may be overwhelmed by the amount of files and folders present in this directory. This is mainly due to the fact, that each tool uses its own configuration file. The situation has improved with more and more tools adding support for pyproject.toml. The following two tables describe the main structure of the project:

Folder	Purpose
.venv	This is where the Poetry-managed venv lives.
.vscode	This is where settings for vscode live. Some useful defaults are added in case you use vscode in your project. If not, this can savely be deleted.
src	Main directory for the python code. Most of the times this will contain one subfolder with the main module of the project. flatpulse in our case. Replace this with your own module-name.
tests	Directory containing all tests. This directory will be scanned by the test-infrastructure to find testcases.

File	Purpose
.gitattributes	Attributes for git are defined in this file, such as automatic line-ending conversion.
.gitignore	This file contains a list of path patterns that you want to ignore for git (they will never appear in commits).
.pre-commit-config.yaml	This file contains configuration for the pre-commit hook, which is run whenever you git commit, you can configure running code quality tools and tests here.
poetry.toml	Configuration for Poetry.
pyproject.toml	This file contains meta information for your project, as well as a high-level specification of the dependencies of your project, from which Poetry will do its dependency resolution and generate the poetry.lock. Also, it contains some customization for code-quality tools. Check PEP 621 for details.
README.md	This file. Document how to develop and use your application in here.

Environment Variable

The following environment variables may be used to configure flatpulse:

Environment Variable	Purpose	Default Value	Allowed Values
LOG_LEVEL	Sets the default log level here.	"INFO"	See Python Standard Library API-Reference