Process Path Events (Published)

Overview

This document catalogs all domain events published by the Process Path bounded context. These events follow the CloudEvents 1.0 specification and are published to Apache Kafka.

Implementation Status

All events in this document have been implemented. See the corresponding Java record classes in each service.

Event Categories

Category	Topic	Service	Description
Routing	`process-path.routing.v1.events`	routing-service	Path assignment and rerouting decisions
Orchestration	`process-path.orchestration.v1.events`	orchestration-service	Capacity, workload, and SLA events
Buffer	`process-path.afe.v1.events`	afe-path-service	Buffer state changes (walls, trays, conveyors)
SLAM	`wes.slam.v1.events`	slam-operations-service	SLAM completion for carrier handoff

Routing Events

ShipmentRoutedToPathEvent

Description: Published when a shipment is assigned to a process path.

Topic: process-path.routing.v1.events

Source: process-path-routing-service/src/main/java/com/paklog/wms/processpath/routing/domain/event/ShipmentRoutedToPathEvent.java

Trigger: Path assignment algorithm completes successfully

Consumers: Task Execution, Pick Execution, Analytics, WES Orchestration

{
  "specversion": "1.0",
  "type": "com.paklog.processpath.routing.shipment-routed.v1",
  "source": "/process-path-routing-service",
  "id": "evt-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "time": "2025-01-20T10:00:00.000Z",
  "datacontenttype": "application/json",
  "subject": "SHP-123456",
  "data": {
    "shipmentId": "SHP-123456",
    "orderId": "ORD-789012",
    "assignedPath": "AFE",
    "pathId": "PATH-AFE-01",
    "routingScore": 87.5,
    "routingFactors": {
      "capacityScore": 15.0,
      "bufferScore": 30.0,
      "laborScore": 22.5,
      "affinityScore": 20.0
    },
    "shipmentType": "MULTI",
    "itemCount": 3,
    "slaPriority": "GREEN",
    "estimatedCycleTime": "PT15M",
    "carrierCutoffTime": "2025-01-20T16:00:00Z",
    "routedAt": "2025-01-20T10:00:00Z"
  }
}

Schema:

Field	Type	Required	Description
`shipmentId`	string	Yes	Unique shipment identifier
`orderId`	string	Yes	Parent order identifier
`assignedPath`	enum	Yes	SINGLES, AFE, BATCH_FLOW
`pathId`	string	Yes	Specific path instance ID
`routingScore`	number	Yes	Calculated fitness score (0-100)
`routingFactors`	object	Yes	Score breakdown by factor
`shipmentType`	enum	Yes	SINGLE, MULTI, SPECIAL
`itemCount`	integer	Yes	Number of items in shipment
`slaPriority`	enum	Yes	GREEN, YELLOW, RED
`estimatedCycleTime`	duration	Yes	ISO 8601 duration
`carrierCutoffTime`	datetime	Yes	Carrier pickup deadline
`routedAt`	datetime	Yes	Routing decision timestamp

PathAssignmentFailedEvent

Description: Published when no eligible path can be found for a shipment.

Topic: process-path.routing.v1.events

Source: process-path-routing-service/src/main/java/com/paklog/wms/processpath/routing/domain/event/PathAssignmentFailedEvent.java

Trigger: Path assignment algorithm fails to find eligible path

Consumers: Operations Alert, Problem Solve, Order Management

{
  "specversion": "1.0",
  "type": "com.paklog.processpath.routing.path-assignment-failed.v1",
  "source": "/process-path-routing-service",
  "id": "evt-f1e2d3c4-b5a6-7890-1234-567890abcdef",
  "time": "2025-01-20T10:05:00.000Z",
  "datacontenttype": "application/json",
  "subject": "SHP-123457",
  "data": {
    "shipmentId": "SHP-123457",
    "orderId": "ORD-789013",
    "failureReason": "ALL_PATHS_CONSTRAINED",
    "attemptedPaths": [
      {
        "pathId": "PATH-SINGLES-01",
        "rejectionReason": "MULTI_ITEM_ORDER"
      },
      {
        "pathId": "PATH-AFE-01",
        "rejectionReason": "UTILIZATION_CRITICAL"
      },
      {
        "pathId": "PATH-BATCH-01",
        "rejectionReason": "NO_WAVE_SCHEDULED"
      }
    ],
    "shipmentProperties": {
      "itemCount": 5,
      "totalWeight": 8.5,
      "hasHazmat": false,
      "requiresGiftWrap": true,
      "hasOversizedItem": false
    },
    "recommendedAction": "WAIT_FOR_CAPACITY",
    "retryAfter": "PT5M",
    "failedAt": "2025-01-20T10:05:00Z"
  }
}

