Inventory Demand Forecasting Tool

AI-powered inventory demand forecasting application with reorder recommendations using Prophet time-series forecasting.

Features

• Time-Series Forecasting: Uses Facebook Prophet for accurate demand prediction
• Multi-Store & Product Support: Forecast demand across different stores and products
• Anomaly Detection: Automatically detects unusual spikes and drops in demand
• Seasonality Analysis: Identifies weekly and yearly seasonal patterns
• Reorder Recommendations: Suggests optimal reorder date and quantity
• Stockout Risk Indicator: Alerts when inventory might run out
• Interactive Dashboard: Clean, modern UI with filters and visualizations
• CSV Export: Export forecast results for further analysis

Technology Stack

• Backend: FastAPI + Python
• Frontend: React + Recharts
• Database: MongoDB
• ML/Forecasting: Prophet, scikit-learn
• UI Components: Shadcn/UI + Tailwind CSS

Getting Started

Prerequisites

• Python 3.11+
• Node.js 18+
• MongoDB
• Yarn package manager

Installation

1. Backend Setup

cd backend
pip install -r requirements.txt

2. Frontend Setup

cd frontend
yarn install

3. Environment Configuration

Backend .env:

MONGO_URL=mongodb://localhost:27017
DB_NAME=inventory_forecast
CORS_ORIGINS=*

Frontend .env:

REACT_APP_BACKEND_URL=http://localhost:8001

Running the Application

1. Start Backend

cd backend
uvicorn server:app --host 0.0.0.0 --port 8001 --reload

2. Start Frontend

cd frontend
yarn start

3. Access the Application

Open your browser and navigate to http://localhost:3000

Generating Sample Data

Use the provided script to generate sample inventory data:

python scripts/generate_sample_data.py

This creates a sample_inventory_data.csv file with:

• 5 stores
• 10 products
• 365 days of historical data
• Seasonal patterns
• Promotional effects
• Random anomalies

Usage Guide

1. Upload Data

• Click the upload area on the dashboard
• Select your CSV file with the following columns:
  • date: Date in YYYY-MM-DD format
  • store_id: Store identifier
  • product_id: Product identifier
  • category: Product category
  • units_sold: Number of units sold
  • price: Price per unit
  • promotions: 1 if promotion active, 0 otherwise
  • stock_on_hand: Current stock level

2. Generate Forecast

• Select a store from the dropdown
• Select a product
• Choose forecast period (30, 60, or 90 days)
• Click "Generate Forecast"

3. Analyze Results

The dashboard displays:

• Metrics: Average daily demand, current stock, trend, stockout risk
• Reorder Recommendations: Suggested reorder date and quantity
• Forecast Chart: Historical data with future predictions and confidence intervals
• Anomalies: Detected unusual demand patterns

4. Export Data

Click the "Export CSV" button to download forecast results.

API Endpoints

Data Management

• POST /api/data/upload - Upload inventory CSV file
• GET /api/data/stores - Get list of stores
• GET /api/data/products?store_id=XXX - Get products for a store
• GET /api/data/historical?store_id=XXX&product_id=YYY - Get historical data

Forecasting

• POST /api/forecast - Generate demand forecast

  {
    "store_id": "STORE_001",
    "product_id": "PROD_0001",
    "forecast_days": 30,
    "lead_time": 7,
    "safety_stock_days": 5
  }

• GET /api/export/forecast?store_id=XXX&product_id=YYY&forecast_days=30 - Export forecast CSV

Forecasting Methodology

Prophet Model

• Seasonality: Captures weekly and yearly patterns
• Trend: Identifies increasing or decreasing demand
• Multiplicative Mode: Better handles percentage-based seasonal effects
• Confidence Intervals: Provides upper and lower bounds for predictions

Anomaly Detection

• Uses Z-score method with threshold of 2.5 standard deviations
• Flags unusual spikes or drops in demand
• Helps identify special events or data quality issues

Reorder Calculation

Safety Stock = Average Daily Demand × Safety Stock Days
Reorder Point = (Average Daily Demand × Lead Time) + Safety Stock
Reorder Quantity = (Average Daily Demand × Lead Time) + Safety Stock - Projected Stock

Stockout Risk Assessment

• High Risk: Reorder needed within 7 days
• Medium Risk: Reorder needed within 8-14 days
• Low Risk: Reorder needed after 14 days or sufficient stock

CSV Data Format

Your CSV file should follow this structure:

date,store_id,product_id,category,units_sold,price,promotions,stock_on_hand
2023-01-01,STORE_001,PROD_0001,Electronics,45,299.99,0,1200
2023-01-02,STORE_001,PROD_0001,Electronics,52,299.99,0,1148
2023-01-03,STORE_001,PROD_0001,Electronics,38,299.99,0,1110

Troubleshooting

"Insufficient historical data" error

• Ensure you have at least 10 days of data per product/store combination
• Prophet requires minimum data points for reliable forecasting

Forecast looks unrealistic

• Check for data quality issues
• Review anomalies - they might indicate data problems
• Ensure your historical data is representative of future demand

High stockout risk

• Consider increasing safety stock days
• Reduce lead time if possible
• Check if forecast accurately reflects demand patterns

Project Structure

.
├── backend/
│   ├── server.py              # FastAPI application
│   ├── requirements.txt       # Python dependencies
│   └── .env                   # Environment variables
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── Dashboard.js   # Main dashboard component
│   │   │   └── ui/            # Shadcn UI components
│   │   ├── App.js
│   │   ├── App.css
│   │   └── index.css
│   ├── package.json
│   └── .env
├── scripts/
│   └── generate_sample_data.py  # Sample data generator
└── README.md

Performance Considerations

• Prophet model fitting can take 5-30 seconds depending on data size
• Consider caching forecasts for frequently accessed product/store combinations
• For production, implement background job processing for large-scale forecasting

Future Enhancements

• Multiple forecasting algorithms (ARIMA, LSTM)
• What-if scenario analysis
• Multi-product bundle forecasting
• Integration with ERP systems
• Automated email alerts for reorder recommendations
• Advanced visualization with trend decomposition

License

MIT License

Support

For issues or questions, please open an issue on the repository.