How zaqqazzaqqaz89-del/telegram_screenshot_bot works
Тип проекта и назначение (что рисуем)
Это инфраструктурно-простой, но интеграционный проект: 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 диаграммы без предположений.