Domain Overview

This document describes the key business and technical domains, how they interact, and where to find the most important code.

For platform context (Tillo, Core, Buyers, purchase schemes), see the documentation index. For sequence and flow diagrams, see key flows.

Domain Map

Domains in Detail

Tenant

What it does: Resolves the current tenant from the HTTP host, initialises a shared Tenancy context for the request, and provides Eloquent scoping so that all queries are automatically filtered to the current tenant.

Hosting and DNS: Production runs on EKS under giftstorefront.com. Buyers point a custom domain at StoreFront—historically via a reverse proxy to giftstorefront.com with X-Forwarded-Host (or equivalent) set to their domain, which middleware uses to look up the tenant. Domain management is increasingly in-house (e.g. Cloudflare entries created for the Buyer’s domain).

Key files:

Journey middleware: The tenant middleware group additionally includes JourneyMiddleware, which controls whether an anonymous customer is allowed to browse or is redirected to log in first (depending on the tenant's configuration).

Product

What it does: Manages the gift card catalogue—brands, denominations (fixed or open), categories, images, discounts, cashback rates, and tenant-specific overrides. The mall (catalogue) page exposes a hero banner, promoted-brand carousel, and searchable/filterable catalogue with discount/cashback labels. The product (brand) page shows denominations or open value, brand details and terms, and scheme rates; Buyers can deep-link authenticated users to a brand URL from their own site. A separate Buy as a Gift path on the brand page checks out a single brand in isolation (similar to Amazon’s gift flow), outside the mixed basket journey.

Key files:

Product data is synced from Tillo via background jobs (see the Tillo section).

Order

What it does: The Order domain spans the entire customer purchase journey, from the basket through payment to post-purchase fulfilment.

Customer journey (self-purchase): catalogue → brand page (value + add to basket) → basket → checkout (name, email, payment method) → hosted payment (Stripe, Checkout.com, TrueLayer, etc.) or tenant-specific flows (voucher sync, tenant wallet) → success page with order confirmation and async gift-card redemption links once fulfilment completes (typically within seconds). Buyers control experience before and after StoreFront (campaigns, deep links, cashback in their app) even though StoreFront UI is not white-label editable.

Key files:

Order lifecycle states: awaiting payment → paid → fulfillment → completed / refunded / cancelled

PaymentGateway

What it does: An abstraction layer over multiple payment processors. Each gateway implements the same abstract base class and is wired in as the active gateway via the tenant's configuration.

Key files:

Supported gateways:

Fulfillment & Tillo

What it does: After payment is confirmed, fulfilment creates gift card records and calls the Tillo API to issue real card codes to the customer. Tillo exposes both synchronous and asynchronous fulfilment endpoints; StoreFront uses only the asynchronous API—a retryable job places the order, then another job checks status until the card is ready. Tillo also provides product catalogue data (brands, denominations, statuses) kept in sync via Core webhooks and background jobs.

Key files:

Hub (internal admin API)

What it does: A JSON REST API used by the new Hub admin UI (Nuxt), which replaces the legacy Hub embedded in Core for StoreFront operations. It provides read/write operations for orders, fulfilment items, tenants, policies, and audit record viewing— including end-customer and payment detail that Core’s Hub cannot show.

Access pattern: All Hub routes are under /api/internal/hub/v1/. Requests must carry a Bearer JWT issued by the Hub platform. The TenantLookupMiddleware maps a Tillo Core user ID to their permitted tenant IDs.

Key files:

Auth

What it does: Storefront authentication is pluggable per tenant. After tenant resolution, the configured protocol (JWT, OAuth, or OIDC) is loaded from encrypted credentials in the database. On success, StoreFront creates a session (and cookie) keyed by the IdP’s sub (or equivalent) as the external user ID. Sessions expire after two hours; the customer is sent back to the Buyer’s site and, if still logged in there, returns to StoreFront with a fresh token. The Hub uses a completely separate JWT-based auth path.

Key files:

Auditing

What it does: Records an immutable, versioned audit trail for domain events. Audit records are stored in AWS DynamoDB (a local DynamoDB container is available via Sail). PII in audit payloads is tokenised before storage.

Key files:

Events registered for auditing can be found in app/Providers/EventServiceProvider.php.

Outbound Webhooks

What it does: After key order events, the application sends signed webhook payloads to the tenant's configured endpoint (e.g. ItemFulfilled, FulfillmentItemRefunded). This is optional per Buyer but critical for real-time cashback and loyalty integrations—typically one webhook per fulfilled gift card, carrying order ID, item ID, brand, amount, user ID, and discount/cashback metadata. Payloads are versioned (V1 / V2) and dispatched via a dedicated webhooks queue.

Key files:

Reporting

What it does: Generates and emails monthly transaction reports directly to Buyers (alongside separate monthly invoicing from Tillo finance). Also contains billing/fee scheme logic for calculating monthly revenue and dispute reporting.

Key files:

Shared

What it does: Cross-cutting utilities used by multiple domains.

Key files: