# zaqqazzaqqaz89-del/telegram_screenshot_bot architecture

> Architecture diagram of the GitHub repository zaqqazzaqqaz89-del/telegram_screenshot_bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zaqqazzaqqaz89-del/telegram_screenshot_bot
- Repository: https://github.com/zaqqazzaqqaz89-del/telegram_screenshot_bot

## Overview

##### Тип проекта и назначение (что рисуем)
Это **инфраструктурно-простой, но интеграционный** проект: **Telegram Bot (Python)**, который:
- принимает команды пользователя в Telegram,
- по запросу или по расписанию делает **скриншоты веб-страниц** через **Playwright + Chromium**,
- отправляет результат обратно пользователю,
- деплоится как **Render Web Service** в режиме **Webhook** (или локально в polling),
- опционально запускается в **Docker**, чтобы гарантировать работу браузера.

По сути, это “edge automation” сервис: вход = Telegram updates, выход = изображения, вычисление = headless браузер.

##### Разбор структуры репозитория (что превращать в блоки)
По дереву файлов видно, что проект **монолитный** (без папок `src/`, `app/`), но логически делится на модули:

- `main.py` — **входная точка приложения** (Webhook-версия). Здесь будут:
- регистрация Telegram handlers (команды `/start`, `/seturl`, `/screenshot`, `/schedule`, …),
- конфигурация webhook endpoint (`/webhook`),
- запуск web server внутри `python-telegram-bot[webhooks]`.
- `screenshot_service.py` — **сервисный слой создания скриншота**:
- запуск Playwright,
- открытие URL,
- (опционально) поиск элемента по CSS-селектору,
- сохранение результата в файл/байты,
- возврат пути/bytes для отправки в Telegram.
- `config.py` — **конфигурация** (env vars: `TELEGRAM_TOKEN`, возможно webhook url/port и т.п.).
- `requirements.txt` — зависимости, ключевое: `python-telegram-bot[webhooks]`, `playwright`.
- `Dockerfile` — **container runtime** (важно для Chromium).
- `.env.example` — пример конфигурации.
- `EXAMPLES.md`, `ПОШАГОВАЯ_ИНСТРУКЦИЯ.md`, `ШПАРГАЛКА.md` — документация (не runtime-компоненты, но могут подсказать сценарии).
- Папка `screenshots/` создается динамически — это **временное файловое хранилище** на локальном диске инстанса.

##### Что README говорит об архитектуре (важные факты для диаграммы)
Из README надо обязательно отразить:
- Режим деплоя: **Render Web Service + Webhook** (основной).
- Режим dev: **Polling** (локально).
- Скриншоты: **вся страница** или **элемент по CSS selector**.
- Есть **расписание** (значит в процессе живет scheduler/job queue внутри процесса).
- Критично: в Build Command ставят `playwright install chromium` (или Docker, где Chromium предустановлен).

##### Как нарисовать “самую точную” архитектурную диаграмму (практический план)
Ниже — как я бы инструктировал рисовать, чтобы было максимально полезно principal-инженеру и команде. Рекомендую сделать **2–3 уровня** (C4-подобно): Context → Container → Component.

##### Уровень A — System Context (1 диаграмма)
Цель: показать систему как “черный ящик” и внешние интеграции.

**Блоки:**
##### Target Websites (любой внешний сайт, который скриншотим).

**Стрелки (обязательно подписывать):**
- User → Telegram: “commands/messages”.
- Telegram → Render service: “Webhook Update (HTTPS POST)”.
- Render service → Telegram: “sendPhoto/sendDocument API call (HTTPS)”.
- Render service → Target websites: “HTTP(S) page load via Playwright Chromium”.

**Подписи/аннотации:**
- “Webhook endpoint: `/webhook`” (из README).
- “HTTPS required” (implicit via Render + Telegram).
- “No persistent DB” (если реально нет — по дереву не видно БД).

##### Уровень B — Container / Deployment (1 диаграмма)
Цель: показать реальные runtime-части внутри Render и их зависимости.

**Контейнеры/узлы:**
##### Render Web Service Instance
- Внутри: “Python Process (main.py)”
##### Embedded Webhook Server
- (Это часть python-telegram-bot webhooks, но лучше вынести как подпроцесс/подкомпонент: “HTTP server handling `/webhook`”)
##### Scheduler / Job Runner
- Логический контейнер внутри процесса (job queue / scheduled tasks)
##### Playwright Runtime
- Python bindings + browser driver
##### Chromium Headless
- Отдельный runtime компонент (часто причина проблем, поэтому выделяйте явно)
##### Ephemeral Filesystem
- папка `./screenshots/` как временное хранилище

**Внешние зависимости:**
- Telegram Bot API
- External Websites (targets)

