How rave-ns/shopify_bot works
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 Bot Core · card_checker.py Checker · index.html Mini App · database.py Database
Components 18
Runtime
Main startup and orchestration path for the bot and Mini App backend.
- Start · Process entrypoint that starts the bot/application.
start.py - Bot Core · Main wiring for Telegram handlers, HTTP routes, and runtime flow.
bot.py - Legacy Bot · Older bot implementation kept outside the main runtime path.
bot_old.py - Commands · Telegram-facing control plane for user commands such as /start.
- App Link · Launch path that sends Telegram users into the Mini App experience.
- HTTP API · Backend endpoints used by the Mini App for data and actions.
Mini App UI
Browser-side interface served to Telegram users.
Checker Worker
Long-running card checking and proxy-driven job execution.
- Checker · Core asynchronous card-checking engine with batching and progress tracking.
card_checker.py - Proxy Flow · Proxy rotation and network routing used by the checker.
- Job State · Per-run status, pause/resume, and categorized results during checks.
State
File-backed persistence and user-scoped data.
Config
Environment and runtime configuration boundary.
- Config · Central runtime configuration sourced from environment variables.
config.py - Env Example · Template for required secrets and deployment settings.
.env.example
External
Outside platforms and deployment dependencies.
- Telegram · External messaging platform that initiates user interaction.
- Web Host · HTTP-serving environment implied by webhook and port configuration.
Connections 21
- 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.