Building Block #10: BullMQ + Events

Status: 📋 Planned
Dependencies: Building Block #09 (Redis Caching) - Redis must be added first
When: Month 4 (after Redis added)
Context: Solo Developer + AI

Definition

Add event-driven architecture with:

• BullMQ job queue
• Event system
• Background job processing
• Event handlers
• Job retry and failure handling

Dependencies

• ✅ Building Block #09: Redis Caching (required for BullMQ)
  • Redis 7.x must be installed and configured
  • Redis connection available
• Requires BullMQ 5.x
• Requires Redis 7.x (already added in #09)

Technology Addition Process

This building block follows the Technology Addition Process:

1. ✅ ADR Created: ADR-011: Add BullMQ + Events
2. ✅ Building Block Defined: This document
3. ⏳ Complete Through Gates: In progress
4. ⏳ Update Boilerplate: After completion
5. ⏳ Update AI Context: After completion

Implementation Checklist

GATE 1: BUILD

BullMQ Setup

• Install BullMQ 5.x
• Configure BullMQ connection (uses Redis)
• Set up queue structure
• Create queue service
• Test BullMQ connection

Event System

• Define event schema/format
• Create event types
• Implement event emitter (using BullMQ jobs)
• Create event handlers
• Test event system

Background Jobs

• Create job processors
• Implement job retry logic
• Implement job failure handling
• Add job scheduling
• Test background jobs

Integration

• Replace direct function calls with events (where appropriate)
• Update services to emit events
• Update event handlers
• Test event-driven flow

Worker Setup

• Set up worker process (or same process)
• Configure worker concurrency
• Add worker monitoring
• Test worker processing

GATE 2: TEST

• Test BullMQ connection
• Test event emission
• Test event handlers
• Test background jobs
• Test job retry
• Test job failure handling
• Write unit tests for events
• Write integration tests for jobs
• All tests passing

GATE 3: REVIEW & APPROVE

• Self-review event system
• Verify event-driven flow works
• Check job retry and failure handling
• Review event schema
• Document approval reasoning
• Status: ✅ APPROVED

GATE 4: DOCUMENT

• Document BullMQ setup
• Document event system
• Document event schema
• Document job processing
• Update ADR with implementation details
• Update boilerplate definition (move BullMQ to "Included")
• Update .cursorrules with event patterns
• Update CLAUDE.md with BullMQ setup
• Update memory log

GATE 5: COMMIT & TAG

• Git commit with clear message: "Building Block #10: BullMQ + Events complete"
• Tag: building-block-10-bullmq
• Push to main
• Update status tracker

Testing Requirements

Unit Tests

• Event emission
• Event handlers
• Job processors
• Retry logic
• Failure handling

Integration Tests

• Event-driven flow
• Background job processing
• Job retry
• Job failure handling

Documentation Requirements

• BullMQ setup documentation
• Event system documentation
• Event schema documentation
• Job processing guide
• ADR for BullMQ + Events
• Migration guide (from direct calls to events)

Approval Criteria

Building block is complete when:

• ✅ BullMQ integrated
• ✅ Event system working
• ✅ Background jobs processing
• ✅ Job retry and failure handling working
• ✅ All tests passing
• ✅ Boilerplate updated
• ✅ Documentation complete

AI Context

What AI needs to know:

• Use BullMQ 5.x (NOT EventEmitter)
• Use Redis 7.x (already added) for BullMQ
• Events are BullMQ jobs (NOT EventEmitter)
• Event format: { type, payload, tenantId, timestamp }
• Use job queues for async processing
• Use events for decoupled communication

Patterns to follow:

• Event format: { type, payload, tenantId, timestamp }
• Use eventQueue.add() to emit events (creates BullMQ job)
• Use job processors to handle events asynchronously
• Event types: employee.created, leave.approved, etc.

Boilerplate Update

After completion, update Boilerplate Definition:

• Move BullMQ from "NOT Included" to "Included"
• Move Event-driven architecture from "NOT Included" to "Included"
• Update technology list
• Document event patterns

Next Building Block

After completion, can proceed to:

• Feature building blocks (Employee Management, Time-Off, etc.)
• Continue sequential pattern

---

Last Updated: 2025-11-27