# amirwebd3v/automation-booking-system architecture

> Architecture diagram of the GitHub repository amirwebd3v/automation-booking-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amirwebd3v/automation-booking-system
- Repository: https://github.com/amirwebd3v/automation-booking-system

## Overview

sim24 Auto Data Booker checks a subscriber’s remaining data and books a 2 GB packet below the 0.5 GB threshold. The primary run moves from configuration/state loading through browser login, usage extraction, decision, and conditional booking, then reports and persists the outcome. Scheduling and Telegram control are separate entry paths: an hourly Cloudflare Worker and an always-on bot can dispatch runs and expose status; both also support captcha replies via shared Gist state. The graph follows README-documented behavior where source excerpts are incomplete; unsampled relationships are left out or marked unverified.

Main entry points: [`main.py`](https://github.com/amirwebd3v/automation-booking-system/blob/main/main.py) (Run orchestrator), [`captcha_handler.py`](https://github.com/amirwebd3v/automation-booking-system/blob/main/captcha_handler.py) (Captcha handler), [`cloudflare_trigger/worker.js`](https://github.com/amirwebd3v/automation-booking-system/blob/main/cloudflare_trigger/worker.js) (Cron and webhook), [`login.py`](https://github.com/amirwebd3v/automation-booking-system/blob/main/login.py) (Browser login)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_run["Booking workflow"]
  node_entry["Run orchestrator<br/>[main.py]"]
  node_login["Browser login<br/>[login.py]"]
  node_usage["Usage extraction<br/>[data_checker.py]"]
  node_decision["Threshold decision<br/>[decision_engine.py]"]
  node_booking["2 GB booking<br/>[booking.py]"]
end

subgraph group_captcha["Captcha resolution"]
  node_captcha["Captcha handler<br/>[captcha_handler.py]"]
end

subgraph group_control["Scheduling and control"]
  node_worker["Cron and webhook<br/>[worker.js]"]
  node_bot["Telegram control bot<br/>[bot.py]"]
end

subgraph group_state["State and messaging"]
  node_config["Configuration and run state<br/>[config_manager.py]"]
  node_notify["Run notifications<br/>[telegram_notify.py]"]
end

node_operator(("Telegram user"))
node_cron(("Hourly cron"))
node_github_actions{{"GitHub Actions"}}
node_sim24{{"sim24 service"}}
node_gemini{{"Gemini API"}}
node_gist[("GitHub Gist")]
node_telegram{{"Telegram API"}}

node_cron -->|"triggers hourly"| node_worker
node_worker -->|"dispatches run"| node_github_actions
node_github_actions -->|"runs"| node_entry
node_entry -->|"loads and records"| node_config
node_entry -->|"calls login"| node_login
node_login -->|"authenticates"| node_sim24
node_entry -->|"reads usage"| node_usage
node_usage -->|"scrapes usage"| node_sim24
node_entry -->|"checks threshold"| node_decision
node_entry -->|"books if needed"| node_booking
node_booking -->|"activates packet"| node_sim24
node_login -->|"handles captcha"| node_captcha
node_booking -->|"solves captcha"| node_captcha
node_captcha -->|"requests solution"| node_gemini
node_captcha -->|"polls reply"| node_config
node_captcha -->|"requests human fallback"| node_notify
node_entry -->|"sends summary and alerts"| node_notify
node_notify -->|"sends messages"| node_telegram
node_config -->|"reads and writes state"| node_gist
node_operator -->|"sends commands"| node_bot
node_bot -->|"reads status and saves reply"| node_gist
node_bot -->|"dispatches run"| node_github_actions
node_operator -->|"sends webhook commands"| node_worker
node_worker -->|"reads and updates state"| node_gist
node_worker -->|"sends status and prompts"| node_telegram

click node_entry "https://github.com/amirwebd3v/automation-booking-system/blob/main/main.py"
click node_config "https://github.com/amirwebd3v/automation-booking-system/blob/main/config_manager.py"
click node_login "https://github.com/amirwebd3v/automation-booking-system/blob/main/login.py"
click node_usage "https://github.com/amirwebd3v/automation-booking-system/blob/main/data_checker.py"
click node_decision "https://github.com/amirwebd3v/automation-booking-system/blob/main/decision_engine.py"
click node_booking "https://github.com/amirwebd3v/automation-booking-system/blob/main/booking.py"
click node_captcha "https://github.com/amirwebd3v/automation-booking-system/blob/main/captcha_handler.py"
click node_notify "https://github.com/amirwebd3v/automation-booking-system/blob/main/telegram_notify.py"
click node_worker "https://github.com/amirwebd3v/automation-booking-system/blob/main/cloudflare_trigger/worker.js"
click node_bot "https://github.com/amirwebd3v/automation-booking-system/blob/main/scheduler_bot/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_entry,node_login,node_usage,node_decision,node_booking,node_operator toneBlue
class node_captcha,node_gist toneAmber
class node_worker,node_bot,node_gemini,node_telegram toneMint
class node_config,node_notify toneRose
class node_cron,node_github_actions,node_sim24 toneIndigo
```

## Components

### Booking workflow

- [Run orchestrator](https://github.com/amirwebd3v/automation-booking-system/blob/main/main.py): `main.py`
- [Browser login](https://github.com/amirwebd3v/automation-booking-system/blob/main/login.py): `login.py`
- [Usage extraction](https://github.com/amirwebd3v/automation-booking-system/blob/main/data_checker.py): `data_checker.py`
- [Threshold decision](https://github.com/amirwebd3v/automation-booking-system/blob/main/decision_engine.py): `decision_engine.py`
- [2 GB booking](https://github.com/amirwebd3v/automation-booking-system/blob/main/booking.py): `booking.py`

### Captcha resolution

- [Captcha handler](https://github.com/amirwebd3v/automation-booking-system/blob/main/captcha_handler.py): `captcha_handler.py`

### Scheduling and control

- [Cron and webhook](https://github.com/amirwebd3v/automation-booking-system/blob/main/cloudflare_trigger/worker.js): `cloudflare_trigger/worker.js`
- [Telegram control bot](https://github.com/amirwebd3v/automation-booking-system/blob/main/scheduler_bot/bot.py): `scheduler_bot/bot.py`

### State and messaging

- [Configuration and run state](https://github.com/amirwebd3v/automation-booking-system/blob/main/config_manager.py): `config_manager.py`
- [Run notifications](https://github.com/amirwebd3v/automation-booking-system/blob/main/telegram_notify.py): `telegram_notify.py`

### Other components

- **Telegram user**
- **Hourly cron**
- **GitHub Actions**
- **sim24 service**
- **Gemini API**
- **GitHub Gist**
- **Telegram API**

## Connections

- Hourly cron → Cron and webhook: triggers hourly (evidence: `README.md`)
- Cron and webhook → GitHub Actions: dispatches run (evidence: `README.md`)
- GitHub Actions → Run orchestrator: runs (evidence: `README.md`)
- Run orchestrator → Configuration and run state: loads and records (evidence: `main.py`)
- Run orchestrator → Browser login: calls login (evidence: `main.py`)
- Browser login → sim24 service: authenticates (evidence: `README.md`)
- Run orchestrator → Usage extraction: reads usage (evidence: `main.py`)
- Usage extraction → sim24 service: scrapes usage (evidence: `data_checker.py`)
- Run orchestrator → Threshold decision: checks threshold (evidence: `main.py`)
- Run orchestrator → 2 GB booking: books if needed (evidence: `main.py`)
- 2 GB booking → sim24 service: activates packet (evidence: `README.md`)
- Browser login → Captcha handler: handles captcha (evidence: `login.py`)
- 2 GB booking → Captcha handler: solves captcha (evidence: `booking.py`)
- Captcha handler → Gemini API: requests solution (evidence: `README.md`)
- Captcha handler → Configuration and run state: polls reply (evidence: `README.md`)
- Captcha handler → Run notifications: requests human fallback (evidence: `README.md`)
- Run orchestrator → Run notifications: sends summary and alerts (evidence: `main.py`)
- Run notifications → Telegram API: sends messages (evidence: `telegram_notify.py`)
- Configuration and run state → GitHub Gist: reads and writes state (evidence: `config_manager.py`)
- Telegram user → Telegram control bot: sends commands (evidence: `README.md`)
- Telegram control bot → GitHub Gist: reads status and saves reply (evidence: `README.md`)
- Telegram control bot → GitHub Actions: dispatches run (evidence: `README.md`)
- Telegram user → Cron and webhook: sends webhook commands (evidence: `cloudflare_trigger/worker.js`)
- Cron and webhook → GitHub Gist: reads and updates state (evidence: `cloudflare_trigger/worker.js`)
- Cron and webhook → Telegram API: sends status and prompts (evidence: `cloudflare_trigger/worker.js`)
