# itsbk13/spyx-bot architecture

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

- Interactive diagram: https://gitdiagram.com/itsbk13/spyx-bot
- Repository: https://github.com/itsbk13/spyx-bot

## Overview

SpyX Bot lets Telegram users manage Twitter accounts to monitor, then receive alerts when those accounts gain new followers. The documented workflow is implemented through command handling and an update job that compares shared follower data with each user's history and sends Telegram notifications. The README also describes profile-rich alerts, history, filtering, and privacy. The sampled code shows CSV-to-SQLite ingestion and per-user comparison; the source excerpts do not establish how follower CSVs are obtained, so that upstream step is omitted.

Main entry points: [`commands.py`](https://github.com/itsbk13/spyx-bot/blob/main/commands.py) (Bot commands), [`update_script.py`](https://github.com/itsbk13/spyx-bot/blob/main/update_script.py) (Follower update job), [`KOL_SpyX_BOT.py`](https://github.com/itsbk13/spyx-bot/blob/main/KOL_SpyX_BOT.py) (Bot entrypoint), [`database.py`](https://github.com/itsbk13/spyx-bot/blob/main/database.py) (Tracking database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_telegram["Telegram interface"]
  node_commands["Bot commands<br/>[commands.py]"]
end

subgraph group_monitoring["Follower monitoring"]
  node_update_job["Follower update job<br/>[update_script.py]"]
  node_csv_data["Follower CSV input"]
  node_alert["Follower alert<br/>[update_script.py]"]
end

subgraph group_storage["Tracking storage"]
  node_tracking_db[("Tracking database<br/>[database.py]")]
  node_user_history[("Per-user follower history")]
  node_shared_history[("Shared follower history")]
end

subgraph group_runtime["Bot runtime"]
  node_bot_entry["Bot entrypoint<br/>[KOL_SpyX_BOT.py]"]
  node_config["Bot configuration<br/>[config.py]"]
  node_logger["Logging<br/>[logger.py]"]
end

node_user(("Telegram user"))
node_telegram_service["Telegram service"]

node_user -->|"sends commands"| node_telegram_service
node_telegram_service -->|"delivers updates"| node_bot_entry
node_bot_entry -->|"registers handlers"| node_commands
node_commands -->|"replies"| node_user
node_commands -->|"manages tracking"| node_tracking_db
node_commands -->|"creates and removes"| node_user_history
node_commands -->|"copies history"| node_shared_history
node_commands -->|"runs update"| node_update_job
node_bot_entry -->|"initializes tables"| node_tracking_db
node_update_job -->|"reads tracked accounts"| node_tracking_db
node_update_job -->|"reads CSV"| node_csv_data
node_update_job -->|"updates shared data"| node_shared_history
node_update_job -->|"compares and updates"| node_user_history
node_update_job -->|"builds notifications"| node_alert
node_alert -->|"sends alert"| node_telegram_service
node_config -->|"provides bot settings"| node_commands
node_bot_entry -->|"loads credentials"| node_config

click node_commands "https://github.com/itsbk13/spyx-bot/blob/main/commands.py"
click node_bot_entry "https://github.com/itsbk13/spyx-bot/blob/main/KOL_SpyX_BOT.py"
click node_config "https://github.com/itsbk13/spyx-bot/blob/main/config.py"
click node_logger "https://github.com/itsbk13/spyx-bot/blob/main/logger.py"
click node_tracking_db "https://github.com/itsbk13/spyx-bot/blob/main/database.py"
click node_user_history "https://github.com/itsbk13/spyx-bot/tree/main/userdata"
click node_shared_history "https://github.com/itsbk13/spyx-bot/tree/main/userdata/common_data"
click node_update_job "https://github.com/itsbk13/spyx-bot/blob/main/update_script.py"
click node_csv_data "https://github.com/itsbk13/spyx-bot/tree/main/userdata/common_data"
click node_alert "https://github.com/itsbk13/spyx-bot/blob/main/update_script.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_commands,node_user toneBlue
class node_update_job,node_csv_data,node_alert toneAmber
class node_tracking_db,node_user_history,node_shared_history toneMint
class node_bot_entry,node_config,node_logger toneRose
class node_telegram_service toneIndigo
```

## Components

### Telegram interface

- [Bot commands](https://github.com/itsbk13/spyx-bot/blob/main/commands.py): `commands.py`

### Follower monitoring

- [Follower update job](https://github.com/itsbk13/spyx-bot/blob/main/update_script.py): `update_script.py`
- [Follower CSV input](https://github.com/itsbk13/spyx-bot/tree/main/userdata/common_data): `userdata/common_data`
- [Follower alert](https://github.com/itsbk13/spyx-bot/blob/main/update_script.py): `update_script.py`

### Tracking storage

- [Tracking database](https://github.com/itsbk13/spyx-bot/blob/main/database.py): `database.py`
- [Per-user follower history](https://github.com/itsbk13/spyx-bot/tree/main/userdata): `userdata`
- [Shared follower history](https://github.com/itsbk13/spyx-bot/tree/main/userdata/common_data): `userdata/common_data`

### Bot runtime

- [Bot entrypoint](https://github.com/itsbk13/spyx-bot/blob/main/KOL_SpyX_BOT.py): `KOL_SpyX_BOT.py`
- [Bot configuration](https://github.com/itsbk13/spyx-bot/blob/main/config.py): `config.py`
- [Logging](https://github.com/itsbk13/spyx-bot/blob/main/logger.py): `logger.py`

### Other components

- **Telegram user**
- **Telegram service**

## Connections

- Telegram user → Telegram service: sends commands (evidence: `README.md`)
- Telegram service → Bot entrypoint: delivers updates (evidence: `KOL_SpyX_BOT.py`)
- Bot entrypoint → Bot commands: registers handlers (evidence: `KOL_SpyX_BOT.py`)
- Bot commands → Telegram user: replies (evidence: `commands.py`)
- Bot commands → Tracking database: manages tracking (evidence: `commands.py`)
- Bot commands → Per-user follower history: creates and removes (evidence: `commands.py`)
- Bot commands → Shared follower history: copies history (evidence: `commands.py`)
- Bot commands → Follower update job: runs update (evidence: `commands.py`)
- Bot entrypoint → Tracking database: initializes tables (evidence: `KOL_SpyX_BOT.py`)
- Follower update job → Tracking database: reads tracked accounts (evidence: `update_script.py`)
- Follower update job → Follower CSV input: reads CSV (evidence: `update_script.py`)
- Follower update job → Shared follower history: updates shared data (evidence: `update_script.py`)
- Follower update job → Per-user follower history: compares and updates (evidence: `update_script.py`)
- Follower update job → Follower alert: builds notifications (evidence: `update_script.py`)
- Follower alert → Telegram service: sends alert (evidence: `update_script.py`)
- Bot configuration → Bot commands: provides bot settings (evidence: `commands.py`)
- Bot entrypoint → Bot configuration: loads credentials (evidence: `KOL_SpyX_BOT.py`)
