Services

Detailed per-service documentation covering responsibilities, data ownership, and internal design.


edge

Path: apps/edge/ Role: Public API surface Database: None (stateless)

Responsibilities

Key Design Decisions

Endpoints

MethodPathAuthPurpose
GET/v1/widget/schemaOriginAttribute schema
POST/v1/widget/subscriptionspk_ + OriginCreate subscription
GET/c/{token}TokenConfirm subscription
GET\POST/u/{token}TokenUnsubscribe
POST/v1/availabilitysk_Report availability
POST/webhooks/postmarkBasicDelivery webhook

core

Path: apps/core/ Role: Domain logic Database: notifito_core (Postgres)

Responsibilities

Data Ownership

Core owns all domain data. No other service writes directly to core's database.

Matching Engine

The matching engine is the product's core logic:

  1. Stage 1 (SQL): Filter by tenant, item type, item, status = active, not expired. Uses a GIN index on the attributes JSONB column.
  1. Stage 2 (PHP): Evaluate type-specific comparison rules:
- enum, boolean, text — equality (set intersection for multiple)

- integer, decimal — equality or range containment

- date — equality

- date_range — overlap

Notification Policies

Per item type:

PolicyBehavior
all (default)Notify every matching subscription
capacity_multipleNotify oldest capacity × factor subscriptions (factor defaults to 3)

Subscription Modes

ModeBehavior
once (default)Subscription moves to notified after notification
recurringSubscription stays active (for renewal reminders)

Transactional Outbox

Domain changes and outbound event commits happen in a single database transaction. A relay publishes them to the queue. This prevents event loss in the window between commit and publish.


dispatch

Path: apps/dispatch/ Role: Notification delivery Database: notifito_dispatch (Postgres)

Responsibilities

Driver Interface

php
interface ChannelDriver

{

public function supports(ContactPoint $contactPoint): bool;

public function send(OutboundMessage $message): SendResult;

public function cost(OutboundMessage $message): float;

}

Delivery State Machine

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

Templates

Per tenant, per channel, rendered from a whitelisted variable set:

Tenants never supply raw Blade. Sensible defaults ship per channel.

Retry Logic

Exponential backoff, approximately six attempts over several hours, then failed. Each notification is its own job — one bad recipient never stalls a batch. Dead-letter queue with alerts for poison messages.


dashboard

Path: apps/dashboard/ Role: Seller-facing UI Database: None

Responsibilities

Design

Built with Laravel + Livewire. Owns no domain database — all data fetched via HTTP from core. Session and cache state live in Redis.

The dashboard's "Notify" button renders the identical form as the push API and posts to the identical endpoint, preventing the two ingress paths from drifting apart.

Pages

PageDescription
LoginEmail/password authentication
DashboardOverview with key metrics
Item TypesList, create, edit item types with schema editor
NotifyForm to trigger availability events
SettingsTenant configuration

admin

Path: apps/admin/ Role: Platform operator UI Database: None

Responsibilities

Design

Same pattern as dashboard: Laravel + Livewire, no database, all data via HTTP to core. Separate auth flow using AdminUser model (not tenant-scoped).

Pages

PageRouteDescription
Login/loginAdmin authentication
Tenants/tenantsList all tenants with counts
Create Tenant/tenants/newTenant creation form
Edit Tenant/tenants/{id}/editTenant edit form
Tenant Detail/tenants/{id}Tabs: overview, users, API keys
Create User/tenants/{id}/users/newUser creation form
Subscriptions/subscriptionsCross-tenant search
Subscription Detail/subscriptions/{id}Full detail with consent history
Deliveries/deliveriesRecent deliveries with filters

widget

Path: widget/ Role: Embeddable notification widget Bundle: Vanilla JavaScript, no framework

Responsibilities

Design

Executes inside the seller's page, rendered inside a shadow DOM to survive arbitrary seller CSS. Built with esbuild, targets under 15KB gzipped.

Embedding

html
<script

src="https://cdn.notifito.com/widget.js"

data-pk="pk_live_..."

data-type="sneaker"

></script>

Attribute Type Rendering

TypeWidget Component
enum
integerNumber input (with optional min/max)
decimalNumber input (with step)
dateDate picker
date_rangeTwo date pickers (from/to)
booleanCheckbox
textText input

packages/contracts

Path: packages/contracts/ Role: Shared event payloads and DTOs

Contents

FilePurpose
Catalog/AttributeType.phpClosed seven-type enum
Catalog/AttributeDefinition.phpSingle attribute schema definition
Catalog/AttributeSchema.phpVersioned list of attribute definitions
Catalog/AttributeBagValidator.phpShared validation (edge + core)
Bus/EventBus.phpPublish interface
Bus/QueueEventBus.phpLaravel-queue implementation
Bus/FakeEventBus.phpIn-memory test double
Events/*.phpDomain event payloads

Why This Package Exists

Contract tests exercise every payload from both the producing and consuming side. Changing a payload breaks CI rather than production. This is the main benefit a monorepo offers.