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.
- Calculates demand forecasts, safety stock, reorder points, days of supply, and recommended order quantities.
- Assigns operational risk levels:
CRITICAL,HIGH,MEDIUM, andLOW. - Produces clear planner actions:
REORDER,MONITOR, orOK. - 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.
SupplyChain_Frontend.mp4
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
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.
| 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 |
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
shippedunits 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.
| 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 |
Main endpoint:
GET /replenishment/recommendationsOptional 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_01Example 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.
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
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.txtStart the backend:
cd backend
python -m uvicorn app.main:app --reloadIn a second terminal, start the frontend:
cd frontend
npm install
npm startOpen:
- 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.
MongoDB Atlas can provision a managed MongoDB cluster on AWS. After creating a cluster:
- Create an Atlas database user.
- Add your current IP address under Atlas Network Access.
- Copy the Python connection string from Atlas.
- Create your private environment file:
cd backend
Copy-Item .env.example .env- 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_snapshotsDo 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\rawThe 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 --reloadTo return to CSV mode, set DATA_BACKEND=csv or remove backend/.env.
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.txtAtlas 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.
Backend tests:
cd backend
python -m pytest -qFrontend production build:
cd frontend
npm run buildThe 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.
- 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.
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.
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.