Services
Detailed per-service documentation covering responsibilities, data ownership, and internal design.
edge
Path:apps/edge/
Role: Public API surface
Database: None (stateless)
Responsibilities
- Widget API: schema fetch, subscription submit
- Push API: availability event ingest
- Provider webhooks: delivery status updates
- Rate limiting (per-key and per-IP)
- API-key authentication (
pk_andsk_) - Origin allowlist enforcement for widget requests
Key Design Decisions
- Stateless and deliberately small — absorbs hostile traffic
- No database — delegates all data operations to
corevia HTTP - Widget endpoints are origin-restricted, not API-key-protected (the key identifies the tenant, not the user)
- Push API requires
sk_key (secret, server-to-server only)
Endpoints
| Method | Path | Auth | Purpose | |
|---|---|---|---|---|
| GET | /v1/widget/schema | Origin | Attribute schema | |
| POST | /v1/widget/subscriptions | pk_ + Origin | Create subscription | |
| GET | /c/{token} | Token | Confirm subscription | |
| GET\ | POST | /u/{token} | Token | Unsubscribe |
| POST | /v1/availability | sk_ | Report availability | |
| POST | /webhooks/postmark | Basic | Delivery webhook |
core
Path:apps/core/
Role: Domain logic
Database: notifito_core (Postgres)
Responsibilities
- Tenancy: tenant, user, and API key management
- Catalog: item types, items, attribute schemas
- Subscriptions: consumer records, subscription lifecycle
- Consent ledger: append-only audit trail
- Matching engine: two-stage availability-to-subscription matching
- Transactional outbox: reliable event publishing
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:
- Stage 1 (SQL): Filter by tenant, item type, item,
status = active, not expired. Uses a GIN index on theattributesJSONB column.
- 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:
| Policy | Behavior |
|---|---|
all (default) | Notify every matching subscription |
capacity_multiple | Notify oldest capacity × factor subscriptions (factor defaults to 3) |
Subscription Modes
| Mode | Behavior |
|---|---|
once (default) | Subscription moves to notified after notification |
recurring | Subscription 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
ChannelDriverinterface- Email driver (Postmark)
- Message templates (per tenant, per channel)
- Send scheduling and retry logic
- Delivery state machine
Driver Interface
interface ChannelDriver
{
public function supports(ContactPoint $contactPoint): bool;
public function send(OutboundMessage $message): SendResult;
public function cost(OutboundMessage $message): float;
}
Delivery State Machine
- Accepted: Provider took the message
- Delivered: Webhook confirmed delivery
- Failed: Provider rejected after retries (~6 attempts with exponential backoff)
- Bounced: Hard bounce — mark contact point invalid, stop
Templates
Per tenant, per channel, rendered from a whitelisted variable set:
{{tenant_name}}{{item_type_name}}{{item_name}}{{attributes.*}}{{action_url}}{{unsubscribe_url}}
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
- Authentication (session-based, delegates to core)
- Item type CRUD with schema editor
- Notify form (triggers availability events through the push API)
- Tenant settings
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
| Page | Description |
|---|---|
| Login | Email/password authentication |
| Dashboard | Overview with key metrics |
| Item Types | List, create, edit item types with schema editor |
| Notify | Form to trigger availability events |
| Settings | Tenant configuration |
admin
Path:apps/admin/
Role: Platform operator UI
Database: None
Responsibilities
- Tenant management (list, create, edit, detail)
- User management per tenant
- API key management per tenant
- Cross-tenant subscription search
- Delivery log monitoring
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
| Page | Route | Description |
|---|---|---|
| Login | /login | Admin authentication |
| Tenants | /tenants | List all tenants with counts |
| Create Tenant | /tenants/new | Tenant creation form |
| Edit Tenant | /tenants/{id}/edit | Tenant edit form |
| Tenant Detail | /tenants/{id} | Tabs: overview, users, API keys |
| Create User | /tenants/{id}/users/new | User creation form |
| Subscriptions | /subscriptions | Cross-tenant search |
| Subscription Detail | /subscriptions/{id} | Full detail with consent history |
| Deliveries | /deliveries | Recent deliveries with filters |
widget
Path:widget/
Role: Embeddable notification widget
Bundle: Vanilla JavaScript, no framework
Responsibilities
- Render subscription form inside seller's page
- Fetch attribute schema from edge API
- Validate input client-side against schema
- Submit subscription to edge API
- Handle confirmation/unconfirmation states
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
<script
src="https://cdn.notifito.com/widget.js"
data-pk="pk_live_..."
data-type="sneaker"
></script>
Attribute Type Rendering
| Type | Widget Component |
|---|---|
enum | (or multi-select if multiple: true) |
integer | Number input (with optional min/max) |
decimal | Number input (with step) |
date | Date picker |
date_range | Two date pickers (from/to) |
boolean | Checkbox |
text | Text input |
packages/contracts
Path:packages/contracts/
Role: Shared event payloads and DTOs
Contents
| File | Purpose |
|---|---|
Catalog/AttributeType.php | Closed seven-type enum |
Catalog/AttributeDefinition.php | Single attribute schema definition |
Catalog/AttributeSchema.php | Versioned list of attribute definitions |
Catalog/AttributeBagValidator.php | Shared validation (edge + core) |
Bus/EventBus.php | Publish interface |
Bus/QueueEventBus.php | Laravel-queue implementation |
Bus/FakeEventBus.php | In-memory test double |
Events/*.php | Domain 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.