# ArcRam Bot & Mini App - Private Structure & Technical Map This file contains the internal codebase structure, data flows, and configurations for the ArcRam project. **This file should be kept private and not committed to public repositories.** --- ## πŸ—ΊοΈ Project Directory & Codebase Map ### πŸ“ Directory Layout ``` project/ β”œβ”€β”€ .github/workflows/ β”‚ └── deploy.yml # GitHub Actions deployment workflow (SSH & chmod setup) β”œβ”€β”€ assets/ # Public assets (images, styles, etc.) β”œβ”€β”€ classes/ # Core PHP Class Controllers (Business Logic) β”‚ β”œβ”€β”€ data/ # JSON data & temporary assets β”‚ β”œβ”€β”€ form_states/ # User form step session files β”‚ β”œβ”€β”€ pending_messages/ # Temporary message storage for admin approval β”‚ β”œβ”€β”€ AIChatHandler.php # Multi-model AI Integration (GPT, DeepSeek, Qwen) β”‚ β”œβ”€β”€ BotHandler.php # Monolithic Bot Handler (Bot flows, keyboards, commands) β”‚ β”œβ”€β”€ BroadcastHandler.php # Handles admin broadcast messages β”‚ β”œβ”€β”€ Database.php # MySQLi Database Wrapper & Query Handler β”‚ β”œβ”€β”€ FileHandler.php # File uploads, downloads, and validation logic β”‚ β”œβ”€β”€ FormManager.php # Dynamic Multi-step Form Processor Engine β”‚ β”œβ”€β”€ Forms.php # Form Fields Config Definition (e.g. ad_creation) β”‚ β”œβ”€β”€ InlineQueryHandler.php# Telegram Inline Queries (Search projects/profiles) β”‚ β”œβ”€β”€ IppanelSmsHandler.php # SMS verification gateway integrations β”‚ β”œβ”€β”€ Logger.php # Logging to file & sending debug logs to Telegram channel β”‚ β”œβ”€β”€ PendingMessageManager.php # Handles messages awaiting admin approval β”‚ β”œβ”€β”€ WebAppHelper.php # Mini App security verification & request helper β”‚ └── cache.php # File/Memory caching logic β”œβ”€β”€ config/ β”‚ β”œβ”€β”€ AppConfig.php # Loads .env variables and holds configuration arrays β”‚ └── jdf.php # Jalali (Shamsi) Calendar utility functions β”œβ”€β”€ cron/ β”‚ └── expire_projects.php # Cron job to mark expired projects/ads β”œβ”€β”€ log/ # Daily system and error log outputs (Requires 777 perms) β”œβ”€β”€ data/ β”‚ └── state/ # Form flow lock/JSON files (Requires 777 perms) β”œβ”€β”€ miniapp/ # Telegram Mini App (Web App) Frontend & API β”‚ β”œβ”€β”€ api.php # Backend API endpoint for the Web App β”‚ β”œβ”€β”€ index.html # Main HTML UI for the Web App β”‚ β”œβ”€β”€ styles.css # Stylesheets for the Web App β”‚ β”œβ”€β”€ error_log # Mini app specific error logs β”‚ └── js/, fonts/, images/ # Frontend static resources β”œβ”€β”€ payment/ β”‚ └── ZarinpalPaymentHandler.php # Zarinpal gateway API (Invoice creation & verification) β”œβ”€β”€ public/ # Public Web Endpoints β”‚ β”œβ”€β”€ bot.php # Telegram webhook endpoint (Reads php://input) β”‚ β”œβ”€β”€ diagnose.php # System and Telegram Webhook diagnostic script β”‚ β”œβ”€β”€ broadcast_panel.php # Admin web panel for sending broad messages β”‚ β”œβ”€β”€ receipt.php # User payment receipt web page β”‚ β”œβ”€β”€ project_cron.php # Main scheduled task cron execution entry point β”‚ β”œβ”€β”€ run_scheduler.php # System command scheduler β”‚ └── update_block_statistics.php # Stats updating cron β”œβ”€β”€ .env # Environment Variables (DB credentials, API Keys, Tokens) β”œβ”€β”€ .htaccess # Apache routing and directory security config └── composer.json # PHP packages configuration ``` --- ## πŸ—ƒοΈ Codebase Analysis & Data Flows ### 1. Webhook Routing * **Entry Point**: `public/bot.php` * When a user sends a message or clicks a button, Telegram sends an update JSON payload via POST to `public/bot.php`. * `bot.php` decodes the input and determines the update type: * Regular Messages / Commands (`/start`): routed to `$bot->handleRequest()` in `classes/BotHandler.php`. * Callback Queries (Inline buttons): routed to `$bot->handleCallbackQuery()` in `classes/BotHandler.php`. * Inline Queries (Typing @botusername ...): routed to `$bot->handleInlineQuery()` in `classes/InlineQueryHandler.php`. * Pre-Checkout (Payments): routed to `$bot->handlePreCheckoutQuery()` in `classes/BotHandler.php`. ### 2. Database Integration * **Class**: `classes/Database.php` * Uses PHP's `mysqli` extension to connect to the database configured in `.env`. * Manages core tables: `users` (chat_id, points, balance, is_admin), `channels` (subscription requirements), `packages` (token bundles), `transactions` (Zarinpal history), and project/ad data. ### 3. Multi-Step Forms & States * **Classes**: `classes/FormManager.php`, `classes/Forms.php`, `classes/StateManager.php` * Creating ads or listing items involves a multi-step conversational form. The structure of these forms (fields, validation, prompt messages) is defined in `classes/Forms.php`. * User progress is kept between webhook invocations by saving JSON files in `data/state/` named `{chat_id}.json` using `classes/StateManager.php`. A locking mechanism `{chat_id}.lock` is used to prevent parallel processing race conditions. ### 4. AI Chat Integration * **Class**: `classes/AIChatHandler.php` * Allows users to interact with AI models directly inside the bot. * Supported services configured via `config/AppConfig.php` and `.env`: * **OpenAI (GPT-3.5-turbo / GPT-4)** * **DeepSeek (deepseek-chat)** * **Qwen (qwen-chat)** * Manages token counts, handles system prompts, logs chat logs, and calculates usage based on user package tokens. ### 5. Payments & Invoices * **Classes**: `payment/ZarinpalPaymentHandler.php` * Integrates Zarinpal IPG. * When purchasing tokens or paying for ad listings, the user gets a payment link. * Once paid, Zarinpal redirects them back to `public/bot.php` (with query parameters like `tokenPurchase`, `adPayment`, or `walletCharge`). The bot verifies the transaction with Zarinpal, credits the user/ad in the DB, and notifies the user and administrators. --- ## πŸ› οΈ Environment Configuration (.env) Make sure your `.env` contains the following keys on the production server: ```env APP_NAME=Arc APP_ENV=production APP_DEBUG=false DB_CONNECTION=mysql DB_HOST=127.0.0.1 DB_PORT=3306 DB_DATABASE=your_database_name DB_USERNAME=your_database_user DB_PASSWORD=your_database_password BOT_TOKEN=your_telegram_bot_token MERCHANT_ID=your_zarinpal_merchant_id BOT_LINK=https://t.me/your_bot_username?start= BOT_USERNAME=your_bot_username GPT_API_KEY=your_openai_key GPT_MODEL=gpt-3.5-turbo GPT_TEMPERATURE=0.5 DEEPSEEK_API_KEY=your_deepseek_key ```