Architecture

Overview

notifito is a monorepo containing five Laravel applications and one shared PHP package. Each application owns its own database and is independently deployable. Services communicate through typed domain events over Redis queues, with synchronous HTTP only where a human is waiting for a response.

Service Map

graph TB Internet["Internet"] Internet --> Edge["edge
public API"] Internet --> Dashboard["dashboard
seller UI"] Edge -->|"HTTP"| Core["core
domain logic"] Dashboard -->|"HTTP"| Core Core --> Admin["admin
operator UI"] Admin -->|"HTTP"| Core Core -->|"queue"| Dispatch["dispatch
delivery"] classDef public fill:#4ecdc4,stroke:#333,stroke-width:2px classDef internal fill:#ffe66d,stroke:#333,stroke-width:2px classDef data fill:#ff6b6b,stroke:#333,stroke-width:2px class Edge,Dashboard public class Core,Admin internal class Dispatch data

Service Responsibilities

edge

The public internet face. Handles:

Stateless and deliberately small. Absorbs hostile traffic.

core

The product. Holds:

dispatch

Absorbs third-party provider failure. Holds:

stateDiagram-v2 [*] --> queued queued --> sending sending --> accepted accepted --> delivered accepted --> failed accepted --> bounced delivered --> [*] failed --> [*] bounced --> [*]

dashboard

Seller-facing UI built with Livewire. No database — all data fetched via HTTP from core. Handles:

admin

Platform operator UI built with Livewire. No database — all data fetched via HTTP from core. Handles:

widget

Standalone JavaScript bundle that executes inside the seller's page. Renders inside a shadow DOM to survive arbitrary seller CSS. Targets under 15KB gzipped.

Data Model

One Postgres server, one database per service, and no cross-database queries under any circumstance.

Tenancy Tables (core)

TablePurpose
tenantsSeller organizations (name, slug, timezone, domains, from_name, from_email)
usersSeller staff, tenant-scoped
api_keysHashed keys, pk_ (publishable) or sk_ (secret)
admin_usersPlatform operator credentials (not tenant-scoped)

Catalog Tables (core)

TablePurpose
item_typesKinds of things (attribute schema, notify policy, subscription mode)
itemsNamed instances belonging to a type (nullable relationship)

Subscription Tables (core)

TablePurpose
consumersPeople waiting, tenant-scoped
contact_points(consumer, channel, value) with verification status
subscriptionsLinks consumer to item type + attributes, with status lifecycle
consent_eventsAppend-only ledger of consent actions
availability_eventsIngress events with idempotency keys

Notification Tables (core)

TablePurpose
notificationsMatched subscription + event pairs
outbox_messagesTransactional outbox for reliable event publishing

Delivery Tables (dispatch)

TablePurpose
deliveriesDelivery state tracking
templatesPer-tenant, per-channel message templates

Attribute Schema

JSONB on item_types, an ordered list of attribute definitions:

json
{

"key": "size",

"label": "Size",

"type": "enum",

"options": ["40", "41", "42"],

"required": true,

"matchable": true

}

The closed set of types: enum, integer, decimal, date, date_range, boolean, text. Three consumers share this contract: the widget's form renderer, server-side validation, and the matching engine.

Communication Patterns

Asynchronous (EventBus)

A thin EventBus abstraction over Laravel queues with named per-service queues:

TopicProducerConsumerQueue
availability.receivededge, dashboardcorecore-matching
subscription.confirmation_requestedcoredispatchdispatch-send
subscription.matchedcoredispatchdispatch-send
delivery.status_changeddispatchcorecore-delivery

The abstraction exists so that moving to RabbitMQ later is a configuration change rather than a refactor.

Synchronous (HTTP)

Used only where a human is waiting:

Internal calls travel over a private network with a shared secret header (X-Notifito-Internal-Secret).

Matching Engine

Two stages, deliberately:

flowchart LR A["Availability Event"] --> B["Stage 1: SQL Filter"] B --> C{"Candidate Set"} C --> D["Stage 2: PHP Evaluation"] D --> E["Matched Subscriptions"]

Stage 1: SQL Filter

Filter by tenant, item type, item, status = active, not expired. Uses a GIN index on the attributes JSONB column for cheap equality narrowing.

Stage 2: PHP Evaluation

Type-specific comparison rules over the candidate set. The candidate set after stage one is already small.

Matching criteria:

Error Handling

Data Flow

sequenceDiagram participant W as Widget participant E as edge participant C as core participant D as dispatch participant P as Postmark Note over W,P: Subscription Flow W->>E: Submit subscription E->>C: Validate + create subscription C-->>E: Subscription created (pending) E-->>W: Subscription ID returned Note over D,P: (async) Confirmation email sent W->>E: Click confirm link E->>C: Verify token, activate Note over W,P: Notification Flow E->>C: Push availability C->>C: Match subscriptions C->>D: SubscriptionMatched D->>P: Send email P-->>D: Delivery webhook D->>C: Update status