# ehcaning/divar-telegram-bot architecture

> Architecture diagram of the GitHub repository ehcaning/divar-telegram-bot, 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/ehcaning/divar-telegram-bot
- Repository: https://github.com/ehcaning/divar-telegram-bot

## Overview

Divar Telegram Bot periodically fetches Divar search results, extracts and filters new listings, sends matching ads to a configured Telegram chat, and persists seen listing tokens. The implementation is a small single-file runtime; README documents cron as the launcher. All internal nodes point to main.py because the workflow is implemented there; no separate scheduler or storage module is present.

Main entry points: [`main.py`](https://github.com/ehcaning/divar-telegram-bot/blob/master/main.py) (Bot runtime), [`tokens.json`](https://github.com/ehcaning/divar-telegram-bot/blob/master/tokens.json) (Seen-token store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bot["Listing notifier"]
  node_runtime["Bot runtime<br/>[main.py]"]
  node_fetch["Search fetch<br/>[main.py]"]
  node_parse["Response parsing<br/>[main.py]"]
  node_listing["Listing extraction<br/>[main.py]"]
  node_filter["Deduplicate and filter<br/>[main.py]"]
  node_telegram["Message delivery<br/>[main.py]"]
  node_tokens[("Seen-token store<br/>[tokens.json]")]
end

node_cron(("Cron scheduler"))
node_divar["Divar search API"]
node_telegram_api["Telegram Bot API"]

node_cron -->|"launches"| node_runtime
node_runtime -->|"loads tokens"| node_tokens
node_runtime -->|"requests pages"| node_fetch
node_fetch -->|"fetches listings"| node_divar
node_fetch -->|"parses response"| node_parse
node_parse -->|"extracts posts"| node_listing
node_runtime -->|"processes posts"| node_filter
node_filter -->|"extracts fields"| node_listing
node_filter -->|"sends new matches"| node_telegram
node_telegram -->|"posts message"| node_telegram_api
node_runtime -->|"saves tokens"| node_tokens

click node_runtime "https://github.com/ehcaning/divar-telegram-bot/blob/master/main.py"
click node_fetch "https://github.com/ehcaning/divar-telegram-bot/blob/master/main.py"
click node_parse "https://github.com/ehcaning/divar-telegram-bot/blob/master/main.py"
click node_listing "https://github.com/ehcaning/divar-telegram-bot/blob/master/main.py"
click node_filter "https://github.com/ehcaning/divar-telegram-bot/blob/master/main.py"
click node_telegram "https://github.com/ehcaning/divar-telegram-bot/blob/master/main.py"
click node_tokens "https://github.com/ehcaning/divar-telegram-bot/blob/master/tokens.json"

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_runtime,node_fetch,node_parse,node_listing,node_filter,node_telegram,node_tokens toneBlue
class node_cron toneRose
class node_divar,node_telegram_api toneMint
```

## Components

### Listing notifier

- [Bot runtime](https://github.com/ehcaning/divar-telegram-bot/blob/master/main.py): `main.py`
- [Search fetch](https://github.com/ehcaning/divar-telegram-bot/blob/master/main.py): `main.py`
- [Response parsing](https://github.com/ehcaning/divar-telegram-bot/blob/master/main.py): `main.py`
- [Listing extraction](https://github.com/ehcaning/divar-telegram-bot/blob/master/main.py): `main.py`
- [Deduplicate and filter](https://github.com/ehcaning/divar-telegram-bot/blob/master/main.py): `main.py`
- [Message delivery](https://github.com/ehcaning/divar-telegram-bot/blob/master/main.py): `main.py`
- [Seen-token store](https://github.com/ehcaning/divar-telegram-bot/blob/master/tokens.json): `tokens.json`

### Other components

- **Cron scheduler**
- **Divar search API**
- **Telegram Bot API**

## Connections

- Cron scheduler → Bot runtime: launches (evidence: `README.md`)
- Bot runtime → Seen-token store: loads tokens (evidence: `main.py`)
- Bot runtime → Search fetch: requests pages (evidence: `main.py`)
- Search fetch → Divar search API: fetches listings (evidence: `main.py`)
- Search fetch → Response parsing: parses response (evidence: `main.py`)
- Response parsing → Listing extraction: extracts posts (evidence: `main.py`)
- Bot runtime → Deduplicate and filter: processes posts (evidence: `main.py`)
- Deduplicate and filter → Listing extraction: extracts fields (evidence: `main.py`)
- Deduplicate and filter → Message delivery: sends new matches (evidence: `main.py`)
- Message delivery → Telegram Bot API: posts message (evidence: `main.py`)
- Bot runtime → Seen-token store: saves tokens (evidence: `main.py`)