**Deployment варианты (важно отразить как примечание или отдельной маленькой диаграммой):**
- **Non-Docker path:** Build installs chromium (`playwright install chromium`) на Render.
- **Docker path:** Chromium baked into image via `Dockerfile`.

**Стрелки:**
- Webhook Server → Bot Handlers: “dispatch update”.
- Bot Handlers → Scheduler: “create/update scheduled jobs”.
- Bot Handlers → Screenshot Service: “request screenshot(url, selector)”.
- Screenshot Service → Playwright → Chromium: “render & capture”.
- Screenshot output → Filesystem: “write PNG”.
- Bot Handlers → Telegram API: “upload/send photo”.

Цель: максимально точно отразить структуру кода (по этому репо).

**Компоненты (соответствуют файлам):**
- `main.py`
- Telegram command handlers:
- `/start`, `/help`, `/settings`
- `/seturl`, `/setselector`
- `/screenshot`
- `/schedule` (вкл/выкл, настройка времени)
- Webhook bootstrap: `application.run_webhook(...)`
- State management (где хранятся url/selector/schedule per chat) — даже если это in-memory dict, вынесите как “In-memory Chat Settings Store”.
- `screenshot_service.py`
- `capture_full_page(url)` / `capture_selector(url, css_selector)` (названия условные, но логику выделить)
- “timeout/retry” (если есть; если нет — как потенциальная зона)
- “save to ./screenshots + return path/bytes”
- `config.py`
- чтение env (`TELEGRAM_TOKEN`, возможно `PORT`, `WEBHOOK_URL`, etc.)

**Связи:**
- `main.py` → `config.py` (load settings).
- `main.py` → `screenshot_service.py` (use screenshot functionality).
- `screenshot_service.py` → Playwright/Chromium (external library/runtime).
- `main.py` → Telegram Bot API (external API).

##### Важные архитектурные особенности, которые стоит подчеркнуть на диаграмме
1. **Webhook-first**: входящие события приходят извне (Telegram → ваш `/webhook`), т.е. сервис должен быть всегда доступен по HTTPS.
2. **Headless browser как “тяжелая зависимость”**: Playwright/Chromium — отдельный блок, иначе диаграмма будет “врать” (будто это просто HTTP GET).
3. **Эфемерное хранилище**: `screenshots/` на Render — временное, не гарантирует персистентность. На диаграмме пометьте как “ephemeral”.
4. **Scheduler внутри процесса**: расписание — это либо job queue в памяти, либо библиотечный scheduler. В любом случае: при рестарте инстанса расписание может теряться (если нет внешнего хранилища). Это стоит явно отметить (как риск/ограничение).
##### Два режима запуска
- Prod: webhook
- Dev: polling (README предлагает `main_local.py`)

##### Как именно рисовать: элементы, подписи, цвета, стрелки (чтобы диаграмма была “инженерной”)
**Набор правил:**
- Каждый блок подписывайте: *имя + ответственность + технология*
Пример: “Screenshot Service (`screenshot_service.py`) — Playwright capture”.
- Стрелки только направленные, с подписью протокола/типа данных:
- “HTTPS POST /webhook (Telegram Update JSON)”
- “HTTPS sendPhoto (multipart/form-data)”
- “HTTP GET/JS render (Chromium)”
- Цвет/формы:
- Внешние системы (Telegram, Websites) — серые прямоугольники.
- Ваши runtime-компоненты — синие/основной цвет.
- Хранилища (даже файловые) — цилиндр или отдельная форма storage.
- Библиотеки/runtime (Playwright/Chromium) — отдельный слой/контур (например, пунктиром).
- Делайте “границу доверия” (Trust Boundary):
- Снаружи: Telegram, websites
- Внутри: Render instance
- Подпишите конфигурацию:
- Env Vars: `TELEGRAM_TOKEN`
- Build step: `playwright install chromium` (или “Docker image includes Chromium”)

##### System Context (Telegram ↔ Render Bot ↔ Websites)
2. **Deployment/Container** (Render instance: Python app + webhook server + scheduler + playwright + chromium + filesystem)
3. **Component** (main.py/config.py/screenshot_service.py + in-memory settings store + interactions)
- “/screenshot”:
1) User sends `/screenshot`
2) Telegram sends update to `/webhook`
3) Handler loads chat settings (url/selector)
4) Screenshot service runs Playwright/Chromium
5) Saves file
6) Sends image back via Telegram API
- “/schedule daily”:
1) User sets schedule
2) Scheduler triggers job at UTC time
3) Job calls same screenshot pipeline
4) Sends result