ShipmentReroutedEvent

Description: Published when an in-flight shipment is rerouted to a different path.

Topic: process-path.routing.v1.events

Source: process-path-routing-service/src/main/java/com/paklog/wms/processpath/routing/domain/event/ShipmentReroutedEvent.java

Trigger: Dynamic rerouting due to bottleneck, SLA risk, or equipment failure

Consumers: Physical Tracking, Task Execution, Analytics

{
  "specversion": "1.0",
  "type": "com.paklog.processpath.routing.shipment-rerouted.v1",
  "source": "/process-path-routing-service",
  "id": "evt-1a2b3c4d-5e6f-7890-abcd-ef0123456789",
  "time": "2025-01-20T10:10:00.000Z",
  "datacontenttype": "application/json",
  "subject": "SHP-123458",
  "data": {
    "shipmentId": "SHP-123458",
    "orderId": "ORD-789014",
    "originalPath": "AFE",
    "originalPathId": "PATH-AFE-01",
    "newPath": "SINGLES",
    "newPathId": "PATH-SINGLES-02",
    "rerouteReason": "BOTTLENECK",
    "reroutePoint": "MAIN_SORTER",
    "physicalLocation": "CONV-ZONE-A-12",
    "estimatedDelayMinutes": 3,
    "newEstimatedCycleTime": "PT8M",
    "reroutedAt": "2025-01-20T10:10:00Z"
  }
}

Orchestration Events

PathCapacityChangedEvent

Description: Published when a path’s capacity state changes.

Topic: process-path.orchestration.v1.events

Source: process-path-orchestration-service/src/main/java/com/paklog/wms/processpath/orchestration/domain/event/PathCapacityChangedEvent.java

Trigger: Utilization crosses threshold (80%, 90%, 95%) or returns to normal

Consumers: WES Orchestration, Wave Planning, Operations Dashboard

{
  "specversion": "1.0",
  "type": "com.paklog.processpath.orchestration.path-capacity-changed.v1",
  "source": "/process-path-orchestration-service",
  "id": "evt-2b3c4d5e-6f78-90ab-cdef-123456789012",
  "time": "2025-01-20T10:15:00.000Z",
  "datacontenttype": "application/json",
  "subject": "PATH-AFE-01",
  "data": {
    "pathId": "PATH-AFE-01",
    "pathType": "AFE",
    "previousState": "NORMAL",
    "currentState": "CONSTRAINED",
    "utilizationPercent": 85.5,
    "currentThroughput": 2295,
    "maxThroughput": 2700,
    "activeStations": 8,
    "maxStations": 10,
    "queueDepth": 45,
    "projectedRecoveryTime": "PT20M",
    "stateChangedAt": "2025-01-20T10:15:00Z"
  }
}

Capacity States:

State	Utilization	Description
`NORMAL`	0-79%	Normal operations, accepting all work
`CONSTRAINED`	80-94%	Approaching limits, begin shifting work
`CRITICAL`	95-100%	At capacity, stop routing new work

stateDiagram-v2
    [*] --> NORMAL

    NORMAL --> CONSTRAINED: utilization >= 80%
    CONSTRAINED --> CRITICAL: utilization >= 95%
    CONSTRAINED --> NORMAL: utilization < 80%
    CRITICAL --> CONSTRAINED: utilization < 95%
    CRITICAL --> NORMAL: utilization < 80%

    NORMAL: ✅ Accepting all work
    NORMAL: Utilization 0-79%

    CONSTRAINED: ⚠️ Begin shifting work
    CONSTRAINED: Utilization 80-94%

    CRITICAL: 🛑 Stop routing new work
    CRITICAL: Utilization 95-100%

WorkloadRebalanceTriggeredEvent

Description: Published when workload rebalancing is initiated.

Topic: process-path.orchestration.v1.events

Source: process-path-orchestration-service/src/main/java/com/paklog/wms/processpath/orchestration/domain/event/WorkloadRebalanceTriggeredEvent.java

Trigger: Significant utilization imbalance detected or SLA risk identified

Consumers: All Path Operations, Analytics, Operations Dashboard

