Skip to content

About

Retail Replenishment Control Tower: A full-stack retail supply-chain application that converts historical demand and current inventory into explainable replenishment recommendations.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

Repository files navigation

Retail Replenishment Control Tower

A full-stack retail supply-chain application that converts historical demand and current inventory into explainable replenishment recommendations.

The project combines a React operations dashboard, a typed FastAPI REST API, deterministic forecasting and stock-policy calculations, automated tests, and interchangeable CSV or MongoDB Atlas storage. It was designed as a focused portfolio project for junior full-stack and backend engineering roles in retail logistics.

Highlights

  • Calculates demand forecasts, safety stock, reorder points, days of supply, and recommended order quantities.
  • Assigns operational risk levels: CRITICAL, HIGH, MEDIUM, and LOW.
  • Produces clear planner actions: REORDER, MONITOR, or OK.
  • Provides product, warehouse, risk, search, sorting, and refresh controls in React.
  • Exposes typed, filterable REST endpoints with interactive Swagger documentation.
  • Uses a repository interface to switch between local CSV files and MongoDB Atlas.
  • Includes a repeatable CSV-to-MongoDB import utility with indexes and upserts.
  • Covers calculation rules, edge cases, API filters, and storage adapters with automated tests.

Demo

Frontend

SupplyChain_Frontend.mp4

Backend

The GET /replenishment/recommendations endpoint analyzes historical demand and current inventory to calculate safety stock, reorder points, days of supply, stockout risk, and recommended order quantities. It supports product, warehouse, and risk-level filters and works with either CSV data or MongoDB

SupplyChain_Backend.mp4

Application flow

CSV inventory snapshots                 MongoDB Atlas on AWS
      (default)                              (optional)
             \                              /
              Inventory Repository Interface
                            |
                 Replenishment Service
          demand | forecast | safety stock | risk
                            |
        GET /replenishment/recommendations
                            |
                React Planner Dashboard

The replenishment service depends on a small repository contract rather than a specific database. This keeps the business calculations testable and allows CSV development without requiring a cloud connection.

Technology stack

Layer Technologies
Frontend React 18, Axios, Chart.js, Recharts, CSS
Backend Python, FastAPI, Pydantic, Uvicorn
Data processing Pandas, NumPy
Storage CSV by default; MongoDB Atlas optionally
Testing Pytest, FastAPI TestClient, HTTPX
Optional analytics artifacts Databricks Bronze/Silver/Gold notebooks

Replenishment model

For each product and warehouse combination, the application uses the latest closing_stock as available inventory and the latest 30 days of shipped quantities as a demand proxy.

average daily demand = mean(shipped units in the 30-day history window)
7-day forecast       = average daily demand x 7
safety stock         = 1.65 x demand standard deviation x sqrt(3)
reorder point        = average daily demand x 3 + safety stock
days of supply       = current stock / average daily demand
recommended quantity = max(0, 7-day forecast + safety stock - current stock)

Demo assumptions:

  • History window: 30 days
  • Lead time: 3 days
  • Service factor: 1.65, approximating a 95% service level
  • Target coverage: 7 days
  • shipped units are used because point-of-sale demand is not present in the source data

The engine handles incomplete rows, invalid values, negative quantities, missing history, and zero demand predictably. Recommendations are read-only; the application does not create purchase orders.

Risk and action policy

Condition Risk Action
No stock or no more than one day of supply CRITICAL REORDER
Stock is below the reorder point or lead-time coverage HIGH REORDER
Stock has no more than seven days of coverage MEDIUM MONITOR
Stock is above target thresholds LOW OK
Historical demand is zero LOW OK

REST API

Main endpoint:

GET /replenishment/recommendations

Optional filters:

GET /replenishment/recommendations?risk_level=HIGH
GET /replenishment/recommendations?product_id=PROD_GLASS_A1
GET /replenishment/recommendations?warehouse_id=WAREHOUSE_EU_01
GET /replenishment/recommendations?product_id=PROD_GLASS_A1&warehouse_id=WAREHOUSE_EU_01

Example response:

{
  "calculated_at": "2026-07-05T12:00:00Z",
  "assumptions": {
    "history_days": 30,
    "lead_time_days": 3,
    "service_factor": 1.65,
    "target_coverage_days": 7
  },
  "summary": {
    "total_items": 1,
    "critical_items": 0,
    "reorder_items": 1,
    "forecast_demand_7_days": 3500,
    "recommended_units": 2810
  },
  "recommendations": [
    {
      "product_id": "PROD_GLASS_A1",
      "warehouse_id": "WAREHOUSE_EU_01",
      "current_stock": 900,
      "average_daily_demand": 500,
      "demand_std_dev": 73.48,
      "forecast_7_days": 3500,
      "safety_stock": 210,
      "reorder_point": 1710,
      "days_of_supply": 1.8,
      "recommended_quantity": 2810,
      "risk_level": "HIGH",
      "action": "REORDER"
    }
  ]
}

Additional endpoints provide KPIs, anomalies, source data, health information, and the existing demonstration chat interface. Open http://localhost:8000/docs for the complete interactive API contract.

Project structure

supply-chain/
|-- backend/
|   |-- app/
|   |   |-- models/                 Pydantic API schemas
|   |   |-- repositories/           CSV and MongoDB adapters
|   |   |-- services/               KPI, anomaly, chat, and replenishment logic
|   |   `-- main.py                 FastAPI application and routes
|   |-- scripts/
|   |   `-- import_csv_to_mongodb.py
|   |-- tests/
|   |-- .env.example
|   `-- requirements.txt
|-- frontend/
|   `-- src/
|       |-- components/
|       |-- pages/
|       |   `-- Replenishment.js
|       `-- services/apiService.js
|-- data/raw/                        Demonstration CSV snapshots
|-- databricks/notebooks/            Optional medallion-pipeline artifacts
`-- README.md

Run locally with CSV

Requirements:

  • Python 3.10 or newer
  • Node.js 18 or newer

From the repository root, create and activate a virtual environment:

python -m venv .venv
Set-ExecutionPolicy -Scope Process Bypass
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r backend\requirements.txt

Start the backend:

cd backend
python -m uvicorn app.main:app --reload

In a second terminal, start the frontend:

cd frontend
npm install
npm start

Open:

  • Frontend: http://localhost:3000
  • Swagger API documentation: http://localhost:8000/docs
  • Health endpoint: http://localhost:8000/health

No .env file is required for CSV mode. CSV is the default storage backend.

Use MongoDB Atlas on AWS

MongoDB Atlas can provision a managed MongoDB cluster on AWS. After creating a cluster:

  1. Create an Atlas database user.
  2. Add your current IP address under Atlas Network Access.
  3. Copy the Python connection string from Atlas.
  4. Create your private environment file:
cd backend
Copy-Item .env.example .env
  1. Update backend/.env:
DATA_BACKEND=mongodb
MONGODB_URI=mongodb+srv://YOUR_USER:YOUR_PASSWORD@YOUR_CLUSTER/?retryWrites=true&w=majority
MONGODB_DATABASE=supply_chain
MONGODB_INVENTORY_COLLECTION=inventory_snapshots

Do not commit this file. backend/.env is ignored by Git; .env.example is the safe public template.

Import the CSV datasets:

# Run after activating the Python virtual environment
cd backend
python scripts\import_csv_to_mongodb.py --data-path ..\data\raw

The importer creates separate collections for inventory, production, shipments, quality, and suppliers. Source rows are upserted using deterministic keys, so rerunning the import updates the same records instead of duplicating them. The inventory collection receives a compound index for product, warehouse, and date access.

Start FastAPI normally after the import:

python -m uvicorn app.main:app --reload

To return to CSV mode, set DATA_BACKEND=csv or remove backend/.env.

Common setup errors

ModuleNotFoundError: No module named 'pandas' means the script is running with a Python environment where the backend requirements are not installed. Activate .venv and run:

python -m pip install -r backend\requirements.txt

Atlas connection failures usually mean the current IP address is not allowed, the database credentials are incorrect, or reserved characters in the password were not URL-encoded.

Tests and build

Backend tests:

cd backend
python -m pytest -q

Frontend production build:

cd frontend
npm run build

The backend tests cover calculation formulas, risk boundaries, zero demand, incomplete history, invalid records, API filters, non-negative recommendations, CSV fallback, and the MongoDB adapter without requiring a live Atlas cluster.

Engineering decisions

  • Python remains the backend language so the project presents one coherent, working application rather than a rushed second service.
  • Forecasting is deterministic and explainable, making each recommendation easy to verify.
  • Storage concerns are separated from domain calculations through repository adapters.
  • MongoDB is optional, preserving a fast local setup and reliable automated tests.
  • Cloud deployment and database credentials are deliberately kept outside the repository.

Current limitations

This is a portfolio decision-support application, not a production order-management system.

  • No authentication or authorization
  • No transactional purchase-order persistence
  • No live event stream or real-time inventory integration
  • No production machine-learning forecast
  • No item-specific lead times, promotions, seasonality, or lost-sales modelling
  • MongoDB Atlas configuration is supported, but this repository does not claim a publicly deployed cluster

Reasonable next steps include authenticated planner roles, item-specific replenishment policies, container deployment, operational telemetry, and message-driven inventory updates.

CV wording

Extended a React/FastAPI supply-chain control tower with a forecast-driven replenishment engine that calculates safety stock, reorder points, stockout risk, and recommended quantities; introduced interchangeable CSV and MongoDB Atlas repositories, exposed typed REST APIs, built an operational planner dashboard, and added automated tests.

About

Retail Replenishment Control Tower: A full-stack retail supply-chain application that converts historical demand and current inventory into explainable replenishment recommendations.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages