# rave-ns/shopify_bot architecture

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

- Interactive diagram: https://gitdiagram.com/rave-ns/shopify_bot
- Repository: https://github.com/rave-ns/shopify_bot

## Overview

1. **What this repository is**
   - This is a Telegram bot plus a Telegram Mini App for managing a “Shopify card checker” workflow.
   - The architecture is split between a Telegram-facing backend, a browser-based Mini App UI, and a local/file-backed persistence layer.

2. **Primary runtime entrypoints**
   - `start.py` is the launcher used to start the bot/application.
   - `bot.py` is the main orchestration module: it likely wires together Telegram bot handlers, the HTTP server for the Mini App, and API routes.
   - `bot_old.py` appears to be a legacy/previous version and is not part of the main runtime path.

3. **Telegram interaction layer**
   - Users interact first through Telegram commands such as `/start`.
   - The bot sends users into the Mini App experience, so Telegram is the control plane while the web UI is the operational interface.
   - The presence of `robin_bot.session` suggests the bot uses a Telegram client/session-based library in addition to standard bot token flow.

4. **Mini App frontend**
   - The `static/` directory contains the entire client-side UI:
     - `index.html` for structure
     - `style.css` for theming and responsive layout
     - `script.js` for interaction and API calls
   - This UI is presented as a single-page Mini App with tabs, live status, and user-driven actions.

5. **Backend API boundary**
   - The backend exposes HTTP endpoints used by the Mini App, including:
     - card checking
     - proxy management
     - Shopify URL management
     - user data retrieval
   - The API acts as the bridge between the web UI and the bot’s internal services, so the frontend never directly owns state or checking logic.

6. **Card-checking subsystem**
   - `card_checker.py` contains the core checking engine.
   - Based on the README, this subsystem supports batching, progress tracking, pause/resume, result categorization, and proxy rotation.
   - This is the main asynchronous workload in the system and is separate from UI and persistence concerns.

7. **Persistence and per-user state**
   - `database.py` plus `database.json` indicate file-based storage rather than a database server.
   - The repo emphasizes isolated user data, saved settings, proxy lists, and Shopify URL lists per user.
   - `database.json` likely stores the persistent state that survives restarts.

8. **Configuration boundary**
   - `config.py` centralizes runtime configuration such as API credentials, bot token, webhook URL, and port.
   - `.env.example` shows the system expects environment-based secrets/configuration, which are loaded at startup rather than hardcoded.

9. **Main data flow**
   - Telegram user sends `/start` → bot responds with a Mini App link.
   - User interacts in the Mini App → frontend sends requests to backend API.
   - Backend loads user-specific settings from persistence → invokes the card checker.
   - Checker updates status/progress/results → backend returns live state to the UI.
   - Settings changes from the UI are persisted back into `database.json`.

10. **Operational features that affect architecture**
   - Proxy rotation and multi-store URL management are first-class backend concerns, not UI-only features.
   - Progress reporting and real-time updates imply the backend keeps per-job state during long-running checks.
   - “Fake address generation” and error handling are part of the worker/service layer, likely inside or adjacent to the checker.

11. **External dependencies and infrastructure**
   - Telegram is the primary external platform.
   - The Mini App requires HTTP serving, and `WEBHOOK_URL`/`PORT` in the README suggest the bot can be deployed behind a reachable web endpoint.
   - `requirements.txt` defines the Python runtime dependencies that support both Telegram integration and the web/API stack.

12. **Relevant architectural boundaries for a diagram**
   - **Telegram layer**: commands, bot responses, launch point.
   - **Web Mini App layer**: browser UI hosted from `static/`.
   - **API/orchestration layer**: `bot.py` routes and request handling.
   - **Worker layer**: `card_checker.py` long-running checking jobs.
   - **Persistence layer**: `database.py` and `database.json`.
   - **Configuration layer**: `config.py` and environment variables.

13. **Repository layout summary**
   - The repo is small and monolithic, but the separation of concerns is clear:
     - orchestration in `bot.py`
     - work execution in `card_checker.py`
     - state in `database.py`
     - configuration in `config.py`
     - UI in `static/`
   - That makes the architecture easy to diagram as a backend service that serves and controls a Mini App, with file-backed per-user state.