{
  "specversion": "1.0",
  "type": "com.paklog.processpath.orchestration.workload-rebalance-triggered.v1",
  "source": "/process-path-orchestration-service",
  "id": "evt-3c4d5e6f-7890-abcd-ef12-345678901234",
  "time": "2025-01-20T10:20:00.000Z",
  "datacontenttype": "application/json",
  "data": {
    "rebalanceId": "REB-2025-01-20-001",
    "triggerReason": "UTILIZATION_IMBALANCE",
    "affectedPaths": [
      {
        "pathId": "PATH-AFE-01",
        "fromUtilization": 95,
        "targetUtilization": 80,
        "shipmentsToMove": 75
      },
      {
        "pathId": "PATH-SINGLES-01",
        "fromUtilization": 50,
        "targetUtilization": 65,
        "shipmentsToReceive": 50
      },
      {
        "pathId": "PATH-BATCH-01",
        "fromUtilization": 40,
        "targetUtilization": 55,
        "shipmentsToReceive": 25
      }
    ],
    "totalShipmentsToReassign": 75,
    "estimatedCompletionTime": "PT10M",
    "triggeredAt": "2025-01-20T10:20:00Z"
  }
}

SurgeDetectedEvent

Description: Published when volume surge is detected.

Topic: process-path.orchestration.v1.events

Source: process-path-orchestration-service/src/main/java/com/paklog/wms/processpath/orchestration/domain/event/SurgeDetectedEvent.java

Trigger: Incoming volume exceeds forecast threshold

Consumers: Workload Planning, Operations, Management

{
  "specversion": "1.0",
  "type": "com.paklog.processpath.orchestration.surge-detected.v1",
  "source": "/process-path-orchestration-service",
  "id": "evt-4d5e6f78-90ab-cdef-1234-567890123456",
  "time": "2025-01-20T10:25:00.000Z",
  "datacontenttype": "application/json",
  "data": {
    "surgeId": "SURGE-2025-01-20-001",
    "surgeLevel": "LEVEL_2",
    "volumePercentOfForecast": 135,
    "currentVolumePerHour": 2700,
    "forecastedVolumePerHour": 2000,
    "affectedPaths": ["AFE", "SINGLES"],
    "recommendedActions": [
      "ACTIVATE_ADDITIONAL_STATIONS",
      "EXTEND_SHIFTS",
      "RELAX_PATH_PREFERENCES"
    ],
    "estimatedDuration": "PT2H",
    "detectedAt": "2025-01-20T10:25:00Z"
  }
}

Surge Levels:

Level	Volume %	Actions
`LEVEL_1`	100-120%	Monitor, prepare contingencies
`LEVEL_2`	120-150%	Activate additional stations, extend shifts
`LEVEL_3`	>150%	All hands, activate all reserves, mandatory overtime

stateDiagram-v2
    [*] --> NORMAL_VOLUME

    NORMAL_VOLUME --> LEVEL_1: volume > 100%
    LEVEL_1 --> LEVEL_2: volume > 120%
    LEVEL_2 --> LEVEL_3: volume > 150%
    LEVEL_3 --> LEVEL_2: volume <= 150%
    LEVEL_2 --> LEVEL_1: volume <= 120%
    LEVEL_1 --> NORMAL_VOLUME: volume <= 100%

    NORMAL_VOLUME: ✅ Standard Operations
    NORMAL_VOLUME: Volume <= 100% of forecast

    LEVEL_1: 🟡 Monitor
    LEVEL_1: 100-120% of forecast
    LEVEL_1: Prepare contingencies

    LEVEL_2: 🟠 Activate Resources
    LEVEL_2: 120-150% of forecast
    LEVEL_2: Additional stations & shifts

    LEVEL_3: 🔴 All Hands
    LEVEL_3: > 150% of forecast
    LEVEL_3: Mandatory overtime

SLA Events

SLAPriorityEscalatedEvent

Description: Published when a shipment’s SLA priority changes.

Topic: process-path.orchestration.v1.events

Source: process-path-orchestration-service/src/main/java/com/paklog/wms/processpath/orchestration/domain/event/SLAPriorityEscalatedEvent.java

Trigger: Time to cutoff crosses priority threshold

Consumers: Pack & Ship, Task Execution, Operations

{
  "specversion": "1.0",
  "type": "com.paklog.processpath.orchestration.sla-priority-escalated.v1",
  "source": "/process-path-orchestration-service",
  "id": "evt-5e6f7890-abcd-ef12-3456-789012345678",
  "time": "2025-01-20T10:30:00.000Z",
  "datacontenttype": "application/json",
  "subject": "SHP-123459",
  "data": {
    "shipmentId": "SHP-123459",
    "orderId": "ORD-789015",
    "previousPriority": "GREEN",
    "newPriority": "YELLOW",
    "timeToSLACutoff": "PT45M",
    "carrierCutoffTime": "2025-01-20T11:15:00Z",
    "currentStage": "AFE_INDUCT",
    "currentPath": "AFE",
    "expeditedRouting": false,
    "escalatedAt": "2025-01-20T10:30:00Z"
  }
}

