Wave Planning Service Integration

Overview

Attribute	Value
Context	Wave Planning Service
Pattern	Published Language
Direction	Inbound (Wave Planning → Process Path)
Protocol	Apache Kafka
Topics	`wave-planning.waves.*`

Integration Summary

Wave Planning Service creates and releases waves of orders for batch processing. Process Path consumes wave events and routes the contained shipments to the Batch/Flow path. Wave Planning owns the wave composition logic, and Process Path follows their published contract.

┌─────────────────────────┐         ┌─────────────────────────┐
│    WAVE PLANNING        │         │      PROCESS PATH       │
│                         │         │                         │
│  • Wave creation        │  ─────► │  • Batch/Flow routing   │
│  • Order clustering     │  Event  │  • Wave execution       │
│  • Carrier optimization │         │  • Capacity allocation  │
│  • Zone balancing       │         │                         │
└─────────────────────────┘         └─────────────────────────┘

Events Consumed

WaveReleasedEvent

Purpose: Route wave shipments to Batch/Flow path

Topic: wave-planning.waves.released

Action: Bulk route shipments to Batch/Flow, trigger batch picking

{
  "specversion": "1.0",
  "type": "com.paklog.wave.released.v1",
  "source": "/wave-planning-service",
  "id": "evt-wave-123456",
  "time": "2025-01-20T10:05:00.000Z",
  "subject": "WAVE-2025-01-20-001",
  "data": {
    "waveId": "WAVE-2025-01-20-001",
    "waveName": "UPS_GROUND_CUTOFF_1400",
    "waveType": "CARRIER_CUTOFF",
    "orderCount": 50,
    "itemCount": 175,
    "shipmentIds": [
      "SHP-101", "SHP-102", "SHP-103"
    ],
    "carrierCutoff": "2025-01-20T14:00:00Z",
    "targetCarrier": "UPS",
    "targetPath": "BATCH_FLOW",
    "zoneDistribution": {
      "ZONE-A": 20,
      "ZONE-B": 18,
      "ZONE-C": 12
    },
    "estimatedPickTime": "PT45M",
    "estimatedPackTime": "PT30M",
    "priority": "NORMAL",
    "releasedAt": "2025-01-20T10:05:00Z"
  }
}

WaveCancelledEvent

Purpose: Cancel routing for wave shipments

Topic: wave-planning.waves.cancelled

{
  "type": "com.paklog.wave.cancelled.v1",
  "data": {
    "waveId": "WAVE-2025-01-20-001",
    "cancellationReason": "CARRIER_DELAY",
    "affectedShipments": ["SHP-101", "SHP-102", "SHP-103"],
    "rescheduledTo": "WAVE-2025-01-20-002",
    "cancelledAt": "2025-01-20T10:10:00Z"
  }
}

WaveModifiedEvent

Purpose: Update wave composition after release

Topic: wave-planning.waves.modified

{
  "type": "com.paklog.wave.modified.v1",
  "data": {
    "waveId": "WAVE-2025-01-20-001",
    "modifications": {
      "addedShipments": ["SHP-104"],
      "removedShipments": ["SHP-101"],
      "newOrderCount": 50,
      "newItemCount": 180
    },
    "modificationReason": "ORDER_CANCELLATION",
    "modifiedAt": "2025-01-20T10:15:00Z"
  }
}

Wave Types

Wave Planning creates different wave types based on optimization goals:

Carrier Cutoff Wave

Optimized for meeting carrier pickup deadlines.

{
  "waveType": "CARRIER_CUTOFF",
  "targetCarrier": "UPS",
  "carrierCutoff": "2025-01-20T14:00:00Z",
  "priority": "HIGH"
}

Process Path Action: Prioritize routing, expedite if needed

Zone-Based Wave

Optimized for pick path efficiency.

{
  "waveType": "ZONE_BASED",
  "primaryZone": "ZONE-A",
  "zoneDistribution": {
    "ZONE-A": 80,
    "ZONE-B": 15,
    "ZONE-C": 5
  }
}

Process Path Action: Route to path aligned with zone

Priority Wave

Optimized for high-value or expedited orders.

{
  "waveType": "PRIORITY",
  "priorityReason": "SAME_DAY_DELIVERY",
  "slaCutoff": "2025-01-20T12:00:00Z"
}

Process Path Action: Override normal routing, expedite

Processing Logic

On WaveReleasedEvent

1. Validate wave event
2. Check Batch/Flow path capacity
3. If capacity available:
   - Bulk assign all shipments to Batch/Flow
   - Publish ShipmentRoutedToPath for each
   - Update wave tracking
4. If capacity constrained:
   - Split wave across available paths
   - Notify Wave Planning of split
5. Monitor wave progress
6. Report completion to Wave Planning

Wave Capacity Check

Before accepting a wave, Process Path checks:

{
  "waveId": "WAVE-2025-01-20-001",
  "capacityCheck": {
    "requestedShipments": 50,
    "batchFlowCapacity": 60,
    "batchFlowUtilization": 45,
    "canAccept": true,
    "alternativePaths": []
  }
}

Wave-to-Path Mapping

Wave Characteristic	Preferred Path	Reasoning
High order count (>20)	BATCH_FLOW	Efficient batch picking
Zone-concentrated	BATCH_FLOW	Optimized pick paths
Mixed zones	BATCH_FLOW or AFE	Depends on item count
Priority/Same-day	SINGLES or AFE	Faster cycle time

Wave Progress Tracking

Process Path tracks wave progress and reports to Wave Planning:

{
  "type": "com.paklog.processpath.wave.progress.v1",
  "data": {
    "waveId": "WAVE-2025-01-20-001",
    "status": "IN_PROGRESS",
    "totalShipments": 50,
    "pickedShipments": 35,
    "packedShipments": 20,
    "shippedShipments": 15,
    "progress": {
      "pickProgress": 70,
      "packProgress": 40,
      "shipProgress": 30
    },
    "estimatedCompletion": "2025-01-20T11:30:00Z",
    "onTrackForCutoff": true
  }
}

Feedback to Wave Planning

Process Path provides feedback that influences future wave creation:

Capacity Feedback

{
  "type": "com.paklog.processpath.wave.capacity.feedback.v1",
  "data": {
    "pathType": "BATCH_FLOW",
    "currentCapacity": 60,
    "recommendedWaveSize": 40,
    "activeWaves": 2,
    "nextAvailableSlot": "2025-01-20T10:30:00Z"
  }
}

Performance Feedback

{
  "type": "com.paklog.processpath.wave.performance.feedback.v1",
  "data": {
    "waveId": "WAVE-2025-01-20-001",
    "actualPickTime": "PT50M",
    "estimatedPickTime": "PT45M",
    "variance": "PT5M",
    "bottlenecks": ["ZONE-B_CONGESTION"],
    "recommendations": ["REDUCE_ZONE_B_CONCENTRATION"]
  }
}

Error Handling

Error	Action
Wave too large	Request split from Wave Planning
Batch/Flow unavailable	Route to AFE as fallback
Carrier cutoff at risk	Escalate priority, notify WES
Wave shipment short	Report exception, continue

Performance Metrics

Metric	Target	Description
Wave acceptance rate	> 99%	Waves accepted without split
Wave completion rate	> 98%	Waves completed before cutoff
Pick time variance	< 10%	Actual vs estimated pick time
Pack time variance	< 15%	Actual vs estimated pack time