Fulfillment Monitoring

Overview

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

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

Participants

Actor	Ontological type	Role
Staff user (Fulfillment)	Person (CCO) bearing Fulfillment Role	Reviews daily Measurement Data and trends
Dashboard API Worker	EngineeredSystem (IOF)	Serves summary Measurement Data
PlanetScale	EngineeredSystem (IOF)	IBE store for fulfillment Measurement Data
Daily sync	ProcedureExecution (PKO)	Feeds fulfillment Process data from Shopify commercial transaction records

API endpoints

Method	Path	Description
GET	/api/fulfillment-daily-summary	Daily fulfillment Measurement Data, ordered by Temporal Region descending

Response DTO

interface FulfillmentMeasurementDatum {
  day: string;                  // Temporal Region (ISO date, e.g. "2025-01-15")
  total_fulfillments: number;   // Ratio Measurement: total fulfillments processed
  successful: number;           // Ratio Measurement: successfully completed
  failed: number;               // Ratio Measurement: failed fulfillments
}

Data source

[IAO: Measurement Data derived from Process outcome observation, anchored to Temporal Region]

1. Daily sync ProcedureExecution ingests orders with fulfillment status into commercial_transaction_record
2. The mart refresh Aggregation Process aggregates fulfillment Process events by Temporal Region (day)
3. The summary table stores one Measurement Datum row per Temporal Region

Dashboard features

• Daily table — rows showing Temporal Region (day), total fulfillments, successful count, failed count
• Trend direction — most recent Temporal Regions appear first for quick anomaly detection
• Simple read-only view — no filters or mutations; designed for at-a-glance Process outcome 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 ProcedureExecution
• A database view over commercial_transaction_record grouped by Temporal Region and fulfillment status

Acceptance criteria

• Daily summary returns correct Measurement Data matching raw fulfillment Process data
• Results are sorted by Temporal Region descending (most recent first)
• Failed fulfillment count is accurate (derived from Process outcome observation)
• Measurement Data refreshes after each daily sync ProcedureExecution completes