Priority Thresholds:

Priority	Time to Cutoff	Actions
`GREEN`	> 60 minutes	Standard processing
`YELLOW`	30-60 minutes	Prefer faster paths, monitor closely
`RED`	< 30 minutes	Override routing, expedite, escalate

stateDiagram-v2
    [*] --> GREEN

    GREEN --> YELLOW: time_to_cutoff <= 60min
    YELLOW --> RED: time_to_cutoff <= 30min
    RED --> BREACH: time_to_cutoff <= 15min & incomplete

    GREEN: ✅ Standard Processing
    GREEN: Time > 60 min

    YELLOW: ⚠️ Monitor Closely
    YELLOW: Time 30-60 min
    YELLOW: Prefer faster paths

    RED: 🔴 Expedite & Escalate
    RED: Time < 30 min
    RED: Override routing

    BREACH: 💥 Emergency Intervention
    BREACH: Time < 15 min
    BREACH: Shipment not complete

SLABreachImminentEvent

Description: Published when SLA breach is imminent (< 15 min remaining).

Topic: process-path.orchestration.v1.events

Source: process-path-orchestration-service/src/main/java/com/paklog/wms/processpath/orchestration/domain/event/SLABreachImminentEvent.java

Trigger: Time to cutoff < 15 minutes and shipment not yet complete

Consumers: Operations Alert, Management, Customer Service

{
  "specversion": "1.0",
  "type": "com.paklog.processpath.orchestration.sla-breach-imminent.v1",
  "source": "/process-path-orchestration-service",
  "id": "evt-6f789012-cdef-3456-7890-123456789abc",
  "time": "2025-01-20T11:00:00.000Z",
  "datacontenttype": "application/json",
  "subject": "SHP-123460",
  "data": {
    "shipmentId": "SHP-123460",
    "orderId": "ORD-789016",
    "timeToSLACutoff": "PT12M",
    "carrierCutoffTime": "2025-01-20T11:12:00Z",
    "currentStage": "PACK",
    "currentPath": "SINGLES",
    "requiredAction": "EMERGENCY_EXPEDITE",
    "escalationLevel": "OPERATIONS",
    "estimatedCompletionTime": "PT8M",
    "canMeetSLA": true,
    "detectedAt": "2025-01-20T11:00:00Z"
  }
}

Buffer State Events

WallCapacityChangedEvent

Description: Published when AFE rebin wall capacity changes significantly.

Topic: process-path.afe.v1.events

Source: afe-path-service/src/main/java/com/paklog/wms/processpath/afe/domain/event/WallCapacityChangedEvent.java

Trigger: Wall utilization crosses threshold or trend changes

Consumers: AFE Operations, Path Routing, Analytics

{
  "specversion": "1.0",
  "type": "com.paklog.processpath.afe.wall-capacity-changed.v1",
  "source": "/afe-path-service",
  "id": "evt-7890abcd-ef12-3456-7890-abcdef123456",
  "time": "2025-01-20T10:35:00.000Z",
  "datacontenttype": "application/json",
  "subject": "WALL-AFE-01",
  "data": {
    "wallId": "WALL-AFE-01",
    "wallType": "SORTABLE_AFE",
    "totalChutes": 166,
    "availableChutes": 45,
    "occupiedChutes": 121,
    "utilizationPercent": 72.9,
    "previousState": "NORMAL",
    "currentState": "NORMAL",
    "trend": "RISING",
    "avgChuteOccupancyMinutes": 8.5,
    "projectedFullTime": "PT25M",
    "changedAt": "2025-01-20T10:35:00Z"
  }
}

TrayCirculationImbalanceEvent

Description: Published when AFE tray circulation becomes imbalanced.

Topic: process-path.afe.v1.events

Source: afe-path-service/src/main/java/com/paklog/wms/processpath/afe/domain/event/TrayCirculationImbalanceEvent.java

Trigger: Tray buffer level outside normal range (12-20 trays)

Consumers: AFE Operations, Labor Management, Operations Alert

{
  "specversion": "1.0",
  "type": "com.paklog.processpath.afe.tray-circulation-imbalance.v1",
  "source": "/afe-path-service",
  "id": "evt-890abcde-f123-4567-890a-bcdef1234567",
  "time": "2025-01-20T10:40:00.000Z",
  "datacontenttype": "application/json",
  "subject": "AFE-LOOP-01",
  "data": {
    "loopId": "AFE-LOOP-01",
    "imbalanceType": "STARVATION",
    "currentBufferLevel": 3,
    "normalRange": {
      "min": 12,
      "max": 20
    },
    "inductStationId": "INDUCT-01",
    "rebinStationId": "REBIN-01",
    "inductRate": 180,
    "rebinRate": 150,
    "severity": "WARNING",
    "recommendedAction": "ADD_REBIN_LABOR",
    "estimatedRecoveryTime": "PT10M",
    "detectedAt": "2025-01-20T10:40:00Z"
  }
}

