lcbp3/docs/cross-spec/bullmq-coordination.md

Cross-Spec: BullMQ Queue Coordination

Date: 2026-05-16
Features: 204-rfa-approval-refactor + 302-ai-model-revision
Document: Coordination strategy for shared BullMQ infrastructure

---

Queue Overview

Queue	Feature	Job Types	Priority	Notes
ai-realtime	AI Model Revision	ai-suggest, rag-query	HIGH	Interactive, must not be blocked
ai-batch	AI Model Revision	ocr, extract-metadata, embed-document	LOW	Batch processing, can be paused
rfa-reminders	RFA Approval	reminder-send, escalation	MEDIUM	Scheduled notifications
rfa-distribution	RFA Approval	distribute-document	MEDIUM	Post-approval distribution

---

Coordination Rules

1. Queue Isolation

// AI queues are isolated from RFA queues
// Each feature has dedicated queue names
export const QUEUE_AI_REALTIME = 'ai-realtime';
export const QUEUE_AI_BATCH = 'ai-batch';
export const QUEUE_RFA_REMINDERS = 'rfa-reminders';
export const QUEUE_RFA_DISTRIBUTION = 'rfa-distribution';

2. Priority Strategy

Priority Level	Queue	Use Case
1 (Highest)	ai-realtime	User-facing AI suggestions
2	rfa-reminders	Due date notifications
3	rfa-distribution	Document distribution
4 (Lowest)	ai-batch	Background embedding

3. Auto-Pause Mechanism

// AI Realtime Processor pauses ai-batch when active
@OnWorkerEvent('active')
async onActive() {
  await this.aiBatchQueue.pause();
}

@OnWorkerEvent('completed')
@OnWorkerEvent('failed')
async onCompletedOrFailed() {
  await this.aiBatchQueue.resume();
}

4. Concurrency Limits

Queue	Concurrency	Reason
ai-realtime	1	GPU sharing with ai-batch
ai-batch	1	GPU sharing with ai-realtime
rfa-reminders	5	Email notifications can batch
rfa-distribution	3	Transmittal creation moderate

5. Conflict Prevention

• No job name conflicts: Each job type has unique naming
• No data cross-contamination: Different payloads per queue
• Separate Redis keys: Queue prefixes ensure isolation

---

Monitoring

Check queue status:

# Redis CLI
redis-cli KEYS "bull:*"

# Check queue lengths
redis-cli LLEN "bull:ai-realtime:wait"
redis-cli LLEN "bull:rfa-reminders:wait"

---

Verification Checklist

• ai-realtime and ai-batch have auto-pause/resume
• rfa-reminders doesn't block AI queues
• All queues have unique names
• Concurrency configured per queue
• Priority levels documented