Project Overview and Business Context
The client was a supply chain consultancy building a SaaS tool for mid-market manufacturing and distribution businesses. Their target customers had supply chains with 50-300 SKUs, 10-40 suppliers, and lead times ranging from 2 weeks to 6 months depending on product category and supplier geography. These customers were running demand planning in Excel: importing ERP exports, applying manual adjustments for seasonal factors, and emailing the demand plan to suppliers as a PDF. The process was slow, produced errors when spreadsheets grew complex, and gave supply chain managers no visibility into how plan assumptions would affect outcomes under different demand scenarios. The brief was to build a planning tool that imported ERP data, maintained a structured demand plan, modelled supplier lead times and order frequencies, generated alerts when planned demand was at risk of creating a supply shortfall, and allowed the planner to explore scenarios using natural language. The natural language scenario planning requirement drove the Claude integration: instead of rebuilding a static what-if calculator for every scenario type, the planner should be able to ask questions like what happens if our largest supplier has a 4-week delay on all orders and receive a coherent analysis of the impact across their SKU portfolio.
Technical Architecture and Stack Decisions
The backend is a Python FastAPI service on AWS EC2, with PostgreSQL storing all demand plan data: SKUs, suppliers, lead times, minimum order quantities, current stock levels, demand forecasts, and order history. The ERP integration layer accepts data imports via REST API (for ERPs with API access) or CSV uploads (for legacy ERPs without). A daily ETL job refreshes stock levels, recent order receipts, and sales data from the ERP export. The demand planning engine is a Python module that, for each SKU, computes: current weeks of stock cover, projected stock-out date based on the demand forecast, the next required order date (stock-out date minus supplier lead time minus safety stock buffer), and the recommended order quantity (covering the reorder period at forecast demand). Results are written to PostgreSQL and surfaced in the Next.js planning dashboard. The disruption alert system monitors the plan daily and generates alerts when: a stock-out is projected within twice the supplier lead time, a supplier's on-time delivery rate (tracked from historical order data) has fallen below the configured threshold, or an unplanned demand spike in the previous week has shifted the stock-out projection significantly. Alerts are sent via email and displayed in the dashboard. Claude handles the natural language scenario planning layer. The planner types a scenario question into the dashboard, and a FastAPI endpoint retrieves the relevant context from PostgreSQL (current stock levels, demand forecasts, supplier lead times, outstanding orders) and passes it to Claude with the question and a system prompt. Claude returns a plain-English analysis of the scenario's impact and a list of recommended actions.
Key AI and ML Components
Anthropic Claude is used for natural language scenario planning and for generating the weekly supply chain narrative summary. Scenario planning via Claude works because the system provides Claude with the complete structured context it needs to reason about the scenario: current stock positions, demand forecasts, supplier lead times, and outstanding orders. Claude can then apply supply chain logic to the scenario question (what if supplier X delays by 4 weeks) by identifying which SKUs are sourced from supplier X, computing the effect on stock cover, and identifying which customers or production lines would be affected first. The system prompt includes supply chain domain knowledge: how to interpret weeks of cover, what actions to recommend for different risk categories, and how to frame uncertainty in supply chain scenarios. Claude is also used to generate the weekly summary email: a supply chain health digest covering the top five risks, the top three recommended actions, and a plain-English narrative of how the plan compares to last week. This weekly communication is sent to the supply chain director and finance director, giving them visibility without requiring them to log in to the planning tool. The demand forecasting layer uses a simpler time series model (exponential smoothing with seasonal adjustment) rather than an LLM. Numerical forecasting requires precision and reproducibility that statistical models provide reliably.
Challenges Solved and How
ERP data quality is consistently the hardest problem in supply chain planning tools. ERPs accumulate data entry errors, obsolete records, and inconsistent units over years of operation. The ETL layer applies a set of data quality rules on every import: checking for negative stock quantities, inconsistent unit of measure across transactions, SKUs with supplier lead times of zero or implausibly long, and orders in ERP status 'received' that have no goods receipt date. Data quality issues are flagged in the dashboard and sent to the supply chain manager for resolution before they affect plan calculations. Supplier lead time variability is not captured by a single lead time figure. Suppliers have nominal lead times and actual lead times, and the variance between them determines how much safety stock is appropriate. The system tracks actual lead times from historical order data (order placed date to goods received date) per supplier per SKU, computes the average and standard deviation, and uses the 80th percentile actual lead time for planning calculations rather than the nominal lead time. This automatically adjusts safety stock for unreliable suppliers without requiring the planner to manually adjust safety stock rules. Claude's scenario analysis required careful context management. Supply chain scenarios often involve cascading effects across multiple SKUs, suppliers, and customers. Providing Claude with the right level of context to reason about cascades without exceeding context window limits required the FastAPI layer to pre-filter the relevant SKUs and suppliers before passing to Claude.
Outcome and Measurable Results
The client piloted the tool with three mid-market distribution businesses over 14 weeks. Average time spent by supply chain managers on weekly demand planning fell from 9 hours to 2.5 hours. Stockout incidents (weeks where a SKU reached zero stock while listed as active) fell by 29% in the planning-tool-assisted period versus the prior year comparable period. Supplier on-time delivery visibility, previously limited to informal notes in spreadsheet comments, became systematically tracked, allowing two of the three pilot businesses to renegotiate lead time commitments with underperforming suppliers based on data. The natural language scenario planning feature was used most frequently by finance directors who wanted to understand supply chain risk in plain English without navigating the planning dashboard: they asked questions directly and received the analysis in the weekly summary email, improving cross-functional alignment on supply chain risk.
Lessons for Similar Projects
Data quality infrastructure is the supply chain planning product. A planning tool is only as reliable as the data it operates on. Invest a full sprint in the ETL layer, data validation rules, and quality alerting before building any planning logic. The scenario planning UX is as important as the scenario planning AI. If the planner cannot easily type a scenario question and get an immediate response, they will not use the feature. The interface needs to feel like a fast chat interface, not a form submission. Track actual versus planned lead times from day one. The difference between nominal and actual supplier lead time is where most supply chain planning assumptions break down. Building that tracking into the data model from the start enables evidence-based safety stock calculations that improve continuously. Involve finance in the product design. Supply chain planning decisions directly affect cash flow and working capital. Finance stakeholders who get a plain-English weekly digest are more likely to support the tool and act on its recommendations than those who only see a planning dashboard they were not involved in designing.