# albertcamulation/pokemon_tg_bot architecture

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

- Interactive diagram: https://gitdiagram.com/albertcamulation/pokemon_tg_bot
- Repository: https://github.com/albertcamulation/pokemon_tg_bot

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    subgraph "External Services"
        style ExternalServices fill:none,stroke:none
        Telegram["Telegram Bot API"]:::external
        GitHubRaw["GitHub Raw (Data Source)"]:::external
        CloudflareKV["Cloudflare KV Storage"]:::cloud
    end

    %% Serverless Runtime
    subgraph "Serverless Runtime (Cloudflare Workers)" 
        style WorkerRuntime fill:none,stroke:none
        Worker["Entry Point\nworker.ts"]:::code
        subgraph "Handlers" 
            style Handlers fill:none,stroke:#888,stroke-dasharray: 5 5
            Index["index.ts"]:::code
            AdminH["admin.ts"]:::code
            EventH["event.ts"]:::code
            LeagueH["league.ts"]:::code
            MenuH["menu.ts"]:::code
            SearchH["search.ts"]:::code
            TrashH["trash.ts"]:::code
        end
        subgraph "Utilities"
            style Utils fill:none,stroke:#888,stroke-dasharray: 5 5
            Cache["cache.ts"]:::code
            Helpers["helpers.ts"]:::code
            UtilsIndex["index.ts"]:::code
            KVUtil["kv.ts"]:::code
            TelegramUtil["telegram.ts"]:::code
        end
        WebUI["Web UI Templates\nhtml.ts"]:::code
    end

    %% CI/Data Pipeline
    subgraph "CI/Data Pipeline"
        style CI fill:none,stroke:none
        GHRepo["GitHub Repository"]:::ci
        FetchJSONWF["fetch-json.yml"]:::ci
        Fetch2WF["fetch2.yaml"]:::ci
        UpdateEventsWF["update_events.yml"]:::ci
        PythonFetch["fetch_data.py"]:::ci
        PythonUpdate["update_events.py"]:::ci
        DataDir["/data (JSON)"]:::ci
        WranglerDeploy["Wrangler Deploy"]:::ci
    end

    %% Deployment Artifacts
    subgraph "Deployment Artifacts"
        style Config fill:none,stroke:none
        WranglerTOML["wrangler.toml"]:::config
        PackageJSON["package.json"]:::config
        TSConfig["tsconfig.json"]:::config
        Requirements["requirements.txt"]:::config
    end

    %% Connections - External to Runtime
    Telegram -->|"getUpdate webhook"| Worker
    Worker -->|"sendMessage"| Telegram
    Worker -->|"KV Read/Write"| CloudflareKV
    Worker -->|"fetch JSON (cache miss)"| GitHubRaw
    GitHubRaw -->|"JSON data"| CloudflareKV

    %% Runtime internal
    Worker --> Index
    Worker --> AdminH
    Worker --> EventH
    Worker --> LeagueH
    Worker --> MenuH
    Worker --> SearchH
    Worker --> TrashH
    AdminH --> CloudflareKV
    EventH --> CloudflareKV
    LeagueH --> CloudflareKV
    MenuH --> CloudflareKV
    SearchH --> CloudflareKV
    TrashH --> CloudflareKV
    Index -->|uses| Cache
    Index -->|uses| Helpers
    Index -->|uses| UtilsIndex
    Index -->|uses| KVUtil
    Index -->|uses| TelegramUtil
    AdminH --> WebUI
    WebUI --> Worker

    %% CI flows
    GHRepo --> FetchJSONWF
    GHRepo --> Fetch2WF
    GHRepo --> UpdateEventsWF
    FetchJSONWF --> PythonFetch
    Fetch2WF --> PythonFetch
    UpdateEventsWF --> PythonUpdate
    PythonFetch --> DataDir
    PythonUpdate --> DataDir
    DataDir --> WranglerDeploy
    WranglerDeploy --> Worker

    %% Deployment config
    WranglerTOML --> WranglerDeploy
    PackageJSON --> WranglerDeploy
    TSConfig --> WranglerDeploy
    Requirements --> PythonFetch
    Requirements --> PythonUpdate

    %% Click Events
    click TelegramUtil "https://github.com/albertcamulation/pokemon_tg_bot/blob/main/src/utils/telegram.ts"
    click PythonFetch "https://github.com/albertcamulation/pokemon_tg_bot/blob/main/scripts/fetch_data.py"
    click PythonUpdate "https://github.com/albertcamulation/pokemon_tg_bot/blob/main/scripts/update_events.py"
    click KVUtil "https://github.com/albertcamulation/pokemon_tg_bot/blob/main/src/utils/kv.ts"
    click FetchJSONWF "https://github.com/albertcamulation/pokemon_tg_bot/blob/main/.github/workflows/fetch-json.yml"
    click Fetch2WF "https://github.com/albertcamulation/pokemon_tg_bot/blob/main/.github/workflows/fetch2.yaml"
    click UpdateEventsWF "https://github.com/albertcamulation/pokemon_tg_bot/blob/main/.github/workflows/update_events.yml"
    click DataDir "https://github.com/albertcamulation/pokemon_tg_bot/tree/main/data/"
    click Worker "https://github.com/albertcamulation/pokemon_tg_bot/blob/main/src/worker.ts"
    click Index "https://github.com/albertcamulation/pokemon_tg_bot/blob/main/src/handlers/index.ts"
    click AdminH "https://github.com/albertcamulation/pokemon_tg_bot/blob/main/src/handlers/admin.ts"
    click EventH "https://github.com/albertcamulation/pokemon_tg_bot/blob/main/src/handlers/event.ts"
    click LeagueH "https://github.com/albertcamulation/pokemon_tg_bot/blob/main/src/handlers/league.ts"
    click MenuH "https://github.com/albertcamulation/pokemon_tg_bot/blob/main/src/handlers/menu.ts"
    click SearchH "https://github.com/albertcamulation/pokemon_tg_bot/blob/main/src/handlers/search.ts"
    click TrashH "https://github.com/albertcamulation/pokemon_tg_bot/blob/main/src/handlers/trash.ts"
    click Cache "https://github.com/albertcamulation/pokemon_tg_bot/blob/main/src/utils/cache.ts"
    click Helpers "https://github.com/albertcamulation/pokemon_tg_bot/blob/main/src/utils/helpers.ts"
    click UtilsIndex "https://github.com/albertcamulation/pokemon_tg_bot/blob/main/src/utils/index.ts"
    click KVUtil "https://github.com/albertcamulation/pokemon_tg_bot/blob/main/src/utils/kv.ts"
    click TelegramUtil "https://github.com/albertcamulation/pokemon_tg_bot/blob/main/src/utils/telegram.ts"
    click WebUI "https://github.com/albertcamulation/pokemon_tg_bot/blob/main/src/web/html.ts"
    click WranglerTOML "https://github.com/albertcamulation/pokemon_tg_bot/blob/main/wrangler.toml"
    click PackageJSON "https://github.com/albertcamulation/pokemon_tg_bot/blob/main/package.json"
    click TSConfig "https://github.com/albertcamulation/pokemon_tg_bot/blob/main/tsconfig.json"
    click Requirements "https://github.com/albertcamulation/pokemon_tg_bot/blob/main/requirements.txt"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#000
    classDef cloud fill:#FFA500,stroke:#000
    classDef code fill:#D3D3D3,stroke:#000
    classDef ci fill:#90EE90,stroke:#000
    classDef config fill:#FFDEAD,stroke:#000
```
