How albertcamulation/pokemon_tg_bot works
Project Type & Core Purpose
• This is a serverless Telegram bot built on Cloudflare Workers.
• It provides PvP ranking lookups, type‐matchup analysis, event notifications, and admin controls via Telegram.
• It fetches/stores Pokémon-Go PvP data (rankings, moves, events), enforces gatekeeper permissions, and exposes an admin panel in chat.
Main Architectural Components
A. External Services
1. Telegram Bot API
2. GitHub Raw (PvPoke data source)
3. Cloudflare KV (key-value storage)
B. Continuous Integration / Data Ingestion
1. GitHub Actions Workflows (.github/workflows/*.yml)
2. Python scripts in /scripts that fetch JSON and commit to /data
C. Serverless Runtime
1. Cloudflare Workers (the deployed “worker” from worker.ts)
2. Route handlers in src/handlers (admin, event, league, menu, search, trash)
3. Utility modules in src/utils (cache, kv, helpers, telegram)
4. Web templates in src/web/html.ts (for admin panel UI)
D. Deployment Artifacts
1. wrangler.toml + package.json + tsconfig.json
2. Static data in /data directory (seeded via CI)
Data & Control Flows
• Bot Initialization
– Admin registers webhook via GET /registerWebhook → Cloudflare Worker → Telegram API
• Incoming Message
– Telegram sends an Update → Worker’s fetch handler (worker.ts) → routes to a specific src/handlers/* function.
– Handler reads/writes state in Cloudflare KV (permissions, trash list, cached rankings).
– If data is missing or stale, utils/cache fetches fresh JSON from GitHub Raw, caches in KV.
– Handler composes a response and calls Telegram Bot API via utils/telegram.
• Admin Panel Interaction
– Admin invokes /banlist → Worker renders HTML UI via src/web/html.ts → displays buttons
– Button clicks are routed back through worker → admin.ts updates KV (blacklist/whitelist).
Architectural Patterns & Principles
• Serverless (FaaS) – all compute on Cloudflare Workers, zero‐server maintenance.
• Event-Driven – HTTP webhook events drive the entire bot logic.
• CQRS-style Separation – read models (rankings in KV) vs. write models (admin updates, trash list).
• Cache Aside – JSON data fetched on demand from GitHub Raw, then cached in KV.
• Modular Handlers – one handler per command/feature keeps code organized.