🤖 PHP Bot Hosting Platform

A Telegram bot platform for hosting PHP-based bots with file management, subscription plans, and quota management.

📋 Overview

This platform allows users to:

• Upload and manage PHP files through Telegram
• Host their own Telegram bots with automatic webhook setup
• Manage files and folders with an intuitive interface
• Choose between Free and Pro subscription plans
• Monitor usage and quotas in real-time

🏗️ Architecture

Built with a clean, layered architecture:

• Presentation Layer: Telegram bot interface (python-telegram-bot)
• Application Layer: Business logic services
• Domain Layer: Core models and entities
• Infrastructure Layer: PostgreSQL, Redis, PHP-FPM

🚀 Tech Stack

• Python 3.11+: Main application runtime
• python-telegram-bot 21.x: Telegram bot framework
• FastAPI: Webhook receiver and API
• PostgreSQL 16+: Primary database
• Redis 7+: Caching and queues
• PHP-FPM 8.3: Execute user bots
• SQLAlchemy 2.0+: Database ORM
• APScheduler: Background tasks

📦 Project Structure

src/
├── core/           # Core infrastructure (config, database, cache, logger)
├── models/         # Domain models (User, Bot, File, Subscription)
├── repositories/   # Data access layer
├── services/       # Business logic
├── handlers/       # Telegram command handlers
├── middleware/     # Authentication, rate limiting, logging
├── tasks/          # Background tasks
├── utils/          # Utilities and helpers
└── web/            # Webhook receiver and PHP gateway

config/             # PHP and PHP-FPM configuration
migrations/         # Database migrations
tests/              # Unit, integration, and e2e tests
scripts/            # Utility scripts

🔧 Setup

1. Clone the repository

   git clone <repository-url>
   cd php-bot

2. Create virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

   pip install -r requirements.txt

4. Configure environment

   cp .env.example .env
   # Edit .env with your configuration

5. Setup database

   python scripts/setup_db.py
   python scripts/migrate.py

6. Run the bot

   python -m src

🎯 Features

Free Plan

• 50 MB storage
• 30 files maximum
• 5 folders maximum
• 1 bot
• 10,000 webhook calls/day

Pro Plan

• 1 GB storage
• 500 files maximum
• 50 folders maximum
• 5 bots
• 100,000 webhook calls/day

🔐 Security

• PHP sandbox with open_basedir isolation
• Disabled dangerous PHP functions
• Rate limiting per user and IP
• Input validation and sanitization
• Secure file upload handling

📊 Monitoring

• Structured logging with structlog
• Real-time quota tracking
• Webhook call monitoring
• Activity logs

🧪 Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test suite
pytest tests/unit/
pytest tests/integration/
pytest tests/e2e/

🚀 Deployment

Optimized for Railway deployment. See ARCHITECTURE_PLAN.md for detailed deployment instructions.

📝 Documentation

• ARCHITECTURE_PLAN.md: Detailed architecture and design decisions
• AGENTS.md: Development workflow and guidelines

📄 License

[Add your license here]

🤝 Contributing

Contributions are welcome! Please read the contributing guidelines before submitting PRs.

📧 Contact

[Add contact information]

---

Version: 1.0
Status: In Development
Last Updated: May 28, 2026