# ribbonjikough/uma-index-telegram-catch-bot architecture

> Architecture diagram of the GitHub repository ribbonjikough/uma-index-telegram-catch-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ribbonjikough/uma-index-telegram-catch-bot
- Repository: https://github.com/ribbonjikough/uma-index-telegram-catch-bot

## Overview

Uma-Index Telegram Bot polls uma-index.top for translated comics, resolves full-resolution images, and delivers unseen posts to subscribed Telegram chats in oldest-to-newest order. Users can subscribe, pause delivery, inspect sync status, and trigger an immediate check; a configured target chat is also supported. SQLite tracks subscribers, cached post data, and per-chat delivery history. Sent posts include a “Done reading” control that deletes the comic messages. The source is a single, partially excerpted bot.py, so subsystem boundaries are logical rather than separate modules; some links rely on README documentation.

Main entry points: [`bot.py`](https://github.com/ribbonjikough/uma-index-telegram-catch-bot/blob/main/bot.py) (PostStore)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Comic collection"]
  node_page_scan["Page traversal<br/>[bot.py]"]
  node_card_extract["Comic card extraction<br/>[bot.py]"]
  node_image_resolve["Image resolution<br/>[bot.py]"]
  node_url_upgrade["Image URL upgrade<br/>[bot.py]"]
end

subgraph group_state["Delivery state"]
  node_store["PostStore<br/>[bot.py]"]
  node_sqlite[("SQLite history<br/>[bot.py]")]
end

subgraph group_telegram["Telegram delivery"]
  node_delivery["Per-chat delivery<br/>[bot.py]"]
  node_sender["Paced Telegram sender<br/>[bot.py]"]
  node_done_control["Done-reading control<br/>[bot.py]"]
end

subgraph group_controls["Bot controls"]
  node_commands["Command handlers<br/>[bot.py]"]
  node_sync["Sync and polling<br/>[bot.py]"]
end

node_reader(("Chat users"))
node_source_site["uma-index.top"]
node_image_apis["Image API services"]
node_telegram_service["Telegram"]

node_reader -->|"sends commands"| node_commands
node_commands -->|"updates subscriptions"| node_store
node_commands -->|"starts or triggers"| node_sync
node_sync -->|"scans pages"| node_page_scan
node_page_scan -->|"reads comics"| node_source_site
node_page_scan -->|"extracts cards"| node_card_extract
node_card_extract -->|"resolves images"| node_image_resolve
node_image_resolve -->|"queries image APIs"| node_image_apis
node_image_resolve -->|"normalizes URLs"| node_url_upgrade
node_sync -->|"checks delivery history"| node_store
node_store -->|"reads and writes"| node_sqlite
node_sync -->|"dispatches posts"| node_delivery
node_delivery -->|"sends comics"| node_sender
node_sender -->|"posts messages"| node_telegram_service
node_delivery -->|"records delivery"| node_store
node_sender -->|"attaches control"| node_done_control
node_reader -->|"activates control"| node_done_control
node_done_control -->|"deletes messages"| node_telegram_service
node_commands -->|"reads status"| node_store

click node_commands "https://github.com/ribbonjikough/uma-index-telegram-catch-bot/blob/main/bot.py"
click node_sync "https://github.com/ribbonjikough/uma-index-telegram-catch-bot/blob/main/bot.py"
click node_page_scan "https://github.com/ribbonjikough/uma-index-telegram-catch-bot/blob/main/bot.py"
click node_card_extract "https://github.com/ribbonjikough/uma-index-telegram-catch-bot/blob/main/bot.py"
click node_image_resolve "https://github.com/ribbonjikough/uma-index-telegram-catch-bot/blob/main/bot.py"
click node_url_upgrade "https://github.com/ribbonjikough/uma-index-telegram-catch-bot/blob/main/bot.py"
click node_store "https://github.com/ribbonjikough/uma-index-telegram-catch-bot/blob/main/bot.py"
click node_sqlite "https://github.com/ribbonjikough/uma-index-telegram-catch-bot/blob/main/bot.py"
click node_delivery "https://github.com/ribbonjikough/uma-index-telegram-catch-bot/blob/main/bot.py"
click node_sender "https://github.com/ribbonjikough/uma-index-telegram-catch-bot/blob/main/bot.py"
click node_done_control "https://github.com/ribbonjikough/uma-index-telegram-catch-bot/blob/main/bot.py"

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_page_scan,node_card_extract,node_image_resolve,node_url_upgrade,node_reader toneBlue
class node_store,node_sqlite toneAmber
class node_delivery,node_sender,node_done_control,node_image_apis toneMint
class node_commands,node_sync toneRose
class node_source_site,node_telegram_service toneIndigo
```

## Components

### Comic collection

- [Page traversal](https://github.com/ribbonjikough/uma-index-telegram-catch-bot/blob/main/bot.py): `bot.py`
- [Comic card extraction](https://github.com/ribbonjikough/uma-index-telegram-catch-bot/blob/main/bot.py): `bot.py`
- [Image resolution](https://github.com/ribbonjikough/uma-index-telegram-catch-bot/blob/main/bot.py): `bot.py`
- [Image URL upgrade](https://github.com/ribbonjikough/uma-index-telegram-catch-bot/blob/main/bot.py): `bot.py`

### Delivery state

- [PostStore](https://github.com/ribbonjikough/uma-index-telegram-catch-bot/blob/main/bot.py): `bot.py`
- [SQLite history](https://github.com/ribbonjikough/uma-index-telegram-catch-bot/blob/main/bot.py): `bot.py`

### Telegram delivery

- [Per-chat delivery](https://github.com/ribbonjikough/uma-index-telegram-catch-bot/blob/main/bot.py): `bot.py`
- [Paced Telegram sender](https://github.com/ribbonjikough/uma-index-telegram-catch-bot/blob/main/bot.py): `bot.py`
- [Done-reading control](https://github.com/ribbonjikough/uma-index-telegram-catch-bot/blob/main/bot.py): `bot.py`

### Bot controls

- [Command handlers](https://github.com/ribbonjikough/uma-index-telegram-catch-bot/blob/main/bot.py): `bot.py`
- [Sync and polling](https://github.com/ribbonjikough/uma-index-telegram-catch-bot/blob/main/bot.py): `bot.py`

### Other components

- **Chat users**
- **uma-index.top**
- **Image API services**
- **Telegram**

## Connections

- Chat users → Command handlers: sends commands (evidence: `README.md`)
- Command handlers → PostStore: updates subscriptions (evidence: `README.md`)
- Command handlers → Sync and polling: starts or triggers (evidence: `README.md`)
- Sync and polling → Page traversal: scans pages (evidence: `README.md`)
- Page traversal → uma-index.top: reads comics (evidence: `README.md`)
- Page traversal → Comic card extraction: extracts cards (evidence: `bot.py`)
- Comic card extraction → Image resolution: resolves images (evidence: `bot.py`)
- Image resolution → Image API services: queries image APIs (evidence: `bot.py`)
- Image resolution → Image URL upgrade: normalizes URLs (evidence: `bot.py`)
- Sync and polling → PostStore: checks delivery history (evidence: `bot.py`)
- PostStore → SQLite history: reads and writes (evidence: `bot.py`)
- Sync and polling → Per-chat delivery: dispatches posts (evidence: `bot.py`)
- Per-chat delivery → Paced Telegram sender: sends comics (evidence: `bot.py`)
- Paced Telegram sender → Telegram: posts messages (evidence: `README.md`)
- Per-chat delivery → PostStore: records delivery (evidence: `bot.py`)
- Paced Telegram sender → Done-reading control: attaches control (evidence: `README.md`)
- Chat users → Done-reading control: activates control (evidence: `README.md`)
- Done-reading control → Telegram: deletes messages (evidence: `README.md`)
- Command handlers → PostStore: reads status (evidence: `README.md`)