BOOST.Dispatcher (BOOST.DeliveryBoy)

A multi-tenant job dispatch and processing system that receives trigger messages from an AMQP queue and routes them to type-specific executors (email, MQTT, webhook, SMS, push). Jobs are created via BOOST.Secretary and executed here.

Architecture

BOOST.Secretary (any service)
    ↓ JMS message with tenantUUID property
    ↓
ActiveMQ Queue (boost.dispatcher.jobs)
    ↓
TenantDispatcher.onMessage()
    ↓
TriggerMessage.parse()
    ↓
┌──────────────┬──────────────────┬─────────────┐
│ processJob   │ processPending   │ mqttCRUD    │
│              │                  │ (relay)     │
│ JobProcessor │ JobProcessor     │ MQTTService │
│   ↓          │   ↓              │             │
│ JobRouter    │ fetchPendingDue  │             │
│   ↓          │                  │             │
│ JobExecutor  │                  │             │
│ (email/mqtt) │                  │             │
└──────────────┴──────────────────┴─────────────┘

Multi-Tenancy

• Each tenant gets its own TenantDispatcher, Quartz scheduler, and HikariCP database pool
• Messages are filtered by tenantUUID JMS property via message selectors
• MQTT topics are hashed per-tenant using MD5
• DispatcherBoss orchestrates dispatcher creation for all discovered tenants

Prerequisites

• Java 21
• AMQP Message Broker (ActiveMQ Artemis)
• MQTT Broker
• MySQL Database (per-tenant + master)
• ImageMagick (for PDF generation via BOOST.PDFBuilder)

Configuration

config.properties

dispatcher_queue_name=boost.dispatcher.jobs
broker_url=amqp://172.16.200.32:5672
mqtt_host=tcp://172.16.200.158:1883
mqtt_username=BOOSTDispatcher
mqtt_password=****
master.jdbc.url=jdbc:mysql://host:3306/qeeping?useSSL=false&serverTimezone=UTC
master.jdbc.username=qeeping-master
master.jdbc.password=****
hikari.minimum_idle=2
hikari.maximum_pool_size=10
hikari.idle_timeout=300000
hikari.max_lifetime=600000

Trigger Types

processJob

Processes a single job by UUID. Looks up sys_jobs, routes to the correct executor based on messageType, tracks execution in sys_job_queue.

Message:

{
  "triggerType": "processJob",
  "jobUUID": "uuid-string"
}

Job lifecycle: PENDING → IN_PROGRESS → COMPLETED / FAILED

processPending

Processes all jobs in sys_job_queue with status PENDING and scheduledTime <= now.

Message:

{
  "triggerType": "processPending"
}

mqttCRUD

Relays an MQTT message directly — no job record, no DB. Used for device sync and CRUD notifications.

Message:

{
  "triggerType": "mqttCRUD",
  "body": { "topic": "BOOST/{hash}/items", ... }
}

MQTT Topic format: BOOST/{MD5(tenantUUID + salt)}/{entity}

Job Types (messageType)

messageType	Executor	Data table	Description
email	EmailJobExecutor	sys_email_job_data	Send email, optionally with PDF attachment
mqtt	MqttJobExecutor	sys_mqtt_job_data	Publish MQTT message
webhook	TBD	sys_webhook_job_data	HTTP callback
sms	TBD	sys_sms_job_data	SMS message
push	TBD	sys_push_job_data	Push notification (FCM/APNs)

Email Job Flow

1. Fetch SysEmailJobDataRecord via job.jobDataUUID
2. If pdfDataUUID is set → fetch SysPdfJobDataRecord → fetch template from sys_templates → generate PDF
3. Resolve mail provider (specific via mailProviderUUID or tenant default)
4. Send email via provider (SMTP / Mailgun)

MQTT Job Flow

1. Fetch SysMqttJobDataRecord via job.jobDataUUID
2. Read topic and payload
3. Publish via MQTTService

Email Providers

Provider	Status	Implementation
SMTP	Implemented	Generic SMTP with STARTTLS/auth
Mailgun	Implemented	REST API via OkHttp (US + EU regions)
SendGrid	Placeholder	Not yet implemented
AWS SES	Placeholder	Not yet implemented

Provider configuration is stored per-tenant in sys_mail_providers. Each email job can reference a specific provider via mailProviderUUID, or fall back to the tenant's default.

Checksum Sync System

A periodic background process (every 5 minutes via ChecksumPingJob) that:

1. Queries entity tables for row counts, max timestamps, and XOR-based checksums
2. Publishes checksums via MQTT to topic BOOST/{tenant_hash}/sync/ping
3. Clients compare local checksums to detect stale data and request full sync

