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
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:
- Widget API (attribute schema fetch, subscription submit)
- Seller push API (
POST /v1/availability) - Provider webhooks (delivery status)
- Rate limiting and API-key authentication
- Origin allowlist enforcement for widget requests
Stateless and deliberately small. Absorbs hostile traffic.
core
The product. Holds:
- Tenancy (tenants, users, API keys)
- Catalog (item types, items, attribute schemas)
- Subscriptions and consumer records
- Consent ledger (append-only, never updated)
- Matching engine (two-stage: SQL filter + PHP evaluation)
- Transactional outbox for reliable event publishing
dispatch
Absorbs third-party provider failure. Holds:
ChannelDriverinterface- Email driver (Postmark)
- Message templates (per tenant, per channel)
- Send scheduling and retry logic
- Delivery state machine:
dashboard
Seller-facing UI built with Livewire. No database — all data fetched via HTTP from core. Handles:
- Authentication (session-based, delegates to core)
- Item type CRUD with schema editor
- Notify form (triggers availability events through the public API)
admin
Platform operator UI built with Livewire. No database — all data fetched via HTTP from core. Handles:
- Tenant management (CRUD, user/key management)
- Cross-tenant subscription search
- Delivery log monitoring
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)
| Table | Purpose |
|---|---|
tenants | Seller organizations (name, slug, timezone, domains, from_name, from_email) |
users | Seller staff, tenant-scoped |
api_keys | Hashed keys, pk_ (publishable) or sk_ (secret) |
admin_users | Platform operator credentials (not tenant-scoped) |
Catalog Tables (core)
| Table | Purpose |
|---|---|
item_types | Kinds of things (attribute schema, notify policy, subscription mode) |
items | Named instances belonging to a type (nullable relationship) |
Subscription Tables (core)
| Table | Purpose |
|---|---|
consumers | People waiting, tenant-scoped |
contact_points | (consumer, channel, value) with verification status |
subscriptions | Links consumer to item type + attributes, with status lifecycle |
consent_events | Append-only ledger of consent actions |
availability_events | Ingress events with idempotency keys |
Notification Tables (core)
| Table | Purpose |
|---|---|
notifications | Matched subscription + event pairs |
outbox_messages | Transactional outbox for reliable event publishing |
Delivery Tables (dispatch)
| Table | Purpose |
|---|---|
deliveries | Delivery state tracking |
templates | Per-tenant, per-channel message templates |
Attribute Schema
JSONB on item_types, an ordered list of attribute definitions:
{
"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:
| Topic | Producer | Consumer | Queue |
|---|---|---|---|
availability.received | edge, dashboard | core | core-matching |
subscription.confirmation_requested | core | dispatch | dispatch-send |
subscription.matched | core | dispatch | dispatch-send |
delivery.status_changed | dispatch | core | core-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:
edge→coreon widget submitdashboard→corethroughoutadmin→corethroughout
Internal calls travel over a private network with a shared secret header (X-Notifito-Internal-Secret).
Matching Engine
Two stages, deliberately:
Filter by tenant, item type, item, status = active, not expired. Uses a GIN index on the attributes JSONB column for cheap equality narrowing.
Type-specific comparison rules over the candidate set. The candidate set after stage one is already small.
Matching criteria:
- Tenant and item type must agree
- Item agrees (or either side is a wildcard)
- Every matchable attribute is compatible (per-type rules for enum equality, numeric containment, date-range overlap)
Error Handling
- Lost events: Transactional outbox in
core— domain change and outbound event commit in a single transaction. - Double sends: Ingest idempotency key on
availability_events; unique constraint on(subscription_id, availability_event_id). - Provider outages: Exponential backoff (~6 attempts over several hours), then
failed. Each notification is its own job. - Hard bounces: Mark contact point invalid and stop. Never retry. Never treat as consent withdrawal.
- Schema drift: Schemas are versioned; subscriptions record the version under which they were captured.