Skip to content

Replay Engine

Table of Contents

Overview

The Replay Engine re-runs the supply + allocation planning pipeline iteratively over a configurable historical horizon. At each iteration, the engine advances the "planning date" by one step (daily or weekly), receives supply orders that have arrived by that date into on-hand inventory, and runs the full supply and allocation engines again.

This allows you to answer questions like:

  • What would our fill rate have been if we had used this planning configuration over the past year?
  • How would stock have evolved week by week under the current policy?
  • Where did backorders accumulate, and when did they clear?

The replay uses the same engines as the live planning process — not a simplified simulation — so the results accurately reflect what the system would have produced at each point in time.

Where to find it

The Replay screen is accessible from the 🔄 Replay link in the sidebar's Action group.

Core Concepts

Replay Run

A replay run defines the scope of a replay:

Parameter Description
Source pipeline The pipeline whose configuration (supply scenario, allocation parameters, forecast) will be replayed
Start date The first planning date — the beginning of the historical horizon
End date The last planning date — the end of the historical horizon
Granularity Step size: weekly (default) or daily

Each replay run creates its own replay pipeline (a copy of the source pipeline's configuration). The source pipeline's data is never modified.

Iteration

Each iteration is one complete planning cycle at a specific planning date:

  1. Receive supply: Orders with arrival date ≤ planning date are "received" — their quantity is added to on-hand inventory
  2. Run supply planning: The full supply engine runs, generating new replenishment orders
  3. Run allocation: The allocation engine distributes available supply across demands
  4. Record metrics: Fill rate, total stock, and shortage are captured

Each iteration writes its output with archive_date = planning_date, so results are naturally historized and queryable across iterations.

Stock Evolution

Between iterations, the on-hand inventory evolves realistically:

  • Supply orders from previous iterations that arrive by the current planning date are received into stock
  • Demand that was allocated (filled) reduces available inventory
  • Unfulfilled demand (backorders) carries forward

Creating a Replay Run

  1. Navigate to the Replay screen (🔄 in the sidebar)
  2. Click + New Replay
  3. Fill in the form:
Field Required Description
Name Yes A descriptive name for this replay run
Description No Optional details
Source Pipeline Yes The pipeline to replay
Start Date Yes First iteration date (e.g. 2025-06-01)
End Date Yes Last iteration date (e.g. 2026-06-01)
Granularity Yes Weekly (default) or Daily
  1. Click Create

New Replay Run form

The system creates a new replay pipeline (marked with is_replay = TRUE) that clones the source pipeline's supply and allocation scenario configuration. The source pipeline is not modified.

Running a Replay

After creating a replay run, its status is pending. To start it:

  1. Click the Start button in the runs table
  2. The status changes to running and the progress bar begins advancing

The replay runs in the background — you can navigate away and return later. The progress bar shows the current iteration out of the total.

Runtime estimate

Each iteration takes approximately 1 minute (supply + allocation). A 52-week replay runs in about 1 hour. A 365-day daily replay takes approximately 6 hours.

Replay Dashboard

Replay Engine dashboard with the list of replay runs

When you select a running or completed replay run, the dashboard shows three panels:

Stock Over Time

A line chart showing projected inventory across all iterations. Each line represents one item-site combination, with the X-axis showing planning dates and the Y-axis showing stock quantity.

Use this to identify:

  • Periods of low stock or stockouts
  • Inventory build-up patterns
  • Seasonal stock patterns under the replayed policy

Fill Rate & Shortfall Over Time

A combined chart with:

  • Fill rate % (left Y-axis, line chart): the percentage of demand that was allocated
  • Shortfall qty (right Y-axis, bar chart): the total unfulfilled quantity

Use this to identify:

  • Weeks where allocation was insufficient
  • Trends in service level
  • The impact of lead times on fill rate

Iteration Details Table

A row-by-row breakdown of every iteration:

Column Description
# Iteration number
Planning Date The date this iteration simulated
Status Completed, failed, or skipped
Fill Rate Percentage of demand allocated
Total Stock Sum of projected on-hand across all item-sites
Shortage Total shortage quantity
Duration Wall-clock time for this iteration

Stock Over Time

The stock evolution chart queries PIPE_supply_inventory_projection from ClickHouse, grouped by archive_date (one per iteration). Each series is an item-site combination.

The chart supports:

  • Hovering to see exact values
  • Zooming by clicking and dragging
  • Double-clicking to reset the zoom

Fill Rate Over Time

Fill rate is calculated per iteration as:

fill_rate = total_allocated_qty / total_requested_qty

where:

  • total_allocated_qty comes from PIPE_allocation_results
  • total_requested_qty comes from PIPE_allocation_unfulfilled

Both tables are partitioned by (pipeline_id, archive_date), so each iteration's fill rate is computed independently.

Iteration Details

The iteration table reads from the replay_iteration PostgreSQL table. Each row contains a metrics JSONB column with the following structure:

{
  "total_stock": 15420.0,
  "total_shortage": 320.5,
  "avg_stock": 128.5,
  "total_allocated": 15100.0,
  "total_requested": 15420.0,
  "total_shortfall": 320.0,
  "fill_rate": 0.9792
}

Cancelling and Deleting

Cancelling a Running Replay

Click Cancel on a running replay. The engine checks for cancellation before each iteration, so the current iteration will complete before the replay stops. Partial results (iterations that already completed) are preserved.

Deleting a Replay Run

Click Delete on a completed, failed, or cancelled replay. This removes:

  • The replay run metadata
  • All iteration records
  • The replay pipeline

Deletion is permanent

Deleted replay data cannot be recovered. The source pipeline is never affected by deletion.

Limitations and Performance

Aspect Detail
One replay at a time Only one replay can run per source pipeline concurrently. Starting a second replay on the same pipeline will fail.
Engine runtime Each iteration runs the full supply + allocation engine (~1 min). 52 weekly iterations ≈ 1 hour.
Forecast reuse The replay reuses the source pipeline's forecast. It does not re-run the forecast step at each iteration.
On-hand backup The engine backs up master.on_hand before starting and restores it on failure. If the API process crashes mid-replay, on_hand may be in an intermediate state.
ClickHouse partitions Each iteration writes a new partition to PIPE_supply_inventory_projection, PIPE_allocation_results, and PIPE_allocation_unfulfilled. For daily granularity over a year, this means 365 partitions per table.
No demand simulation The replay uses actual historical demand and the source pipeline's forecast. It does not simulate alternative demand scenarios.