Core Concepts

Understand the fundamental concepts and architecture of RouteMQ.

Topics

• Framework Architecture - Overall system design

• Router Discovery - How routes are loaded

• Message Flow - How messages are processed

• Middleware Pipeline - Request processing chain

• Worker Processes - Shared subscriptions and scaling

Framework Architecture

RouteMQ follows a modular architecture inspired by web frameworks:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   MQTT Broker   │◄──►│   RouteMQ App   │◄──►│   External      │
│                 │    │                 │    │   Services      │
│ - Message Queue │    │ - Route Handler │    │ - Database      │
│ - Pub/Sub       │    │ - Middleware    │    │ - Redis         │
│ - Load Balance  │    │ - Workers       │    │ - APIs          │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Key Components

1. Router Registry

• Discovers and loads route files automatically

• Manages route definitions and middleware

• Handles shared subscriptions

2. Middleware Pipeline

• Processes messages before reaching handlers

• Supports authentication, rate limiting, logging

• Chainable and reusable components

3. Controllers

• Handle business logic for routes

• Async/await support for non-blocking operations

• Direct access to Redis, database, and MQTT client

4. Worker Manager

• Manages shared subscription workers

• Provides horizontal scaling for high-throughput routes

• Load balancing across multiple processes

Message Processing Flow

1. Message Arrives: MQTT broker receives message

2. Route Matching: Framework matches topic to registered routes

3. Middleware Chain: Message passes through middleware pipeline

4. Parameter Extraction: Route parameters extracted from topic

5. Handler Execution: Controller method processes the message

6. Response: Optional response published back to MQTT

Design Principles

• Convention over Configuration: Sensible defaults with customization options

• Async First: Built for non-blocking I/O operations

• Modular: Loosely coupled components

• Scalable: Horizontal scaling through shared subscriptions

• Testable: Easy to unit test and mock dependencies

Next Steps

• Router Discovery - Learn how routes are loaded

• Message Flow - Understand message processing

• Getting Started - Build your first route