🎮 Scrapox - Roblox Promo Code Scraper

Beautiful, fast, and smart Roblox promo code aggregator

---

✨ Features

• 🚀 10+ Sources - Aggregates from RobloxDen, GamesRadar, PocketTactics, and more
• ⚡ Parallel Scraping - All sources scraped simultaneously (3-5 seconds total)
• 🧠 Smart Deduplication - Reliability-weighted code selection
• 🎨 Beautiful TUI - Interactive Terminal UI with Textual (NEW!)
• 🔒 Rate Limiting - Prevents IP bans (10s between requests per source)
• 📊 Source Tracking - Reliability ratings and statistics
• 🔔 Notifications - Discord and Telegram support
• 💾 SQLite Database - Persistent storage with history

---

🚀 Quick Start

Installation

# Clone repository
git clone https://github.com/yourusername/scrapox.git
cd scrapox

# Install dependencies
pip install -r requirements.txt

# Or install as package
pip install -e .

Usage

# 🎨 Launch interactive TUI (NEW!)
scrapox tui

# Scrape all sources once
scrapox scrape

# Continuous monitoring (every 2 hours)
scrapox monitor --interval 2

# Browse codes with filters
scrapox list --status active --sort-by reliability

# View source statistics
scrapox stats

See TUI Guide for detailed TUI documentation.

---

📊 Example Output

  ╔═══════════════════════════════════════╗
  ║  🎮 Scrapox - Roblox Code Scraper    ║
  ║  ✨ Discover the latest codes!        ║
  ╚═══════════════════════════════════════╝

⠋ 🔍 Scraping 10 sources... ━━━━━━━ 80%

╭─────────── 📈 Scrape Results ───────────╮
│ 🆕 New Codes: 5                         │
│ 📊 Total Active: 68                     │
│ ⏱️  Duration: 3.45s                     │
╰─────────────────────────────────────────╯

         ✨ 🆕 New Codes ✨
╭────────┬───────────┬─────────┬────────╮
│🎯 Code │📦 Item    │🌐 Source│⭐Status│
├────────┼───────────┼─────────┼────────┤
│CODE123 │Cool Item  │RobloxDen│ ✅ ⭐⭐⭐│
╰────────┴───────────┴─────────┴────────╯

---

🏗️ Architecture

Scrapox uses a pragmatic 3-tier architecture:

┌─────────────────────────────────────┐
│ Tier 1: Interface Layer             │
│ • CLI (cli.py) - Command interface  │
│ • TUI (tui.py) - Interactive UI     │
├─────────────────────────────────────┤
│ Tier 2: Business Logic              │
│ • scraper.py - Async orchestration  │
│ • monitor.py - Scheduled scraping   │
│ • parsers.py - HTML extraction      │
├─────────────────────────────────────┤
│ Tier 3: Data & Services             │
│ • database.py - SQLite persistence  │
│ • notifications.py - Alerts         │
└─────────────────────────────────────┘

Design Philosophy: Simple over complex, working over perfect

---

📁 Project Structure

scrapox/
├── scrapox/              # Main package
│   ├── __init__.py       # Package metadata
│   ├── cli.py            # CLI interface
│   ├── tui.py            # Terminal UI (Textual)
│   ├── scraper.py        # Core scraping logic
│   ├── database.py       # SQLite operations
│   ├── monitor.py        # Continuous monitoring
│   ├── parsers.py        # HTML extraction
│   └── notifications.py  # Discord/Telegram
├── tests/                # Test suite (60% coverage)
├── docs/                 # Documentation
│   └── TUI_GUIDE.md      # TUI usage guide
├── config.yaml           # Configuration
├── requirements.txt      # Dependencies
└── README.md             # This file

---

⚙️ Configuration

Edit config.yaml to customize:

• Sources: Enable/disable sources, change URLs
• Rate Limiting: Adjust requests per minute
• Notifications: Configure Discord/Telegram webhooks
• Database: Change database path

Environment Variables

For secrets (optional):

export SCRAPOX_DISCORD_WEBHOOK="https://discord.com/api/webhooks/..."
export SCRAPOX_TELEGRAM_BOT_TOKEN="123456789:ABC..."
export SCRAPOX_TELEGRAM_CHAT_ID="987654321"

---

🧪 Testing

# Run all tests
pytest

# With coverage report
pytest --cov=scrapox --cov-report=html

# Run specific test
pytest tests/test_deduplication.py

Target: 60% test coverage (pragmatic goal)

---

📈 Performance

Metric	Target	Actual
Scrape Duration (10 sources)	< 5s	3-5s ✅
Memory Usage	< 100MB	~60MB ✅
Database Size (100k codes)	~50MB	~45MB ✅

---

🛠️ Development

Setup Development Environment

# Clone repo
git clone https://github.com/yourusername/scrapox.git
cd scrapox

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

# Install with dev dependencies
pip install -r requirements.txt
pip install -e .

Running Locally

# Run scraper
python -m scrapox scrape

# Run with debug logging
python -m scrapox scrape --config config.yaml

---

🔐 Security

• ✅ Rate limiting - Prevents IP bans
• ✅ Code validation - Alphanumeric only, max 20 chars
• ✅ Parameterized queries - SQL injection prevention
• ✅ Environment variables - No secrets in code
• ✅ Public data only - No authentication bypass

---

📝 License

MIT License - see LICENSE file

---

🙏 Credits

Sources:

• RobloxDen, GamesRadar, PocketTactics, FossBytes
• SimplyCodes, Times of India, Eldorado.gg
• PCGamer, TheSpike.gg, MyRidima

Built With:

• Python, aiohttp, BeautifulSoup4
• Textual (interactive TUI framework)
• Rich (terminal styling)
• SQLite, PyYAML, structlog

---

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ❤️ for the Roblox community