# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this repository is

This is a Persian-language **Telegram bot that sells V2Ray/Xray VPN accounts** ("WizWiz"). It is not a single application — it is three loosely-coupled pieces that share one MySQL database (`wizwiz`):

1. **`wizwizxui-timebot/`** — the Telegram bot itself (PHP). This is the core product and where almost all logic lives.
2. **`kCcznQ8FmN0Y2qh3sHgEAClMB/`** — a separate web admin panel (PHP + Tailwind UI) that reads/writes the same database. The obscure directory name is intentional (security-by-obscurity for the admin URL).
3. **`3x-ui-main/`** — a **vendored, unmodified copy of the upstream [3x-ui](https://github.com/MHSanaei/3x-ui) Go panel**. The bot talks to deployed 3x-ui instances over HTTP; this checkout is reference/source only. Do not assume changes here affect the running system, and avoid editing it unless explicitly asked.

The bot does not manage Xray directly — it provisions accounts by calling the HTTP APIs of remote **x-ui / 3x-ui ("sanaei") panels**, whose credentials are stored per-server in the `server_config` table.

## Architecture of the bot (`wizwizxui-timebot/`)

This is a **webhook-driven, single-pass router**, not an MVC app. Understanding the request lifecycle is essential:

- **`baseInfo.php`** — secrets and config: `$botToken`, DB credentials, `$admin` (super-admin Telegram user id), `$botUrl`. Included everywhere. Note `error_reporting(0)`.
- **`config.php`** (~6k lines) — the shared library. Included first by every entry point. It:
  - Opens the global `$connection` (mysqli) and defines all Telegram helpers (`sendMessage`, `editText`, `alert`, `sendPhoto`, …).
  - At the bottom (around line 158) **parses the incoming Telegram update from `php://input`** into globals: `$update`, `$from_id`, `$text`, `$data` (callback data), `$message_id`. These globals are used throughout the codebase — treat them as ambient request state.
  - Defines the **keyboard builders** (`getMainKeys`, `getAdminKeys`, `getServerListKeys`, `getPlanDetailsKeys`, …) and the **panel-integration layer**: `getJson` (logs into a remote panel, returns inbounds), `addUser`/`addInboundAccount` (create accounts), `editClientTraffic`, `deleteClient`, `renewClientUuid`, `getConnectionLink` (build vmess/vless/trojan links), etc. These branch on the panel `type` (`"sanaei"` = 3x-ui REST API under `/panel/api/...` vs. older x-ui under `/xui/...`).
- **`bot.php`** (~9k lines) — the webhook target and the actual router. It is one long top-to-bottom sequence of `if`/`preg_match` checks against `$text` / `$data` that dispatches every button press and message. **State is tracked per-user via the `step` field** (see `setUser()`/`checkStep()` in config.php): the bot writes the user's current step to the DB, and the next update is interpreted in the context of that step. There is no central dispatch table — to find how a feature works, grep `bot.php` for the relevant `callback_data` string or `$buttonValues` key.
- **`settings/values.php`** — **all user-facing strings** (`$mainValues`, `$buttonValues`), in Persian, with `UPPERCASE-PLACEHOLDER` tokens replaced at send time via `str_replace`. Add/modify copy here, not inline in bot.php.
- **`settings/`** also holds standalone cron/maintenance scripts run independently of the webhook: `warnusers.php` (expiry warnings), `rewardReport.php`, `gift2all.php`, `tronChecker.php` (TRON/crypto payment polling), `subLink.php`.
- **`search.php`** — public-facing page to look up an account/config by its link or UUID.
- **`pay/`** — payment gateway callbacks. `index.php` initiates, `back.php` handles return/IPN for Zarinpal, NextPay, and NOWPayments (crypto). Payments are tracked in the `pays` table by `hash_id`.
- **`phpqrcode/`** — bundled QR library; **`settings/jdf.php`** — Jalali (Persian) date functions, used as `jdate()` everywhere.

## Database

A single MySQL DB (`wizwiz`, utf8mb4) is the integration point between all three components. There is no migration tooling or schema file in the repo — the schema is implied by the queries. Key tables seen in code: `users` (with `step`, `wallet`, `refered_by`, `isAdmin`), `server_config` (remote panel URL/credentials/cookie/`type`), `server_plans`, `increase_plan`, `pays`, `setting` (key/value blobs like `PAYMENT_KEYS`, addressed by `type`), `admins`. Queries use mysqli prepared statements — follow that pattern.

## How the pieces connect

```
Telegram → webhook → bot.php ──(include)──> config.php ──HTTP──> remote x-ui/3x-ui panels
                                   │
                          MySQL `wizwiz` DB
                                   │
        kCcznQ8.../ admin panel (includ/db.php reuses ../wizwizxui-timebot/baseInfo.php)
```

The admin panel reuses the bot's `baseInfo.php` for DB credentials (`kCcznQ8.../includ/db.php`), so the two are deployment-coupled and assume a fixed relative directory layout.

## Working in this codebase

- **No build, no test suite, no package manager, no linter.** This is plain PHP deployed by file upload. Changes are validated by running against Telegram, not by a local test runner. The `.idea/deployment.xml` maps `$PROJECT_DIR$` → `/var/www/html` on the `WizWiz` server (auto-upload), and `pay`/panel paths assume that web root.
- **Syntax-check before considering a change done:** `php -l wizwizxui-timebot/bot.php` (and the file you edited). A parse error takes the whole webhook down silently because of `error_reporting(0)`.
- **The bot.php and config.php files are very large.** Do not read them end-to-end. Locate work by grepping for the `callback_data`/button string, the `$mainValues`/`$buttonValues` key, or the function name.
- **Comments, strings, and UI are Persian (RTL).** Preserve existing language and the placeholder-token convention (`PRICE`, `USER-ID`, `DAY-PRICE`, …) when editing copy in `settings/values.php`.
- **Two panel API dialects exist.** When touching account-provisioning code, handle both the `"sanaei"` (3x-ui, `/panel/api/inbounds/...`) and legacy x-ui (`/xui/...`) branches — see `getJson` as the template.
- `dbbackupwizwiz.sh` dumps the DB and sends it to the admin via Telegram (cron). `ssl.sh*` are server SSL/cert provisioning helpers, not part of the app.

## Security note

`baseInfo.php` contains a live bot token, DB password, and admin id committed in plaintext. Treat these as real secrets — do not echo, log, or transmit them, and flag if asked to expose them.