📖 Quraan Bot V2

An advanced, high-performance, and open-source Telegram bot dedicated to the Holy Quran. Built with an enterprise-level architecture, it offers seamless reading, advanced verse searching, multi-reciter audio playback, and robust Khatma (completion) tracking.

✨ Features

• Hybrid Database Architecture:
  • Utilizes PostgreSQL (Asyncpg) for dynamic data (Users, Chats, Khatma sessions) ensuring ACID compliance and thread-safe operations.
  • Employs a standalone SQLite database for static, read-only Quran data to guarantee lightning-fast queries without network overhead.
• Advanced Search Engine: Features a normalized text search algorithm that ignores diacritics (Tashkeel) and standardizes Arabic letters, returning highly accurate results in milliseconds.
• Smart Audio Caching: Implements a multi-layered caching mechanism using Telegram file_ids, RAM (io.BytesIO), and temporary disk files. This reduces server bandwidth consumption to 0% for repeated audio requests.
• Interactive Admin Dashboard: A fully inline, real-time control panel for the bot owner to view live statistics, manage users (ban/unban), and broadcast messages seamlessly using Pyrogram's listen feature.
• Dynamic Image Generation: Generates pixel-perfect, beautifully aligned images of Quranic verses using the Uthmanic script via Pillow, handled asynchronously to prevent event-loop blocking.
• Dockerized & Hot-Reload: Fully containerized environment with docker-compose and watchfiles for instantaneous auto-reloading during development.

🛠️ Tech Stack

• Language: Python 3.10+
• Core Framework: Pyrofork (Pyrogram fork)
• Database ORM & Drivers: SQLAlchemy, asyncpg, SQLite3
• Media Processing: Pillow (PIL)
• Networking: httpx
• Infrastructure: Docker, Docker Compose

🚀 Getting Started (Deployment)

The bot is designed to be easily deployed on any Linux or Windows server using Docker.

1. Clone the Repository

git clone https://github.com/AlsaeedHasan/QuraanBotV2.git
cd QuraanBotV2

2. Install Docker

If Docker is not already installed, use the provided automated installation scripts based on your OS:

For Linux (Debian / Ubuntu / CentOS / Arch / openSUSE):

chmod +x docker-install.sh
./docker-install.sh

For Windows (Run PowerShell as Administrator):

.\docker-install.ps1

3. Environment Configuration

Copy the example environment file and fill in your credentials (API ID, Hash, Bot Token, etc.):

cp .env.example .env

Note: Ensure DB_HOST=db is set inside your .env file if you are running the bot via Docker.

4. Run the Bot

Start the PostgreSQL database and the bot in detached mode:

docker compose up -d --build

Development Note: Any changes made to the src/ directory will automatically trigger a hot-reload without needing to rebuild the container or restart the service manually.

📂 Project Structure

QuraanBotV2/
├── assets/                  # Shipped Quran SQLite DB, Fonts, and Temp folder
├── src/
│   ├── database/            # SQLAlchemy Models and Connections
│   ├── helpers/             # Utility functions (Filters, Markups, Image Rendering)
│   ├── plugins/             # Bot plugins (Admin panel, Mushaf, Khatma, Audio)
│   ├── config.py            # Pydantic Settings & Env Validation
│   └── main.py              # Application Entry Point
├── .env.example             # Environment variables template
├── docker-compose.yml       # Docker Compose configuration
├── Dockerfile               # Python app container definition
├── docker-install.sh        # Linux Docker installer
├── docker-install.ps1       # Windows Docker installer
└── requirements.txt         # Python dependencies

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page if you want to contribute.

👨‍💻 Author

Alsaeed Khalil

• LinkedIn: Alsaeed Khalil

📄 License

This project is open-source and available under the PolyForm Noncommercial License.