Imbalance Types:

Type	Condition	Cause
`STARVATION`	Buffer < min	Rebin slower than induct
`BACKLOG`	Buffer > max	Induct faster than rebin

DischargeJamDetectedEvent

Description: Published when a discharge lane jam is detected.

Topic: process-path.afe.v1.events

Source: afe-path-service/src/main/java/com/paklog/wms/processpath/afe/domain/event/DischargeJamDetectedEvent.java

Trigger: Photo-eye blockage detected for > 5 seconds

Consumers: AFE Operations, Maintenance, Operations Alert

{
  "specversion": "1.0",
  "type": "com.paklog.processpath.afe.discharge-jam-detected.v1",
  "source": "/afe-path-service",
  "id": "evt-90abcdef-1234-5678-90ab-cdef12345678",
  "time": "2025-01-20T10:45:00.000Z",
  "datacontenttype": "application/json",
  "subject": "LANE-AFE-01-DISCHARGE-03",
  "data": {
    "laneId": "LANE-AFE-01-DISCHARGE-03",
    "wallId": "WALL-AFE-01",
    "jamDurationSeconds": 15,
    "blockedTrays": 6,
    "affectedShipments": ["SHP-123461", "SHP-123462", "SHP-123463"],
    "upstreamImpact": "SORTER_SLOWDOWN",
    "severity": "CRITICAL",
    "requiresManualClear": true,
    "detectedAt": "2025-01-20T10:45:00Z"
  }
}

SLAM Events

SLAMCompletedEvent

Description: Published when SLAM operations (Scan, Label, Apply, Manifest) are completed for a shipment.

Topic: wes.slam.v1.events

Source: slam-operations-service/src/main/java/com/paklog/wms/slam/domain/event/SLAMCompletedEvent.java

Trigger: Shipment successfully manifested and ready for carrier pickup

Consumers: Shipment Transportation, Physical Tracking, Order Management

{
  "specversion": "1.0",
  "type": "com.paklog.wes.slam.completed.v1",
  "source": "/slam-operations-service",
  "id": "evt-slam-abcdef12-3456-7890-abcd-ef1234567890",
  "time": "2025-01-20T11:30:00.000Z",
  "datacontenttype": "application/json",
  "subject": "SHP-123456",
  "data": {
    "shipmentId": "SHP-123456",
    "orderId": "ORD-789012",
    "trackingNumber": "1Z999AA10123456784",
    "carrier": "UPS",
    "serviceLevel": "GROUND",
    "manifestId": "MFT-2025-01-20-001",
    "loadingDockId": "DOCK-03",
    "manifestedAt": "2025-01-20T11:28:00Z",
    "carrierPickupTime": "2025-01-20T14:00:00Z",
    "packageWeight": 3.5,
    "packageDimensions": "12x8x6",
    "labelUrl": "https://labels.paklog.com/1Z999AA10123456784.pdf",
    "completedAt": "2025-01-20T11:30:00Z"
  }
}

Schema:

Field	Type	Required	Description
`shipmentId`	string	Yes	Unique shipment identifier
`orderId`	string	Yes	Parent order identifier
`trackingNumber`	string	Yes	Carrier tracking number
`carrier`	string	Yes	Carrier code (UPS, FEDEX, USPS, etc.)
`serviceLevel`	enum	Yes	GROUND, EXPRESS, PRIORITY
`manifestId`	string	Yes	Manifest batch identifier
`loadingDockId`	string	Yes	Assigned loading dock
`manifestedAt`	datetime	Yes	Manifest creation time
`carrierPickupTime`	datetime	Yes	Expected carrier pickup
`packageWeight`	number	Yes	Package weight in lbs
`packageDimensions`	string	Yes	LxWxH format in inches
`labelUrl`	string	Yes	URL to shipping label PDF
`completedAt`	datetime	Yes	SLAM completion timestamp

Event Versioning

All events follow semantic versioning in the type field:

v1 - Initial version
Backward compatible changes increment minor version
Breaking changes create new major version with migration period

Deprecation Policy:

Old versions supported for 6 months after new version release
Consumers notified 3 months before deprecation
Event schema registry enforces compatibility