Communication Architecture

notifito uses asynchronous communication by default. Services communicate through an event bus (Redis queues) unless a human is waiting for the answer.

Communication Patterns

PatternUse CaseExample
AsynchronousBackground processingMatching, sending emails
SynchronousHuman waitingWidget submit, dashboard API

Event Bus Abstraction

The EventBus interface in packages/contracts provides a thin abstraction over Laravel queues. This exists so that moving to RabbitMQ later is a configuration change, not a refactor.

Interface

php
// packages/contracts/src/Bus/EventBus.php

interface EventBus

{

public function publish(DomainEvent $event): void;

/** @param iterable<DomainEvent> $events */

public function publishAll(iterable $events): void;

}

Domain Event Interface

php
// packages/contracts/src/Bus/DomainEvent.php

interface DomainEvent

{

public function topic(): string;

public function correlationId(): string;

/** @return array<string, mixed> */

public function toArray(): array;

/** @param array<string, mixed> $payload */

public static function fromArray(array $payload): static;

}

Implementations

ImplementationPurpose
QueueEventBusProduction: publishes to Laravel queues
FakeEventBusTesting: in-memory event collection
OutboxEventBusCore default: writes to transactional outbox

Topic Routing

Events are routed to specific queues based on their topic.

TopicProducerConsumerQueueDescription
availability.receivededge, dashboardcorecore-matchingNew availability event
subscription.confirmation_requestedcoredispatchdispatch-sendSend confirmation email
subscription.matchedcoredispatchdispatch-sendSend notification email
delivery.status_changeddispatchcorecore-deliveryDelivery status update

Core Route Configuration

php
// apps/core/config/notifito.php

'bus' => [

'routes' => [

'availability.received' => ['connection' => 'redis', 'queue' => 'core-matching'],

'subscription.confirmation_requested' => ['connection' => 'redis', 'queue' => 'dispatch-send'],

'subscription.matched' => ['connection' => 'redis', 'queue' => 'dispatch-send'],

'delivery.status_changed' => ['connection' => 'redis', 'queue' => 'core-delivery'],

],

],

Dispatch Route Configuration

php
// apps/dispatch/config/notifito.php

'bus' => [

'routes' => [

'delivery.status_changed' => ['connection' => 'redis', 'queue' => 'core-delivery'],

],

],


Event Payloads

AvailabilityEventReceived

Emitted when a seller signals availability.

php
// packages/contracts/src/Events/AvailabilityEventReceived.php

final readonly class AvailabilityEventReceived implements DomainEvent

{

public function __construct(

public string $eventId,

public string $tenantId,

public string $itemTypeId,

public ?string $itemId,

public array $attributes,

public ?int $capacity,

public ?string $availableFrom,

public ?string $availableUntil,

public AvailabilitySource $source,

public string $idempotencyKey,

public string $correlationId,

public string $occurredAt,

) {}

}

Wire Format:
json
{

"event_id": "evt-123",

"tenant_id": "ten-456",

"item_type_id": "it-789",

"item_id": null,

"attributes": {"size": "42"},

"capacity": 3,

"available_from": null,

"available_until": null,

"source": "push_api",

"idempotency_key": "unique-key",

"correlation_id": "corr-abc",

"occurred_at": "2026-08-28T10:00:00+00:00"

}

ConfirmationRequested

Emitted when a subscription needs email confirmation.

php
// packages/contracts/src/Events/ConfirmationRequested.php

final readonly class ConfirmationRequested implements DomainEvent

{

public function __construct(

public string $tenantId,

public string $tenantName,

public string $subscriptionId,

public string $contactPointId,

public string $channel,

public string $contactValue,

public string $confirmUrl,

public string $itemTypeName,

public ?string $itemName,

public array $attributes,

public string $correlationId,

) {}

}

SubscriptionMatched

Emitted when availability matches subscriptions (batched).

php
// packages/contracts/src/Events/SubscriptionMatched.php

final readonly class SubscriptionMatched implements DomainEvent

{

public function __construct(

public string $tenantId,

public string $tenantName,

public string $availabilityEventId,

public string $itemTypeName,

public ?string $itemName,

public array $eventAttributes,

public array $matches, // List of MatchedSubscription

public string $correlationId,

) {}

}

MatchedSubscription value object:
php
final readonly class MatchedSubscription

{

public function __construct(

public string $subscriptionId,

public string $contactPointId,

public string $channel,

public string $contactValue,

public array $attributes,

public string $unsubscribeUrl,

public ?string $actionUrl,

) {}

}

DeliveryStatusChanged

Emitted when delivery status updates.

php
// packages/contracts/src/Events/DeliveryStatusChanged.php

final readonly class DeliveryStatusChanged implements DomainEvent

{

public function __construct(

public string $tenantId,

public string $deliveryId,

public ?string $subscriptionId,

public string $contactPointId,

public string $status,

public ?string $detail,

public ?string $providerMessageId,

public string $occurredAt,

public string $correlationId,

) {}

}


