From 4fe4456f3e69185f3a4534e3c3f570ac625ed29e Mon Sep 17 00:00:00 2001
From: arsam <me@asabbagh.com>
Date: Fri, 18 Sep 2026 23:14:50 +0330
Subject: [PATCH] Import documentation: CLAUDE.md

Import the existing local project snapshot. This commit organizes existing files; it does not represent newly developed functionality.
---
 CLAUDE.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..9b3bd58
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,71 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Project Does
+
+**Tele2Bale** — transfers files from a Telegram bot to Bale messenger's Saved Messages via a Userbot. Supports files up to 2GB by bypassing Bale's 50MB bot limit through Userbot authentication. Features a file-based queue system, real-time progress updates, Safe Mode (AES-encrypted ZIP before upload), and direct URL downloading.
+
+## Running the Project
+
+**Install dependencies:**
+```bash
+pip install -r requirements.txt
+```
+
+**First-time Bale login** (interactive — required once to create `session.bale`):
+```bash
+python3 bale.py
+```
+
+**Run the application:**
+```bash
+python3 main.py
+```
+
+## Architecture
+
+`main.py` spawns `telebot.py` and `bale.py` as separate subprocesses and waits for both. The two components communicate exclusively via files in `queue/`.
+
+### telebot.py (Telegram Bot — Pyrogram)
+- Receives files/URLs from users via Telegram bot
+- Downloads Telegram media immediately to `downloads/` using `pyrogram`
+- Writes tasks to `queue/tasks.jsonl` (JSONL, append-only)
+- Watches `queue/status.jsonl` via `status_watcher()` coroutine and edits Telegram messages to reflect upload progress
+- Handles `/del`, `/delall`, `/safemode` commands; cancellations written to `queue/cancelled.jsonl`
+
+### bale.py (Bale Userbot Worker — aiobale)
+- Pops tasks from `queue/tasks.jsonl` one at a time (`pop_first_task()` reads and rewrites the file)
+- For `direct_url` tasks: downloads via `requests` streaming to `downloads/url/`
+- For `local_file` tasks: uses the already-downloaded path
+- If Safe Mode: wraps file in AES-encrypted ZIP via `pyzipper`, then deletes the original
+- Uploads to Bale via `aiobale.Client.send_document()` with retry logic (up to 5 attempts, 30-minute timeout)
+- Writes progress/status updates to `queue/status.jsonl` which `telebot.py` picks up
+
+### Queue File Protocol
+| File | Purpose |
+|------|---------|
+| `queue/tasks.jsonl` | Pending tasks; `telebot.py` appends, `bale.py` pops from front |
+| `queue/status.jsonl` | Append-only status updates from `bale.py`; consumed by `telebot.py` |
+| `queue/processing.json` | Single-task file; current in-flight task |
+| `queue/deleted.jsonl` | Deleted task records for dedup |
+| `queue/cancelled.jsonl` | Cancellation signals keyed by `job_id` |
+| `queue/failed.jsonl` | Failed tasks with error messages |
+
+## Configuration (.env)
+
+```env
+API_ID=          # Telegram API ID (from my.telegram.org)
+API_HASH=        # Telegram API Hash
+BOT_TOKEN=       # Telegram bot token
+BALE_TARGET_ID=  # Bale UID to send files to (Saved Messages ID)
+```
+
+The `BALE_PHONE` in `.env` is used during the interactive first-run session setup for `aiobale`.
+
+## Key Constraints
+
+- **Userbot required**: Bale bot API limits files to 50MB; the Userbot (`session.bale`) bypasses this.
+- **Sequential processing**: `bale.py` processes one task at a time to avoid Bale rate limiting/crashes.
+- `UPLOAD_TIMEOUT` is 1800s (30 min) — tune based on server speed and file sizes.
+- All user-facing messages in the bot are in Persian (Farsi).