StudyCamp Bot 📚

بوت تيليجرام احترافي لإدارة معسكرات الدراسة الجماعية

العربية | English

---

نظرة عامة

StudyCamp هو بوت تيليجرام متطور لإنشاء وإدارة معسكرات دراسية تفاعلية في المجموعات. يتميز البوت بواجهة عربية جميلة، لوحة تحكم حية تُحدث تلقائياً، وروابط دعوة فريدة لكل معسكر.

المميزات الرئيسية ✨

• 🎯 معالج إنشاء سهل - 3 خطوات فقط: المدة ← المادة ← التأكيد
• 📊 لوحة تحكم حية - تحديث تلقائي كل 10 ثوانٍ
• 🤲 دعاء المذاكرة - يظهر في كل لوحة تحكم
• ⏱️ عداد تنازلي - يعرض الوقت المتبقي بدقة
• 🔗 روابط دعوة فريدة - لكل معسكر رابط خاص للمشاركة
• 👥 تتبع المشاركين - إحصائيات لكل مشارك
• 📱 متابعة خاصة - رسالة خاصة لكل مستخدم

---

Overview

StudyCamp is a production-grade Telegram bot for running interactive study camps in group chats. Features a beautiful Arabic UI, live auto-updating dashboard, and unique invite links per camp.

Key Features ✨

• 🎯 Easy Setup Wizard - Just 3 steps: Duration → Subject → Confirm
• 📊 Live Dashboard - Auto-updates every 10 seconds
• 🤲 Study Dua - Islamic prayer displayed on dashboard
• ⏱️ Countdown Timer - Precise remaining time display
• 🔗 Unique Invite Links - Each camp has its own shareable link
• 👥 Participant Tracking - Stats for each participant
• 📱 Private Follow - Personal tracking message in DM

---

Tech Stack 🛠️

Component	Technology
Language	Python 3.11+
Bot Framework	python-telegram-bot v22+ (async)
Database	SQLite3 + SQLAlchemy 2.0 (aiosqlite)
Scheduling	PTB JobQueue
Timezone	Africa/Cairo
UI Language	Arabic-first

---

Project Structure 📁

study-camps/
├── app/
│   ├── __init__.py
│   ├── main.py              # Entry point
│   ├── config.py            # Configuration
│   ├── db.py                # Database setup
│   ├── models.py            # SQLAlchemy models
│   ├── handlers/
│   │   ├── __init__.py
│   │   ├── camp_wizard.py   # Camp creation wizard
│   │   ├── dashboard.py     # Live dashboard
│   │   ├── admin.py         # Admin controls
│   │   ├── tasks.py         # Task management
│   │   └── stats.py         # Stats & reports
│   ├── services/
│   │   ├── __init__.py
│   │   ├── camp_service.py      # Camp management
│   │   ├── session_service.py   # Study sessions
│   │   ├── scheduler_service.py # Job scheduling
│   │   └── xp_service.py        # XP system
│   └── utils/
│       ├── __init__.py
│       ├── markdown.py      # MarkdownV2 helpers
│       ├── rate_limit.py    # Rate limiting
│       └── logging.py       # Structured logging
├── requirements.txt         # Python dependencies
├── .env.example            # Environment template
├── .gitignore              # Git ignore rules
└── README.md               # This file

---

Installation 🚀

Prerequisites

• Python 3.11 or higher
• Telegram Bot Token (from @BotFather)

Quick Start

1. Clone the repository

git clone https://github.com/Mavdii/study-camps.git
cd study-camps

2. Create virtual environment

python -m venv venv
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate     # Windows

3. Install dependencies

pip install -r requirements.txt

4. Configure environment

cp .env.example .env
# Edit .env and add your BOT_TOKEN

5. Run the bot

python -m app.main

---

VPS Deployment 🖥️

Using systemd (Recommended)

1. Upload files to your VPS

scp -r study-camps/ user@your-vps:/opt/

2. Create systemd service

sudo nano /etc/systemd/system/studycamp.service

[Unit]
Description=StudyCamp Telegram Bot
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/study-camps
Environment=BOT_TOKEN=your_bot_token_here
ExecStart=/opt/study-camps/venv/bin/python -m app.main
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

3. Enable and start service

sudo systemctl daemon-reload
sudo systemctl enable studycamp
sudo systemctl start studycamp

4. Check status

sudo systemctl status studycamp
sudo journalctl -u studycamp -f  # View logs

Using Docker (Alternative)

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["python", "-m", "app.main"]

docker build -t studycamp .
docker run -d --name studycamp -e BOT_TOKEN=your_token studycamp

---

Bot Commands 🤖

Command	Description	Scope
/start	Welcome message + help	All
/help	Help information	All
/camp	Start new camp wizard	Groups only
/camps	Show active camps	Groups only
/stop	Cancel camps (Admin)	Groups only
/me	Personal stats	All
/top	Leaderboard	All
/privacy	Privacy policy	All
/delete_me	Delete user data	All

---

Database Schema 📊

Tables

Table	Description
chats	Group settings and preferences
camps	Study camp instances
camp_members	Participants in each camp
sessions	Individual study sessions
tasks	Camp tasks and assignments
wizard_states	Wizard flow state management

---

Configuration ⚙️

Environment Variables

Variable	Required	Description
BOT_TOKEN	Yes	Telegram bot token from @BotFather
DATABASE_URL	No	SQLite path (default: sqlite+aiosqlite:///./studycamp.db)
TZ	No	Timezone (default: Africa/Cairo)

---

Dashboard Features 📋

The live dashboard displays:

┌─────────────────────────────────────┐
│  🤲 دعاء المذاكرة                   │
│  "اللَّهُمَّ انْفَعْنِي بِمَا        │
│   عَلَّمْتَنِي وَعَلِّمْنِي مَا      │
│   يَنْفَعُنِي وَزِدْنِي عِلْمًا"     │
├─────────────────────────────────────┤
│  📊 معلومات المعسكر                 │
│  ⏱️ الوقت المتبقي: 01:45:30        │
│  📅 المدة: ساعتين                   │
│  👥 المشاركين: 5                    │
├─────────────────────────────────────┤
│  🔗 رابط الدعوة                     │
│  t.me/bot?start=join_CODE           │
├─────────────────────────────────────┤
│  [انضم للكامب] [متابعة خاصة]        │
└─────────────────────────────────────┘

---

Contributing 🤝

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

License 📄

This project is licensed under the MIT License - see the LICENSE file for details.

---

Author 👨‍💻

Omar El-Mahdi (Mavdi)

Full-Stack Developer & Bot Creator

---

Support 💬

If you encounter any issues or have questions, please open an issue on GitHub.

---

Made with 💖 & ☕ by Umar for students worldwide

Empowering minds, one study session at a time ✨