A zone-level marketplace control system that detects supply-demand imbalance (stress) and progressively tightens search radius, listing distance, and driving-time caps to stabilize service quality during peak demand. Includes Butler (grocery) shutdown logic at extreme stress, markup pricing hooks, and a customer-facing delivery Choice tier design.
Industry: On-Demand Food Delivery (MENA Region)
Role: Senior Performance Analyst | Designed the stress framework, threshold calibration, and policy logic
Tools: Python, OSRM, Pandas, NumPy
Context: Designed for zone-level demand control in a large on-demand delivery marketplace in Saudi Arabia. This repository reconstructs the calibration and policy logic from production-context work.
On-demand delivery marketplaces degrade silently during demand spikes. When order volume overwhelms courier supply in a zone, the platform keeps behaving as if supply is normal: showing restaurants that are too far away, accepting orders that will have terrible ETAs, and routing couriers on trips that make the zone even more stressed.
The symptoms are visible to customers but invisible to the system: long wait times, high cancellation rates, poor ETAs, and degraded trust. The platform had no mechanism to detect stress at the zone level or to adjust its behavior in response.
The core insight was that stress is not binary (healthy vs broken). It's a gradient, and the system's response should be proportional. A zone under mild stress needs a gentle tightening of search radius. A zone under extreme stress needs aggressive restrictions and shutdown of low-priority services.
The system treats real-time stress as the primary input signal for zone-level behavior. Stress is computed from courier supply-demand metrics and triggers progressive marketplace restrictions as it crosses calibrated thresholds.
The key design decision was to make the response ladder-shaped: each stress level activates a tighter set of constraints, and the system climbs the ladder as conditions worsen.
| Stress Level | System Response |
|---|---|
| Normal | No restrictions, full search radius and listing distance |
| Moderate | Mild shrink of search and listing caps |
| High | Aggressive shrink, tighter driving-time limits |
| Extreme | Butler (grocery) shutdown, maximum shrink |
Thresholds are not set manually. They are calibrated per zone from historical order and stress data using percentile-based cuts:
Search distance caps are derived from historical delivery distances at the 85th, 75th, 65th, 55th, and 45th percentiles. The P85 value becomes the base cap, and each subsequent threshold is stored as a progressive shrink level relative to that base. Each zone gets its own set of caps based on its actual delivery patterns.
Listing distance caps are set to 80% of the corresponding search caps. This ensures vendors are listed at shorter distances than the maximum search radius, preventing customers from seeing restaurants the system can't reliably serve.
Driving-time caps follow the same percentile logic applied to historical driving durations, converted to minutes. Like listing distance, listing driving-time caps are set to 80% of search driving-time caps.
Butler shutdown threshold is set at the 95th percentile of historical stress (not order distances) for each zone. This means Butler shuts down only under genuinely extreme supply-demand conditions.
Markup rows are placeholder hooks in this version. In a production context, these would be populated by the commercial team based on zone-level pricing policy. The current code writes two markup_price rows with default values as interface stubs.
For each zone, the system generates a parameter table with:
- 4 rows of
search_distance(progressive tightening) - 4 rows of
listing_distance(80% of search) - 4 rows of
search_driving_time(progressive tightening) - 4 rows of
listing_driving_time(80% of search driving time) - 1 row of
butler_threshold(95th percentile of stress) - 2 rows of
markup_price(placeholder hooks for commercial configuration)
At runtime, the policy engine takes the current zone stress level and the pre-computed threshold table, then outputs a complete zone policy decision:
decision = evaluate_zone_policy(zone_params, zone_id="Riyadh Central", current_stress=0.72)
# Returns:
# ZonePolicyDecision(
# zone_id='Riyadh Central',
# current_stress=0.72,
# shrink_level=3,
# search_distance=4535.0,
# listing_distance=3628.0,
# search_driving_time=15.0,
# listing_driving_time=12.0,
# butler_shutdown=False,
# markup_price=0.0,
# available_options=['Priority']
# )The decision encapsulates everything the platform needs: how far to search, what to list, whether to shut down Butler, what markup to apply, and what delivery options to show the customer.
Choice is a design layer built on top of demand control. The idea is to translate system constraints into visible customer options rather than hiding stress behind broken experiences. The current implementation is a policy prototype that maps shrink levels to available delivery tiers:
| Shrink Level | Available Options |
|---|---|
| 0-1 (low stress) | Priority, Standard, Saver |
| 2 (moderate stress) | Priority, Standard |
| 3+ (high stress) | Priority only |
| Butler shutdown | No options (service unavailable) |
This mapping demonstrates the design pattern. A production implementation would require frontend integration, A/B testing of tier presentation, and demand elasticity analysis to determine optimal tier pricing.
The system includes an OSRM enrichment pipeline (shared with the ETA model) that calibrates actual delivery times against ideal routing estimates. This feeds into the driving-time threshold calibration, ensuring caps are based on real-world conditions rather than theoretical shortest paths.
Sample zone parameters (Jeddah North):
| Stress Threshold | Search Distance (m) | Listing Distance (m) | Search Time (min) | Listing Time (min) |
|---|---|---|---|---|
| 0.132 | 5,500 | 4,400 | 18 | 14 |
| 0.215 | 4,975 | 3,980 | 16 | 13 |
| 0.285 | 4,535 | 3,628 | 15 | 12 |
| 0.406 | 3,765 | 3,012 | 13 | 10 |
As stress increases from 0.13 to 0.41, search distance shrinks from 5.5 km down to 3.8 km, and listing distance from 4.4 km to 3.0 km. This progressive tightening prevents the platform from accepting orders it can't reliably fulfill.
Butler shutdown threshold: 0.88 (95th percentile of historical stress for this zone)
Each zone has different delivery distance patterns. Jeddah North has shorter typical distances than Riyadh Central, which is why a single global threshold would either over-restrict one zone or under-restrict the other.
The sample_data/ directory contains anonymized order and stress data for two zones, and zone_params_sample.csv shows the generated output for those zones.
| Layer | Status |
|---|---|
| Zone threshold calibration logic (percentile caps, 0.8 listing factor, P95 Butler) | Real - grounded in original production code |
| Stress ladder design (progressive tightening by zone) | Real - core design framework from the project |
| OSRM enrichment and calibration approach | Real - shared pipeline with the ETA model |
| Runtime policy decisioning (stress to caps lookup) | Real - logic reconstructed from original design |
| CLI packaging and entry points | Reconstructed - added for portfolio usability |
| Sample data (orders, stress values) | Reconstructed - anonymized synthetic data matching real schema |
| Architecture diagrams | Reconstructed - created from system knowledge |
| Choice tier mapping | Simplified - demonstrates the design pattern, not the full frontend integration |
| Markup logic | Simplified - placeholder hooks, not the full commercial pricing curves |
| Production monitoring, dashboards, rollout configs | Not included - existed in production but not recoverable for this repo |
The threshold calibration was reviewed against historical operating patterns. The percentile-based approach produced intuitive tightening during stressed periods and looser caps during off-peak periods, which aligned with established operational behavior.
Key design choices:
- Thresholds are derived from historical percentiles, not arbitrary rules. Each zone's caps reflect its actual delivery geography and patterns.
- Listing caps are mechanically set to 80% of search caps, ensuring internal consistency.
- Butler shutdown at the 95th percentile means it triggers only during genuinely extreme conditions, avoiding false shutdowns during normal variability.
Assumptions:
- Historical stress patterns are representative of future stress. This holds for most days but breaks during holidays like Eid or Ramadan, where manual overrides would be needed.
- The supply-demand metric used as the stress signal accurately captures zone-level pressure. In practice, stress can also come from road closures, weather, or localized events that don't show up in the standard metric.
Known limitations:
- The system is reactive, not predictive. It responds to stress after it's detected, rather than anticipating it. By the time stress crosses a threshold, some damage to customer experience has already occurred.
- Threshold calibration is batch-based (runs on historical data). It doesn't adapt in real-time to changing zone characteristics like new restaurant openings or road construction.
- The Butler shutdown is binary (on/off). A more nuanced approach would gradually restrict Butler's search radius before fully shutting it down.
- Markup logic is a placeholder interface in this version. A production implementation would require demand elasticity modeling and commercial team input.
- The Choice tier mapping is a design prototype. Validating its customer impact would require A/B testing and frontend integration work not captured here.
What I would test next:
- Predictive stress forecasting: use historical stress patterns (hour x day-of-week x zone) to anticipate stress 15-30 minutes ahead and pre-tighten before degradation occurs.
- Continuous threshold adaptation instead of batch calibration, with exponential decay weighting similar to the ETA model's recency approach.
- Demand elasticity modeling for markup: how does a delivery fee increase affect order volume at different stress levels?
- Graduated Butler restriction: shrink Butler's search radius progressively before full shutdown, similar to how food delivery search radius is handled.
-
Proportional response beats binary switches. The ladder approach (progressive tightening) handles the majority of stress situations with minimal customer impact. Most stress situations are better handled by progressive tightening than by binary shutdowns.
-
Zone-level calibration is essential. A 5 km search radius makes sense in suburban Riyadh but is excessive in dense Jeddah neighborhoods. Using per-zone historical percentiles instead of global defaults meant each zone got appropriate thresholds for its geography.
-
Listing caps must be tighter than search caps. If listing distance equals search distance, customers see restaurants at the edge of what the system can serve, leading to poor ETAs and cancellations. The 80% factor provides a buffer zone.
-
Shared infrastructure compounds value. The OSRM enrichment pipeline built for demand control was directly reused in the ETA prediction model. Investing in the calibration infrastructure once paid off across multiple systems.
README.md
src/
threshold_builder.py # Zone threshold generation from historical data
dc_policy.py # Runtime policy engine (shrink, Butler, markup, Choice)
osrm_enrich.py # OSRM route enrichment and calibration tables
__init__.py
tests/
test_policy.py # Policy engine edge case tests
main.py # CLI entry point for threshold building and policy simulation
config/
dc_config.yaml # Configurable thresholds, percentiles, and caps
sample_data/
orders_sample.csv # Sample historical orders (anonymized)
stress_sample.csv # Sample stress data (anonymized)
zone_params_sample.csv # Sample generated zone parameters
notebooks/
methodology_walkthrough.ipynb # Step-by-step methodology explanation
diagrams/
architecture.png # System architecture diagram
requirements.txt
.gitignore
pip install -r requirements.txt
# Generate zone thresholds from historical data
python main.py build-thresholds \
--orders sample_data/orders_sample.csv \
--stress sample_data/stress_sample.csv \
--out outputs/zone_params.csv
# Simulate a policy decision for a zone at a given stress level
python main.py simulate-policy \
--zone-params sample_data/zone_params_sample.csv \
--zone-id "Jeddah North" \
--current-stress 0.65Note: This repository contains the system design, threshold calibration logic, and policy engine. The OSRM enrichment module requires a local OSRM server. Zone names and stress values in sample data are anonymized.