RouteMQ Framework

A flexible MQTT routing framework with middleware support, dynamic router loading, Redis integration, and horizontal scaling capabilities, inspired by web frameworks.

🚀 Quick Start

Option 1: Use as Template (Recommended)

Start your own project with a clean git history:

Using GitHub (Easiest):

1. Click "Use this template" button on GitHub
2. Create your new repository
3. Clone your repository:

   git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git
   cd YOUR_REPO

Manual Setup:

# Download and extract, or clone
git clone https://github.com/ardzz/RouteMQ.git my-mqtt-project
cd my-mqtt-project

# Run setup script to initialize fresh repository
bash setup-project.sh    # Linux/Mac
# OR
.\setup-project.ps1      # Windows PowerShell

# Install dependencies
uv sync

# Initialize project structure
python main.py --init

# Configure .env file with your MQTT broker details
# Run the application
uv run python main.py --run

Option 2: Direct Clone

To explore or contribute to RouteMQ itself:

git clone https://github.com/ardzz/RouteMQ.git
cd RouteMQ
uv sync
uv run python main.py --init
uv run python main.py --run

✨ Features

• Dynamic Router Loading - Automatically discover and load routes from multiple files
• Route-based MQTT topic handling - Define routes using a clean, expressive syntax
• Middleware support - Process messages through middleware chains
• Parameter extraction - Extract variables from MQTT topics using Laravel-style syntax
• Background Task Queue - Laravel-style queue system for async job processing
• Shared Subscriptions - Horizontal scaling with worker processes
• Redis Integration - Optional Redis support for distributed caching and rate limiting
• Advanced Rate Limiting - Multiple rate limiting strategies with Redis backend
• Optional MySQL integration - Use with or without a database
• Docker Support - Production-ready Docker Compose setup with queue workers
• Environment-based configuration - Flexible configuration through .env files

📚 Documentation

Complete documentation is available in the docs folder, optimized for GitBook integration.

📦 New to RouteMQ? See the Installation Guide for detailed setup instructions.

Quick Links

• Getting Started - Installation, quick start, and basic setup
• Configuration - Environment variables and setup options
• Routing - Route definition, parameters, and organization
• Controllers - Creating and organizing business logic
• Middleware - Request processing and middleware chains
• Queue System - Background task processing and job queues
• Docker Deployment - Production deployment with Docker
• Redis Integration - Caching, sessions, and distributed features
• Rate Limiting - Advanced rate limiting strategies
• Examples - Practical examples and use cases
• API Reference - Complete API documentation
• FAQ - Frequently asked questions

🏗️ Project Structure

RouteMQ/
├── docs/                   # 📖 Complete documentation
├── app/                    # 🚀 Your application code
│   ├── controllers/        # 🎮 Route handlers
│   ├── middleware/         # 🔧 Custom middleware
│   ├── models/            # 🗄️ Database models
│   ├── jobs/              # 📋 Background jobs
│   └── routers/           # 🛣️ Route definitions
├── core/                  # ⚡ Framework core
│   ├── queue/             # 🔄 Queue system
│   ├── job.py             # 📝 Base job class
│   └── ...                # Other core components
├── bootstrap/             # 🌟 Application bootstrap
├── docker-compose.yml     # 🐳 Production Docker setup
└── tests/                 # 🧪 Test files

🐳 Docker Deployment

RouteMQ includes production-ready Docker Compose configuration with Redis, MySQL, and queue workers:

# Start all services (app + 3 queue workers + Redis + MySQL)
docker compose up -d

# View logs
docker compose logs -f

# Scale workers
docker compose up -d --scale queue-worker-default=5

# Or use Makefile
make up      # Start all services
make logs    # View logs
make ps      # Show status

See Docker Deployment Guide for detailed instructions.

📋 Background Task Queue

Process time-consuming tasks asynchronously with the built-in queue system:

# Create a job
from core.job import Job

class SendEmailJob(Job):
    max_tries = 3
    queue = "emails"

    async def handle(self):
        # Send email logic
        pass

# Dispatch the job
from core.queue.queue_manager import dispatch

job = SendEmailJob()
job.to = "[email protected]"
await dispatch(job)

# Run queue worker
python main.py --queue-work --queue emails

See Queue System Documentation for complete guide.

🤝 Contributing

We welcome contributions! Please see our documentation for development setup and contribution guidelines.

📄 License

MIT License - see LICENSE file for details.

---

📖 For detailed documentation, examples, and guides, visit the docs folder.