Main entry points: [`bot.py`](https://github.com/rave-ns/shopify_bot/blob/main/bot.py) (Bot Core), [`card_checker.py`](https://github.com/rave-ns/shopify_bot/blob/main/card_checker.py) (Checker), [`static/index.html`](https://github.com/rave-ns/shopify_bot/blob/main/static/index.html) (Mini App), [`database.py`](https://github.com/rave-ns/shopify_bot/blob/main/database.py) (Database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_runtime["Runtime"]
  node_start_py(("Start<br/>launcher<br/>[start.py]"))
  node_bot_py["Bot Core<br/>orchestrator<br/>[bot.py]"]
  node_bot_old_py["Legacy Bot<br/>[bot_old.py]"]
  node_telegram_cmds(("Commands<br/>telegram entry"))
  node_miniapp_bridge(("App Link<br/>handoff"))
  node_http_api["HTTP API<br/>backend api"]
end

subgraph group_group_ui["Mini App UI"]
  node_miniapp_shell["Mini App<br/>frontend shell<br/>[index.html]"]
  node_ui_logic["UI Logic<br/>client js<br/>[script.js]"]
  node_ui_theme["Styling<br/>client css<br/>[style.css]"]
end

subgraph group_group_worker["Checker Worker"]
  node_checker_core["Checker<br/>job engine<br/>[card_checker.py]"]
  node_proxy_flow(("Proxy Flow<br/>rotation"))
  node_job_state(("Job State<br/>progress model"))
end

subgraph group_group_state["State"]
  node_database_py["Database<br/>file store<br/>[database.py]"]
  node_database_json[("Data File<br/>json store<br/>[database.json]")]
end

subgraph group_group_config["Config"]
  node_config_py["Config<br/>settings<br/>[config.py]"]
  node_env_example["Env Example<br/>env template<br/>[.env.example]"]
end

subgraph group_group_external["External"]
  node_telegram_platform(("Telegram<br/>external platform"))
  node_web_runtime(("Web Host<br/>deployment runtime"))
end

node_start_py -->|"starts"| node_bot_py
node_bot_py -->|"handles"| node_telegram_cmds
node_telegram_cmds -.->|"via"| node_telegram_platform
node_telegram_cmds -->|"opens"| node_miniapp_bridge
node_miniapp_bridge -->|"launches"| node_miniapp_shell
node_bot_py -->|"serves"| node_http_api
node_miniapp_shell -->|"uses"| node_ui_logic
node_miniapp_shell -->|"styled by"| node_ui_theme
node_ui_logic -->|"calls"| node_http_api
node_http_api -->|"reads/writes"| node_database_py
node_database_py -->|"stores"| node_database_json
node_http_api -->|"invokes"| node_checker_core
node_checker_core -->|"uses"| node_proxy_flow
node_checker_core -->|"updates"| node_job_state
node_http_api -->|"exposes"| node_job_state
node_bot_py -->|"loads"| node_config_py
node_config_py -.->|"documented by"| node_env_example
node_bot_py -.->|"runs on"| node_web_runtime
node_bot_py -->|"coordinates"| node_database_py
node_bot_py -->|"coordinates"| node_checker_core
node_bot_py -.->|"supersedes"| node_bot_old_py

click node_start_py "https://github.com/rave-ns/shopify_bot/blob/main/start.py"
click node_bot_py "https://github.com/rave-ns/shopify_bot/blob/main/bot.py"
click node_bot_old_py "https://github.com/rave-ns/shopify_bot/blob/main/bot_old.py"
click node_miniapp_shell "https://github.com/rave-ns/shopify_bot/blob/main/static/index.html"
click node_ui_logic "https://github.com/rave-ns/shopify_bot/blob/main/static/script.js"
click node_ui_theme "https://github.com/rave-ns/shopify_bot/blob/main/static/style.css"
click node_checker_core "https://github.com/rave-ns/shopify_bot/blob/main/card_checker.py"
click node_database_py "https://github.com/rave-ns/shopify_bot/blob/main/database.py"
click node_database_json "https://github.com/rave-ns/shopify_bot/blob/main/database.json"
click node_config_py "https://github.com/rave-ns/shopify_bot/blob/main/config.py"
click node_env_example "https://github.com/rave-ns/shopify_bot/blob/main/.env.example"

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_start_py,node_bot_py,node_bot_old_py,node_telegram_cmds,node_miniapp_bridge,node_http_api toneBlue
class node_miniapp_shell,node_ui_logic,node_ui_theme toneAmber
class node_checker_core,node_proxy_flow,node_job_state toneMint
class node_database_py,node_database_json toneRose
class node_config_py,node_env_example toneIndigo
class node_telegram_platform,node_web_runtime toneTeal
```

## Components

### Runtime

Main startup and orchestration path for the bot and Mini App backend.

- [Start](https://github.com/rave-ns/shopify_bot/blob/main/start.py): launcher · Process entrypoint that starts the bot/application. · `start.py`
- [Bot Core](https://github.com/rave-ns/shopify_bot/blob/main/bot.py): orchestrator · Main wiring for Telegram handlers, HTTP routes, and runtime flow. · `bot.py`
- [Legacy Bot](https://github.com/rave-ns/shopify_bot/blob/main/bot_old.py): legacy · Older bot implementation kept outside the main runtime path. · `bot_old.py`
- **Commands**: telegram entry · Telegram-facing control plane for user commands such as /start.
- **App Link**: handoff · Launch path that sends Telegram users into the Mini App experience.
- **HTTP API**: backend api · Backend endpoints used by the Mini App for data and actions.

### Mini App UI

Browser-side interface served to Telegram users.

- [Mini App](https://github.com/rave-ns/shopify_bot/blob/main/static/index.html): frontend shell · Single-page browser UI served to Telegram users. · `static/index.html`
- [UI Logic](https://github.com/rave-ns/shopify_bot/blob/main/static/script.js): client js · Client-side interaction and API request handling. · `static/script.js`
- [Styling](https://github.com/rave-ns/shopify_bot/blob/main/static/style.css): client css · Responsive layout and visual theming for the Mini App. · `static/style.css`

### Checker Worker

Long-running card checking and proxy-driven job execution.

- [Checker](https://github.com/rave-ns/shopify_bot/blob/main/card_checker.py): job engine · Core asynchronous card-checking engine with batching and progress tracking. · `card_checker.py`
- **Proxy Flow**: rotation · Proxy rotation and network routing used by the checker.
- **Job State**: progress model · Per-run status, pause/resume, and categorized results during checks.

### State

File-backed persistence and user-scoped data.

- [Database](https://github.com/rave-ns/shopify_bot/blob/main/database.py): file store · File-backed persistence layer for user settings and workflow data. · `database.py`
- [Data File](https://github.com/rave-ns/shopify_bot/blob/main/database.json): json store · Persistent repository of user-scoped settings and saved lists. · `database.json`

### Config

Environment and runtime configuration boundary.

- [Config](https://github.com/rave-ns/shopify_bot/blob/main/config.py): settings · Central runtime configuration sourced from environment variables. · `config.py`
- [Env Example](https://github.com/rave-ns/shopify_bot/blob/main/.env.example): env template · Template for required secrets and deployment settings. · `.env.example`

### External

Outside platforms and deployment dependencies.

- **Telegram**: external platform · External messaging platform that initiates user interaction.
- **Web Host**: deployment runtime · HTTP-serving environment implied by webhook and port configuration.

## Connections

- Start → Bot Core: starts · Launcher hands control to the main orchestration module.
- Bot Core → Commands: handles · Bot receives and processes Telegram commands.
- Commands → Telegram: via · Commands arrive through Telegram.
- Commands → App Link: opens · Telegram command flow exposes the Mini App entrypoint.
- App Link → Mini App: launches · Users are sent from Telegram into the browser UI.
- Bot Core → HTTP API: serves · Backend exposes API endpoints for the Mini App.
- Mini App → UI Logic: uses · HTML shell is driven by client-side script.
- Mini App → Styling: styled by · UI presentation is provided by the stylesheet.
- UI Logic → HTTP API: calls · Frontend sends requests to backend endpoints.
- HTTP API → Database: reads/writes · API layer persists and loads per-user state.
- Database → Data File: stores · Persistence is file-backed in JSON.
- HTTP API → Checker: invokes · Backend starts and coordinates card-check jobs.
- Checker → Proxy Flow: uses · Checker rotates proxies for network requests.
- Checker → Job State: updates · Worker reports progress, pause/resume, and results.
- HTTP API → Job State: exposes · Live job state is returned to the Mini App.
- Bot Core → Config: loads · Orchestration reads runtime configuration.
- Config → Env Example: documented by · Environment template shows required settings.
- Bot Core → Web Host: runs on · Backend expects an HTTP-accessible runtime.
- Bot Core → Database: coordinates · Bot layer also consults persistence for user-scoped data.
- Bot Core → Checker: coordinates · Main runtime connects user actions to the worker.
- Bot Core → Legacy Bot: supersedes · Legacy implementation is separate from the main path.