Transactional Outbox

The outbox pattern ensures events are never lost between commit and publish.

Problem

Without the outbox:

  1. Domain change commits
  2. Event is lost here (process crash, network failure)
  3. Event is published

Solution

With the outbox:

  1. Domain change and outbox row commit in same transaction
  2. Relay publishes unpublished rows
  3. Row is marked as published

Implementation

php
// apps/core/app/Domain/Outbox/OutboxEventBus.php

class OutboxEventBus implements EventBus

{

public function publish(DomainEvent $event): void

{

OutboxMessage::query()->create([

'topic' => $event->topic(),

'payload' => $event->toArray(),

'correlation_id' => $event->correlationId(),

]);

}

}

// apps/core/app/Domain/Outbox/OutboxRelay.php

class OutboxRelay

{

public function relay(): void

{

OutboxMessage::query()

->whereNull('published_at')

->each(function (OutboxMessage $message) {

try {

$this->bus->publish(

$this->reconstruct($message)

);

$message->update(['published_at' => now()]);

} catch (\Throwable $e) {

$message->update(['last_error' => $e->getMessage()]);

}

});

}

}

Relay Command

bash
# Run the outbox relay

./bin/artisan core outbox:relay

Run continuously

./bin/artisan core outbox:relay --watch


Correlation IDs

Every request carries a correlation ID from ingest through send, enabling end-to-end tracing.

sequenceDiagram participant S as Seller participant E as edge participant C as core participant D as dispatch S->>E: POST /v1/availability
X-Request-ID: abc-123 E->>C: AvailabilityEventReceived
correlation_id: abc-123 C->>D: SubscriptionMatched
correlation_id: abc-123 D->>D: Send email
correlation_id: abc-123

Implementation

php
// edge generates or propagates correlation ID

$correlationId = $request->header('X-Request-ID')

?? Str::uuid()->toString();

// Carried through all events

$event = new AvailabilityEventReceived(

correlationId: $correlationId,

// ...

);


Queue Configuration

Queue Names

QueueServicePurpose
core-matchingcoreAvailability event processing and matching
core-deliverycoreDelivery status updates from dispatch
dispatch-senddispatchEmail sending (confirmations + notifications)

Retry Configuration

QueueTriesBackoffTimeout
core-matching5Default120s
core-delivery5Default60s
dispatch-send660, 300, 900, 3600, 10800s60s

Horizon Supervisors

php
// apps/core/config/horizon.php

'environments' => [

'production' => [

'supervisor-matching' => [

'connection' => 'redis',

'queue' => ['core-matching'],

'balance' => 'auto',

'minProcesses' => 1,

'maxProcesses' => 6,

'tries' => 5,

'timeout' => 120,

],

'supervisor-delivery' => [

'connection' => 'redis',

'queue' => ['core-delivery'],

'balance' => 'auto',

'minProcesses' => 1,

'maxProcesses' => 3,

'tries' => 5,

'timeout' => 60,

],

],

],


Synchronous Communication

Used only where a human is waiting for the answer.

edge → core

Widget subscription submit:

php
$response = Http::withHeaders([

'X-Notifito-Internal-Secret' => config('notifito.internal_secret'),

])

->post('http://core:8000/internal/subscriptions', $payload);

dashboard / admin → core

All dashboard and admin API calls:

php
// CoreClient.php

private function request(): PendingRequest

{

return Http::baseUrl(config('notifito.core_url'))

->withHeaders([

'X-Notifito-Internal-Secret' => config('notifito.internal_secret'),

]);

}

Internal Authentication

All internal HTTP calls require the X-Notifito-Internal-Secret header.

php
// Middleware in core

public function handle(Request $request, Closure $next)

{

$secret = $request->header('X-Notifito-Internal-Secret');

if (!hash_equals(config('notifito.internal_secret'), $secret)) {

return response()->json(['message' => 'Unauthorized'], 401);

}

return $next($request);

}


Error Handling

Lost Events

Prevented by the transactional outbox pattern. Domain changes and outbound event commits happen in a single database transaction.

Double Sends

Prevented by database constraints:

sql
-- Availability event idempotency

ALTER TABLE availability_events

ADD CONSTRAINT availability_events_tenant_id_idempotency_key_unique

UNIQUE (tenant_id, idempotency_key);

-- Notification deduplication

ALTER TABLE notifications

ADD CONSTRAINT notifications_subscription_id_availability_event_id_unique

UNIQUE (subscription_id, availability_event_id);

Provider Outages

Exponential backoff with dead-letter queue:

php
// apps/dispatch/app/Jobs/SendDeliveryJob.php

public int $tries = 6;

public function backoff(): array

{

return [60, 300, 900, 3600, 10800]; // ~6 attempts over several hours

}

Each notification is its own job — one bad recipient never stalls a batch. Dead-letter queue with alerts for poison messages.