Database Tables

Job definition

Table	Purpose
sys_jobs	Job record — messageType + jobDataUUID (polymorphic FK to type-specific table)
sys_job_queue	Execution tracking: PENDING → IN_PROGRESS → COMPLETED/FAILED
sys_templates	Shared PDF/document templates (invoices, order confirmations, etc.)

Type-specific job data (sys_<type>_job_data)

Table	Key columns
sys_email_job_data	fromAddress, toAddress, subject, body, mailProviderUUID, pdfDataUUID
sys_mqtt_job_data	topic, payload (JSON)
sys_pdf_job_data	templateUUID (FK → sys_templates), jobData (JSON)
sys_webhook_job_data	url, method, headers (JSON), body (JSON)
sys_sms_job_data	phoneNumber, message, providerUUID
sys_push_job_data	deviceToken, title, body, data (JSON)

Other

Table	Purpose
sys_mail_providers	Per-tenant email provider configuration
QRTZ_*	Quartz scheduler persistence tables

Relationship diagram

sys_jobs
  ├─ messageType = 'email' → jobDataUUID → sys_email_job_data
  │                                           └─ pdfDataUUID → sys_pdf_job_data
  │                                                              └─ templateUUID → sys_templates
  ├─ messageType = 'mqtt'  → jobDataUUID → sys_mqtt_job_data
  ├─ messageType = 'webhook' → jobDataUUID → sys_webhook_job_data
  ├─ messageType = 'sms'   → jobDataUUID → sys_sms_job_data
  └─ messageType = 'push'  → jobDataUUID → sys_push_job_data

sys_job_queue
  └─ jobUUID → sys_jobs.UUID (execution log, multiple entries per job for retries/cron)

Dependencies

Dependency	Version	Purpose
BoostMiddleware	2.0.5	Shared BOOST utilities (UuidUtils, ExecutionContext)
BOOST.Model	1.0.1	jOOQ generated table/record classes
PDFBuilder	1.0.1	PDF generation from templates
jooq	3.19.6	Type-safe SQL
qpid-jms-client	2.10.0	AMQP messaging (Apache Qpid)
paho.mqtt	1.2.5	MQTT publishing
HikariCP	7.0.2	Connection pooling
quartz	2.3.2	Cron job scheduling
jakarta.mail	2.0.1	Email sending (SMTP)
okhttp	4.12.0	HTTP client (Mailgun API)
pdfbox	3.0.2	PDF handling

Project Structure

src/main/java/com/luqon/dispatcher/
├── main/
│   ├── DispatcherApp.java          # Entry point
│   ├── DispatcherBoss.java         # Multi-tenant orchestrator
│   ├── TenantDispatcher.java       # Per-tenant message listener
│   ├── TriggerMessage.java         # Message parser
│   ├── TriggerType.java            # Enum: processJob, processPending, mqttCRUD
│   ├── ActiveMQService.java        # JMS connection management
│   ├── CustomerDataSource.java     # Tenant data wrapper
│   └── DataSourceInitializer.java  # Tenant DB pool initialization
├── job/
│   ├── JobProcessor.java           # Orchestrates job execution + queue tracking
│   ├── JobRouter.java              # Routes messageType → JobExecutor
│   ├── JobExecutor.java            # Executor interface
│   ├── EmailJobExecutor.java       # Email execution (+ optional PDF)
│   ├── MqttJobExecutor.java        # MQTT execution
│   ├── JobQueueService.java        # sys_job_queue CRUD
│   ├── CronJobTrigger.java         # Quartz cron trigger
│   └── CronScheduleManager.java    # Manages cron schedules
├── config/
│   └── AppConfig.java              # Configuration loader
├── email/
│   ├── MailProvider.java            # Provider interface
│   ├── MailProviderFactory.java     # Provider factory
│   ├── MailProviderType.java        # Enum: SMTP, MAILGUN, SENDGRID, SES
│   ├── providers/
│   │   ├── SmtpProvider.java
│   │   └── MailgunProvider.java
│   └── config/
│       ├── MailProviderConfig.java
│       ├── SmtpConfig.java
│       └── MailgunConfig.java
├── PDF/
│   └── PDFUtils.java               # PDF generation utilities
├── mqtt/
│   └── MQTTService.java            # MQTT client (singleton)
├── sync/
│   ├── EntitySyncService.java       # Checksum generation
│   └── ChecksumPingJob.java         # Periodic sync ping (Quartz)
├── utils/
│   ├── ChecksumUtils.java
│   └── SimpleCrypto.java
└── JNDI/
    ├── JndiStorage.java
    └── InMemoryInitialContextFactory.java

Running the Service

java -jar target/dispatcher.jar