Event-Driven Restock Engine (EDRE) 📦⚡

An automated, high-performance data pipeline designed to transform raw e-commerce sales exports (like Shopify) into highly accurate, statistically-backed inventory restock plans for recurring pop-up events.

🎯 The Business Problem

Managing inventory for project-based or pop-up events often relies on manual spreadsheet manipulation, leading to human error, stockouts of top sellers, or overstocking of slow movers.

EDRE solves this by replacing manual calculations with a robust ETL pipeline and a statistical forecasting engine. It calculates historical run rates, factors in demand volatility (Safety Stock), and generates a production-ready Excel action plan.

✨ Core Features

• Automated Ingestion & Cleaning: Reads raw sales logs, automatically filtering out fully refunded items to calculate true net sales.
• Statistical Forecasting Engine: Goes beyond simple averages. It calculates the standard deviation of sales per SKU across past events and applies a Z-Score (95% service level) to determine optimal safety stock.
• Actionable BI Deliverables: Automatically generates a fully formatted .xlsx report with conditional formatting (Color-coded alerts for stockouts and restock targets).
• Zero-Dependency Data Mocking: Includes a synthetic data generator to simulate Shopify exports for immediate testing.

📊 The Math Behind the Engine

The engine uses a Safety Stock formula to handle demand uncertainty:

Target Stock = Average Sales + (Standard Deviation * 1.64)

The Z-Score of 1.64 ensures a 95% Service Level, meaning the inventory plan is designed to cover demand fluctuations in 95% of cases based on historical variance.

🛠️ Tech Stack

• Python 3.12
• Polars: Chosen over Pandas for its strict typing, memory efficiency, and blazingly fast execution speed.
• XlsxWriter: Used to programmatically inject Business Intelligence (BI) formatting and auto-filters directly into the final Excel output.

🏗️ Architecture & Workflow

The system is orchestrated by main.py through three modular components:

1. data_generator.py: Simulates realistic e-commerce datasets (shopify_sales_history.csv and current_inventory.csv).
2. etl_engine.py: Ingests data, calculates net quantities, and aggregates historical performance.
3. forecaster.py: Applies the safety stock formula and exports the final event_restock_plan.xlsx.

🚀 Quick Start

1. Clone the repository and install dependencies:

git clone https://github.com/SimonChiabo/Event-Driven--Restock-Engine.git
cd Event-Driven--Restock-Engine
pip install polars xlsxwriter

2. Run the engine:

python main.py

3. Check the results: Open event_restock_plan.xlsx to see your prioritized restock plan.