# Repository Guidelines

## Project Structure & Module Organization

This is a small Python service for moving files from a Telegram bot to S3 through rclone.

- `main.py` starts both worker processes with the current Python interpreter.
- `telebot.py` receives Telegram messages, downloads media or URLs, and writes queue/status files.
- `rub.py` consumes queued tasks and uploads documents to S3 with `rclone copyto`.
- `requirements.txt` pins runtime dependencies.
- Runtime directories such as `downloads/` and `queue/` are created automatically; do not commit them.
- `.env` stores local secrets and session configuration; keep it private.

There is currently no dedicated `tests/` directory or packaged module layout.

## Build, Test, and Development Commands

Set up dependencies:

```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

Run the full service:

```bash
python3 main.py
```

Run one worker when debugging:

```bash
python3 telebot.py
python3 rub.py
```

No build step is required. Before running, create `.env` with `API_ID`, `API_HASH`, and `BOT_TOKEN`. rclone must have a configured `coaxys` remote.

## Coding Style & Naming Conventions

Use Python 3 style with 4-space indentation. Keep functions small and side effects explicit, especially around writes to `queue/` and `downloads/`. Existing names use `snake_case` for functions and variables, uppercase constants for paths and limits, and `Path` objects for filesystem locations.

Prefer structured JSON handling over manual string manipulation. Preserve UTF-8 reads/writes with `ensure_ascii=False` because status messages include Persian text.

## Testing Guidelines

There is no test framework configured yet. For new logic, add focused `pytest` tests under `tests/`, named like `test_queue_manager.py` or `test_safe_filename.py`. Mock Telegram, rclone, network calls, and filesystem writes where possible.

Until tests exist, manually verify by running `python3 main.py`, sending a small file to the bot, and checking that queue status advances and `rclone ls coaxys:coaxys --s3-no-check-bucket` shows the object.

## Commit & Pull Request Guidelines

Local Git history is not readable in this checkout, so no project-specific commit convention can be inferred. Use concise imperative messages, for example `Add queue cancellation tests`.

Pull requests should include a short summary, configuration notes, manual test steps, and screenshots or logs when behavior changes. Link related issues and call out changes affecting credentials, sessions, or queue files.

## Security & Configuration Tips

Never commit `.env`, rclone config, downloaded user files, queue state, or generated ZIP archives. Treat bot tokens, Telegram API credentials, and S3 keys as secrets. Redact chat IDs, tokens, URLs, and remote names from shared logs.