Performance Metrics & Classification

Overview

The performance metrics system is the primary analytical surface of the platform. It retrieves Measurement Data (IAO) derived from the daily sync pipeline, applies Nominal Classification (CCO) based on configurable Objective Specifications (IAO), and serves a rich dashboard with multi-dimensional filtering.

Goal: Enable Ops and Creative teams (Persons bearing Roles) to quickly identify which MaterialArtifacts are performing (winners, top risers) and which need action (bananas, archive candidates).

Participants

Actor	Ontological type	Role
Staff user (Ops/Creative)	Person (CCO) bearing Role	Browses Measurement Data, adjusts Objective Specifications, triggers sync
Dashboard API Worker	EngineeredSystem (IOF)	Serves CRUD endpoints, summary stats, Objective Specification management
Mart refresh job	ProcedureExecution (PKO)	Rebuilds performance_measurement_dataset with fresh Nominal Classifications
Daily sync	ProcedureExecution (PKO)	Feeds raw sales data that powers the Measurement Dataset

Nominal Classification logic

[CCO: Nominal Measurement derived from Objective Specification thresholds | REA: Typification — policy layer governs instance layer]

MaterialArtifacts are auto-classified during mart refresh based on configurable thresholds stored in objective_specification:

Nominal Classification	Rule
top_riser	sales_first_7_days >= top_riser_7_day_threshold OR sales_first_14_days >= top_riser_14_day_threshold
winner	sales_last_30_days >= winner_30_day_threshold
banana	MaterialArtifact is in the bottom N by aggregate_measurement_value (where N = banana_count)
archive_candidate	is_active = false AND sales_last_30_days = 0
none	Does not match any rule

MaterialArtifacts can carry multiple classification flags simultaneously (is_banana, is_winner, is_top_riser, is_archive) in addition to the primary nominal_classification column.

API endpoints

Measurement Data CRUD

Method	Path	Description
GET	/api/performance-metrics	List ArtifactMeasurementDatum with filters, pagination, sorting
GET	/api/performance-metrics/:id	Single datum by artifact_identifier
POST	/api/performance-metrics	Create (rare — typically populated by sync ProcedureExecution)
PUT	/api/performance-metrics/:id	Update datum
DELETE	/api/performance-metrics/:id	Delete datum

Query parameters (list endpoint)

Param	Type	Description
classification	string	Filter by Nominal Classification: top_riser, winner, banana, archive_candidate, all
search	string	Case-insensitive search on product name and artifact_identifier
page	number	Page number (default: 1)
pageSize	number	Items per page (default: 50)

Default sort: nominal_classification DESC, then aggregate_measurement_value DESC.

Statistics & Objective Specifications

Method	Path	Description
GET	/api/performance-metrics/stats/summary	Aggregate counts by Nominal Classification + total Measurement Data
GET	/api/performance-metrics/settings/classification	Current Objective Specification thresholds
PUT	/api/performance-metrics/settings/classification	Update Objective Specification (triggers reclassification on next mart refresh)

Summary response DTO

interface MeasurementDataSummary {
  total_artifacts: number;       // MaterialArtifact count
  top_risers: number;            // Nominal Classification counts
  winners: number;
  bananas: number;
  aggregate_measurement_total: number;  // sum of aggregate_measurement_value
  sales_last_30_days: number;
}

Dashboard features

The performance tracking page provides:

• Stat cards — clickable cards filtering by Nominal Classification
• Multi-dimensional filters — classification, search, product type, vendor, tags (by category), date range, active status
• Sortable columns — click column headers to toggle sort direction
• Pagination — first/prev/page-input/next/last controls
• Classification badges — color-coded: banana (yellow), winner (blue), top riser (green), archive (red)
• Objective Specification dialog — edit thresholds for top_riser_7_day_threshold, top_riser_14_day_threshold, winner_30_day_threshold, banana_count
• ProcedureExecution history — collapsible table showing last 10 procedure execution records with duration and counts

Database tables

Table	Ontological type	Role
performance_measurement_dataset	Dataset (IAO) of Measurement Data	Read-optimized serving table (rebuilt by mart refresh ProcedureExecution)
objective_specification	Objective Specification (IAO)	Configurable thresholds governing Nominal Classification
procedure_execution_record	ProcedureExecution (PKO)	Audit trail for sync procedure execution history

Acceptance criteria

• List endpoint returns paginated ArtifactMeasurementDatum with correct filter application
• Objective Specification update persists and takes effect on next mart refresh ProcedureExecution
• Summary Measurement Data matches actual data (counts and sums are consistent)
• Search works case-insensitively across product name and artifact_identifier
• Multiple Nominal Classification badges display correctly when a MaterialArtifact matches multiple rules