# WizWiz X-UI TimeBot Workspace Context

This document serves as a lightweight knowledge base and reference point for AI assistants working on the project, saving tokens and providing instant context on architecture, tech stack, and goals.

---

## Project Overview

**WizWiz X-UI TimeBot** is a powerful and feature-rich Telegram bot designed to manage and sell VPN configurations. It acts as an automated billing, management, and support platform that integrates directly with popular VPN panels (e.g., Marzban, X-UI, 3x-ui) and multiple payment gateways. 

Key features include:
*   **Protocol Support:** VLESS, VMess, Trojan, ShadowSocks, XTLS, Reality, gRPC, WebSocket (ws), TCP.
*   **Panel Integrations:** Marzban, Niduka Akalanka, Sanaei (3x-ui), Alireza, Vaxilu.
*   **Payment Gateways:** Zarinpal, NextPay, NowPayments (cryptocurrency), Tron (direct wallet verification).
*   **User Management:** Account extension, custom subscription plans, wallet charging, balance transfers, sub-commission/referrals, and discount codes.
*   **Admin Panel:** Server and category management, sales statistics, live service monitoring, backup generation, and user broadcasting.

---

## Tech Stack

*   **Language:** PHP (Core server-side logic and Telegram Bot API handling)
*   **Database:** MySQL / MariaDB (Configuration metadata, user stats, transactions, tickets)
*   **APIs & Protocols:**
    *   Telegram Bot API
    *   REST APIs for VPN Panels (Marzban, X-UI, etc.)
    *   Payment Gateway Integration APIs (NextPay, Zarinpal, NowPayments)
*   **Frontend/Web:** HTML/CSS (For subscription link info pages, QR code displays, and payment redirectors)

---

## Directory Structure

```
wizwizxui-timebot/
├── assets/                     # Graphic assets and images
├── handlers/                   # Core request handlers for users and admins
│   ├── admin_servers.php       # Admin server management
│   ├── admin_settings.php      # Bot configuration and admin panel settings
│   ├── admin_tickets.php       # Ticket management for administrators
│   ├── user_account.php        # User profile and account status
│   ├── user_buy.php            # Purchase flow and service plans selection
│   ├── user_config.php         # User configuration management
│   └── user_tickets.php        # Support ticketing system for users
├── install/                    # Installation and updating utilities
│   ├── install.php
│   └── update.php
├── pay/                        # Payment actions and portal integrations
│   ├── index.php               # Payment entry point
│   ├── do_action.php           # Action router after callback
│   ├── action_buy_sub.php      # Purchase action processor
│   └── ...                     # Wallet, time extension, and renew actions
├── phpqrcode/                  # Local QR code generation library
├── settings/                   # System configurations and external API integrations
│   ├── config_keyboards.php    # Telegram keyboard layout definitions
│   ├── config_marzban_api.php  # Marzban panel API client
│   ├── config_xui_api.php      # X-UI panel API client
│   ├── config_telegram.php     # Telegram connection settings
│   └── config_utils.php        # Utility functions and helper methods
├── storage/                    # Log files and application backups
├── bot.php                     # Bot webhook endpoint (receives update payloads)
├── config.php                  # Global config variables and DB connection setup
├── payments.php                # Master payment processing script
├── search.php                  # Config search functions
├── README.md                   # English Documentation
└── README-fa.md                # Persian Documentation
```

---

## Current Status & Goals

*   **Current Infrastructure:** Fully integrated setup for managing X-UI/Marzban VPN users.
*   **Google Cloud SDK Configured:** The developer workstation environment has been configured with the Google Cloud SDK (`gcloud` CLI) to manage deployment, APIs, or VM resources on GCP.
*   **Immediate Goals:** Keep the system codebase clean, maintain correct panel integrations, optimize API calls, and support any new custom plans or payment gateway implementations desired by the team.
