The Notification System That Grew Out of Control

My solution — Challenge 2: Notification System

General Architecture#

┌─────────────────┐          Domain Events           ┌──────────────────┐
│                 │  ReservationConfirmed            │                  │
│   Reservation   │  ReservationRejected             │                  │
│   Bounded       │  ReservationCheckedOut  ─────►   │   Notification   │
│   Context       │  PaymentOverdue                  │   Module         │
│                 │  CheckInApproaching              │                  │
└─────────────────┘                                  └──────────────────┘
                                                          │
     The reservation domain does NOT know                  ├─► NotificationDispatcher
     that notifications exist.                             │     │
     It only emits events with a payload.                   │     ├─ Query owner preferences
                                                          │     │
                                                          │     ├─ Generate 1 message per channel
                                                          │     │
                                                          │     └─ Dispatch to channel queue
                                                          │
                                                          ├─► Email Queue ─► EmailChannel
                                                          ├─► SMS Queue   ─► SmsChannel
                                                          ├─► Push Queue  ─► PushChannel
                                                          └─► WA Queue    ─► WhatsAppChannel

Each event only contains reservation data, not notification data:

// The domain emits this. It knows nothing about emails or SMS.

final class ReservationConfirmed
{
    public function __construct(
        public readonly string $reservationId,
        public readonly string $guestId,
        public readonly string $ownerId,
        public readonly DateTimeImmutable $checkInDate,
        public readonly Money $totalAmount,
    ) {}
}

The dispatcher is responsible for orchestration:

final class ReservationConfirmedHandler
{
    public function __invoke(ReservationConfirmed $event): void
    {
        // Determine WHICH notifications to generate
        $ownerPrefs = $this->preferencesRepo->forOwner($event->ownerId);

        // To the guest: email + SMS + push (always)
        $this->dispatch(new SendNotification(
            recipientId: $event->guestId,
            type: 'reservation_confirmed',
            channels: ['email', 'sms', 'push'],
            payload: [...],
            idempotencyKey: "resconf-{$event->reservationId}-guest",
        ));

        // To the owner: according to their preferences
        $this->dispatch(new SendNotification(
            recipientId: $event->ownerId,
            type: 'reservation_confirmed',
            channels: $ownerPrefs->activeChannels(),
            payload: [...],
            idempotencyKey: "resconf-{$event->reservationId}-owner",
        ));
    }
}

The NotificationDispatcher splits notifications into separate queues by channel:

final class NotificationDispatcher
{
    public function __invoke(SendNotification $command): void
    {
        foreach ($command->channels as $channelName) {
            $key = "{$command->idempotencyKey}-{$channelName}";

            // Idempotency BEFORE enqueueing
            if ($this->idempotencyStore->exists($key)) {
                continue;
            }

            $this->idempotencyStore->reserve($key); // INSERT with "pending" status

            // Each channel has its own queue
            $this->bus->dispatch(
                new ChannelDelivery($channelName, $command->payload, $key)
            );
        }
    }
}

New Channel (WhatsApp)#

// 1. Create the class

final class WhatsAppChannel implements NotificationChannel
{
    // ...
}

// 2. Register it in the service container (autowiring by tag)

// 3. Done. No existing class needs to be modified.

Scheduled Notifications — Hybrid Model#

When a reservation is confirmed:

  │
  ├─ Calculate: check_in - 48h = notification date
  │
  └─ INSERT into scheduled_notifications table:
       reservation_id, type, execute_at, status=pending, payload

Cron every 10 minutes (lightweight):

  │
  SELECT * FROM scheduled_notifications
  WHERE execute_at <= NOW()
    AND status = 'pending'
  LIMIT 100

  │
  └─ For each result → dispatch to corresponding queue
                         → UPDATE status = 'dispatched'

The query is fast because it has an index on (status, execute_at) and only retrieves notifications that are due now; it does not scan the entire reservations table.

If the reservation is cancelled, simply mark the scheduled_notification as cancelled.

Idempotency — Complete Safe Flow#

1. Consumer reads message from the queue.

2. Does an idempotency_key with "sent" status exist? → ACK and discard.

3. Does one with "pending" status exist? → Continue to step 4.

   • If it doesn't exist → INSERT with "pending" status.

4. Send through the channel (email, SMS, etc.).

5. UPDATE status to "sent".

6. ACK the message from the queue.

If it fails between steps 4 and 5:

→ SQS redelivers the message

→ Step 3 finds "pending"

→ Attempts to send again

→ Risk of duplicate in this specific case,
  but this is an acceptable edge case compared
  to the complexity of a two-phase commit
  with the external gateway.