##### Короткий чеклист точности (чтобы диаграмма не “упростила” важное)
- [ ] Явно показан **Webhook endpoint** и что Telegram инициатор.
- [ ] Явно показан **Playwright + Chromium** как runtime зависимость.
- [ ] Показано **временное файловое хранилище** `screenshots/`.
- [ ] Показан **scheduler** и отмечено, хранится ли расписание персистентно (скорее всего нет).
- [ ] Отмечены **два режима запуска** (webhook vs polling) хотя бы как примечание.
- [ ] Подписаны ключевые протоколы/форматы (HTTPS, Update JSON, image upload).

Если захотите, пришлите содержимое `main.py`, `screenshot_service.py`, `config.py` — тогда можно составить прям “по функциям/классам” компонентную схему и точные sequence диаграммы без предположений.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Level A — System Context
    %% =========================
    subgraph "System Context (C4-L1)"
        U["Telegram User"]:::external
        TG["Telegram Platform\n(Bot API + Webhook Delivery)"]:::external
        WS["Target Websites\n(Any external URL)"]:::external

        subgraph "Trust Boundary: Render (Your Service)"
            RENDER["Render Web Service\n(Telegram Screenshot Bot)"]:::compute
        end
    end

    U -->|"commands/messages"| TG
    TG -->|"HTTPS_POST_/webhook\n(Telegram Update JSON)"| RENDER
    RENDER -->|"HTTPS_sendPhoto/sendDocument\n(multipart upload)"| TG
    RENDER -->|"HTTP(S)_page_load\n(JS render)"| WS

    %% =========================
    %% Level B — Container / Deployment
    %% =========================
    subgraph "Deployment / Containers (C4-L2)"
        TG2["Telegram Platform\n(Bot API)"]:::external
        WS2["Target Websites"]:::external

        subgraph "Render Web Service Instance"
            PROC["Python Process\n(main.py)"]:::compute

            WH["Embedded Webhook Server\n(python-telegram-bot webhooks)\nEndpoint: /webhook"]:::api
            HANDLERS["Bot Handlers\n(/start,/seturl,/setselector,/screenshot,/schedule,...)"]:::service

            SCHED["Scheduler / Job Runner\n(in-process; volatile on restart)"]:::service
            STORE["In-memory Chat Settings Store\n(url/selector/schedule per chat)"]:::storage

            SS["Screenshot Service\n(screenshot_service.py)"]:::service

            subgraph "Browser Runtime (heavy dependency)"
                PW["Playwright Runtime\n(Python bindings + driver)"]:::runtime
                CH["Chromium Headless"]:::runtime
            end

            FS[("Ephemeral Filesystem\n./screenshots/ (temporary)")]:::storage

            CFG["Config Loader\n(config.py)\nEnv: TELEGRAM_TOKEN, PORT, WEBHOOK_URL,..."]:::config

            NOTE1["Build/Run Variants:\n- Non-Docker: playwright install chromium\n- Docker: Chromium baked into image"]:::note
        end
    end

    TG2 -->|"HTTPS_POST_/webhook\n(Update JSON)"| WH
    WH -->|"dispatch_update"| HANDLERS
    HANDLERS -->|"read/write_settings"| STORE
    HANDLERS -->|"create/update_jobs"| SCHED
    SCHED -->|"trigger_scheduled_screenshot"| HANDLERS

    HANDLERS -->|"load_env"| CFG
    HANDLERS -->|"request_screenshot(url,selector)"| SS
    SS -->|"use"| PW
    PW -->|"launch/control"| CH
    CH -->|"render_and_capture"| PW
    SS -->|"write_png"| FS
    SS -->|"return_path_or_bytes"| HANDLERS
    HANDLERS -->|"HTTPS_sendPhoto/sendDocument"| TG2
    PW -->|"HTTP(S)_navigation"| WS2

    %% =========================
    %% Level C — Components (C4-L3 by repo files)
    %% =========================
    subgraph "Code Components (C4-L3 — Repository Files)"
        MAIN["main.py\n- app entry (webhook)\n- handler registration\n- webhook bootstrap\n- scheduler + settings store"]:::compute
        CONF["config.py\n- env var loading\n- tokens/ports/webhook url"]:::config
        SVC["screenshot_service.py\n- Playwright capture\n- full page or CSS selector\n- save to ./screenshots"]:::service

        REQ["requirements.txt\n- python-telegram-bot[webhooks]\n- playwright\n- ..."]:::artifact
        DOCKER["Dockerfile\n- container runtime\n- Chromium setup"]:::artifact
        ENVEX[".env.example\n- env template"]:::artifact

        DOCS["Docs\n- README, EXAMPLES, guides"]:::doc
        README["README.md\n- Render webhook vs local polling\n- build steps for Chromium"]:::doc
        EXM["EXAMPLES.md\n- scenarios/examples"]:::doc
        GUIDE["ПОШАГОВАЯ_ИНСТРУКЦИЯ.md\n- step-by-step"]:::doc
        CHEAT["ШПАРГАЛКА.md\n- cheat sheet"]:::doc
    end

    MAIN -->|"imports"| CONF
    MAIN -->|"calls"| SVC
    SVC -->|"depends_on"| REQ
    MAIN -->|"depends_on"| REQ
    DOCKER -->|"packages_runtime_for"| MAIN
    ENVEX -->|"documents_env_for"| CONF
    README -->|"documents_deploy_for"| MAIN
    DOCS -->|"includes"| README
    DOCS -->|"includes"| EXM
    DOCS -->|"includes"| GUIDE
    DOCS -->|"includes"| CHEAT

    %% =========================
    %% Optional — Key Sequences (summarized)
    %% =========================
    subgraph "Key Runtime Flows (summary)"
        F1["Flow: /screenshot\nupdate -> handler -> screenshot -> send photo"]:::note
        F2["Flow: /schedule\nset job -> scheduler triggers -> same pipeline"]:::note
    end

    TG -->|"update"| F1
    F1 -->|"calls"| SS
    SS -->|"stores_temp"| FS
    F1 -->|"responds_via"| TG

    HANDLERS -->|"schedule_job"| F2
    SCHED -->|"fires"| F2
    F2 -->|"reuses"| SS

    %% =========================
    %% Click Events (from component_mapping)
    %% =========================
    click MAIN "https://github.com/zaqqazzaqqaz89-del/telegram_screenshot_bot/blob/main/main.py"
    click HANDLERS "https://github.com/zaqqazzaqqaz89-del/telegram_screenshot_bot/blob/main/main.py"
    click WH "https://github.com/zaqqazzaqqaz89-del/telegram_screenshot_bot/blob/main/main.py"
    click SCHED "https://github.com/zaqqazzaqqaz89-del/telegram_screenshot_bot/blob/main/main.py"
    click STORE "https://github.com/zaqqazzaqqaz89-del/telegram_screenshot_bot/blob/main/main.py"
    click PROC "https://github.com/zaqqazzaqqaz89-del/telegram_screenshot_bot/blob/main/main.py"
    click SS "https://github.com/zaqqazzaqqaz89-del/telegram_screenshot_bot/blob/main/screenshot_service.py"
    click SVC "https://github.com/zaqqazzaqqaz89-del/telegram_screenshot_bot/blob/main/screenshot_service.py"
    click CONF "https://github.com/zaqqazzaqqaz89-del/telegram_screenshot_bot/blob/main/config.py"
    click CFG "https://github.com/zaqqazzaqqaz89-del/telegram_screenshot_bot/blob/main/config.py"
    click REQ "https://github.com/zaqqazzaqqaz89-del/telegram_screenshot_bot/blob/main/requirements.txt"
    click DOCKER "https://github.com/zaqqazzaqqaz89-del/telegram_screenshot_bot/tree/main/Dockerfile"
    click ENVEX "https://github.com/zaqqazzaqqaz89-del/telegram_screenshot_bot/blob/main/.env.example"
    click README "https://github.com/zaqqazzaqqaz89-del/telegram_screenshot_bot/blob/main/README.md"
    click EXM "https://github.com/zaqqazzaqqaz89-del/telegram_screenshot_bot/blob/main/EXAMPLES.md"
    click GUIDE "https://github.com/zaqqazzaqqaz89-del/telegram_screenshot_bot/blob/main/ПОШАГОВАЯ_ИНСТРУКЦИЯ.md"
    click CHEAT "https://github.com/zaqqazzaqqaz89-del/telegram_screenshot_bot/blob/main/ШПАРГАЛКА.md"

    %% =========================
    %% Styles
    %% =========================
    classDef external fill:#E5E7EB,stroke:#6B7280,color:#111827,stroke-width:1px
    classDef compute fill:#DBEAFE,stroke:#1D4ED8,color:#0B1B3A,stroke-width:1.2px
    classDef api fill:#CFFAFE,stroke:#0891B2,color:#042F2E,stroke-width:1.2px
    classDef service fill:#DCFCE7,stroke:#16A34A,color:#052E16,stroke-width:1.2px
    classDef runtime fill:#EDE9FE,stroke:#6D28D9,color:#2E1065,stroke-width:1.2px,stroke-dasharray: 4 3
    classDef storage fill:#FEF3C7,stroke:#D97706,color:#3A2500,stroke-width:1.2px
    classDef config fill:#FFEDD5,stroke:#EA580C,color:#431407,stroke-width:1.2px
    classDef artifact fill:#F3F4F6,stroke:#374151,color:#111827,stroke-width:1px
    classDef doc fill:#FCE7F3,stroke:#BE185D,color:#500724,stroke-width:1px
    classDef note fill:#FFF7ED,stroke:#9A3412,color:#431407,stroke-width:1px,stroke-dasharray: 3 3
```
