Fulfillment Monitoring

Overview

The fulfillment monitoring dashboard provides visibility into daily order fulfillment operations — metrics (Measurement Data) tracking successful and failed fulfillments anchored to calendar days (Temporal Regions). This is a read-only reporting surface that helps the Fulfillment team identify fulfillment issues early.

Goal: Surface daily fulfillment metrics (success/failure rates) so the Fulfillment team can detect problems before they cascade.

API endpoints

Method	Path	Spec	Description
GET	/api/fulfillment-daily-summary	fulfillment.yaml	Daily fulfillment metrics, ordered by day descending
GET	/fulfillments	fulfillment.yaml	List fulfillments (filter by phase, order, provider)
GET	/fulfillments/{fulfillment_id}	fulfillment.yaml	Single fulfillment detail
GET	/analytics/commerce/orders	analytics.yaml	Order analytics with group-by phase (includes fulfilled)
GET	/analytics/commerce/overview	analytics.yaml	Commerce KPIs including fulfillment-adjacent metrics

Response DTO

interface FulfillmentDailySummary {
  day: string;                  // Calendar day (ISO date, e.g. "2025-01-15")
  total_fulfillments: number;   // Total fulfillments processed
  successful: number;           // Successfully completed
  failed: number;               // Failed fulfillments
}

Schema tables

Table	Module	Role
fulfillment_daily_summary	Fulfillment	Read: aggregated daily metrics
order_header	Order	Read: source data with fulfillment status
fulfillment	Fulfillment	Read: individual fulfillment records

Infrastructure

Resource	Type	Purpose
internal	Worker	Serves summary metrics via API
COMMERCE_TELEMETRY	Pipeline	Fulfillment event streaming to R2
Daily sync workflow	CF Workflow	Feeds fulfillment data from Shopify

Participants

Actor	Role
Staff user (Fulfillment)	Reviews daily metrics and trends
Dashboard API Worker	Serves summary metrics
PlanetScale	Database for fulfillment metrics
Daily sync	Feeds fulfillment data from Shopify

Data source

1. Daily sync workflow ingests orders with fulfillment status into order_header
2. The mart refresh process aggregates fulfillment events by calendar day
3. The summary table stores one metric row per day

Dashboard features

• Daily table — rows showing day, total fulfillments, successful count, failed count
• Trend direction — most recent days appear first for quick anomaly detection
• Simple read-only view — no filters or mutations; designed for at-a-glance monitoring

Migration notes

The current system queries fulfillment_daily_summary directly via the Supabase client. In the rewrite, this becomes an API endpoint that queries the equivalent table in PlanetScale.

The fulfillment summary may be implemented as either:

• A dedicated mart table rebuilt by the hourly refresh workflow
• A database view over order_header grouped by day and fulfillment status

Acceptance criteria

• Daily summary returns correct metrics matching raw fulfillment data
• Results are sorted by day descending (most recent first)
• Failed fulfillment count is accurate (derived from fulfillment event data)
• Metrics refresh after each daily sync workflow completes