# fantom292992-dot/crm_analist_bot architecture

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

- Interactive diagram: https://gitdiagram.com/fantom292992-dot/crm_analist_bot
- Repository: https://github.com/fantom292992-dot/crm_analist_bot

## Overview

This is a Telegram lead-generation bot that accepts search parameters, collects company records, scores them, and presents prioritized results. The README documents the FSM, access control, per-user run isolation, pagination, and result download; however, the tree omits the referenced handlers/ and services/ implementations, so those internals are represented as an undocumented pipeline rather than assigned invented paths. The collector, scorer, and offline viewer are visible in the supplied sources. Edges into the pipeline rely on README statements; its exact internal orchestration cannot be verified from the excerpts.

Main entry points: [`bot.py`](https://github.com/fantom292992-dot/crm_analist_bot/blob/main/bot.py) (Bot runtime), [`lead_collector.py`](https://github.com/fantom292992-dot/crm_analist_bot/blob/main/lead_collector.py) (Place collector), [`lead_scorer.py`](https://github.com/fantom292992-dot/crm_analist_bot/blob/main/lead_scorer.py) (Lead scorer), [`scored_leads.csv`](https://github.com/fantom292992-dot/crm_analist_bot/blob/main/scored_leads.csv) (Scored CSV)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bot["Telegram bot"]
  node_bot_app["Bot runtime<br/>[bot.py]"]
  node_config["Bot configuration<br/>[config.py]"]
  node_pipeline["Lead pipeline"]
end

subgraph group_collection["Lead collection"]
  node_collector["Place collector<br/>[lead_collector.py]"]
  node_raw_csv["Lead CSV<br/>[leads.csv]"]
end

subgraph group_scoring["Lead scoring"]
  node_scorer["Lead scorer<br/>[lead_scorer.py]"]
  node_scored_csv["Scored CSV<br/>[scored_leads.csv]"]
end

subgraph group_results["Result viewing"]
  node_viewer["Offline viewer generator<br/>[lead_viewer.py]"]
  node_html_board["Lead board<br/>[leads.html]"]
end

node_user(("Telegram user"))
node_telegram(("Telegram"))
node_nominatim(("Nominatim geocoder"))
node_overture[("Overture Places")]

node_user -->|"sends parameters"| node_telegram
node_telegram -->|"delivers updates"| node_bot_app
node_config -->|"configures polling"| node_bot_app
node_bot_app -->|"starts pipeline"| node_pipeline
node_pipeline -->|"runs collection"| node_collector
node_collector -->|"geocodes cities"| node_nominatim
node_collector -->|"queries places"| node_overture
node_collector -->|"writes leads"| node_raw_csv
node_pipeline -->|"runs scoring"| node_scorer
node_scorer -->|"reads leads"| node_raw_csv
node_scorer -->|"writes scores"| node_scored_csv
node_user -->|"requests results"| node_bot_app
node_bot_app -->|"reloads results"| node_scored_csv
node_scored_csv -->|"loads CSV"| node_viewer
node_viewer -->|"generates board"| node_html_board

click node_bot_app "https://github.com/fantom292992-dot/crm_analist_bot/blob/main/bot.py"
click node_config "https://github.com/fantom292992-dot/crm_analist_bot/blob/main/config.py"
click node_collector "https://github.com/fantom292992-dot/crm_analist_bot/blob/main/lead_collector.py"
click node_raw_csv "https://github.com/fantom292992-dot/crm_analist_bot/blob/main/leads.csv"
click node_scorer "https://github.com/fantom292992-dot/crm_analist_bot/blob/main/lead_scorer.py"
click node_scored_csv "https://github.com/fantom292992-dot/crm_analist_bot/blob/main/scored_leads.csv"
click node_viewer "https://github.com/fantom292992-dot/crm_analist_bot/blob/main/lead_viewer.py"
click node_html_board "https://github.com/fantom292992-dot/crm_analist_bot/blob/main/leads.html"

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_bot_app,node_config,node_pipeline,node_user toneBlue
class node_collector,node_raw_csv,node_overture toneAmber
class node_scorer,node_scored_csv toneMint
class node_viewer,node_html_board toneRose
class node_telegram,node_nominatim toneIndigo
```

## Components

### Telegram bot

- [Bot runtime](https://github.com/fantom292992-dot/crm_analist_bot/blob/main/bot.py): `bot.py`
- [Bot configuration](https://github.com/fantom292992-dot/crm_analist_bot/blob/main/config.py): `config.py`
- **Lead pipeline**

### Lead collection

- [Place collector](https://github.com/fantom292992-dot/crm_analist_bot/blob/main/lead_collector.py): `lead_collector.py`
- [Lead CSV](https://github.com/fantom292992-dot/crm_analist_bot/blob/main/leads.csv): `leads.csv`

### Lead scoring

- [Lead scorer](https://github.com/fantom292992-dot/crm_analist_bot/blob/main/lead_scorer.py): `lead_scorer.py`
- [Scored CSV](https://github.com/fantom292992-dot/crm_analist_bot/blob/main/scored_leads.csv): `scored_leads.csv`

### Result viewing

- [Offline viewer generator](https://github.com/fantom292992-dot/crm_analist_bot/blob/main/lead_viewer.py): `lead_viewer.py`
- [Lead board](https://github.com/fantom292992-dot/crm_analist_bot/blob/main/leads.html): `leads.html`

### Other components

- **Telegram user**
- **Telegram**
- **Nominatim geocoder**
- **Overture Places**

## Connections

- Telegram user → Telegram: sends parameters (evidence: `README.md`)
- Telegram → Bot runtime: delivers updates (evidence: `bot.py`)
- Bot configuration → Bot runtime: configures polling (evidence: `bot.py`)
- Bot runtime → Lead pipeline: starts pipeline (evidence: `bot.py`)
- Lead pipeline → Place collector: runs collection (evidence: `README.md`)
- Place collector → Nominatim geocoder: geocodes cities (evidence: `lead_collector.py`)
- Place collector → Overture Places: queries places (evidence: `lead_collector.py`)
- Place collector → Lead CSV: writes leads (evidence: `lead_collector.py`)
- Lead pipeline → Lead scorer: runs scoring (evidence: `README.md`)
- Lead scorer → Lead CSV: reads leads (evidence: `lead_scorer.py`)
- Lead scorer → Scored CSV: writes scores (evidence: `lead_scorer.py`)
- Telegram user → Bot runtime: requests results (evidence: `README.md`)
- Bot runtime → Scored CSV: reloads results (evidence: `README.md`)
- Scored CSV → Offline viewer generator: loads CSV (evidence: `lead_viewer.py`)
- Offline viewer generator → Lead board: generates board (evidence: `lead_viewer.py`)
