StockFlow

AI-Powered Demand Forecasting Platform

An intelligent SaaS platform that helps wholesalers forecast demand, optimize inventory, and make data-driven decisions using machine learning.

Built with Django REST Framework + React + XGBoost | Developed during DEVCAMP 3.0 Hackathon

---

Overview

StockFlow solves a critical problem for Algerian wholesalers: unpredictable demand leading to stock shortages or overstocking. By analyzing historical sales data, seasonal trends, and promotional impacts, StockFlow delivers actionable demand forecasts with an XGBoost-based ML pipeline.

Key Capabilities

• CSV-based Prediction — Upload sales data, get demand forecasts as downloadable CSV
• Visual Analytics Dashboard — Critical products, seasonal trends, and product status charts
• Subscription Management — Multi-tier plans (Free, Basic, Premium) with prediction limits
• User Authentication — Token-based auth with profile management
• Automated Notifications — Subscription expiry alerts and stock warnings

---

Screenshots

Landing Page

Prediction Interface

Upload CSV	View Results

Analytics Dashboard

Subscription Plans

Plans	Checkout

User Profile

Authentication

Sign Up	Sign In

---

Tech Stack

Layer	Technology
Frontend	React 19, Tailwind CSS 4, React Router 7, Axios, React Hot Toast
Backend	Django 5.2, Django REST Framework, SimpleJWT
ML Pipeline	XGBoost, Scikit-learn, Pandas, NumPy
Database	MySQL
Visualization	Matplotlib (server-side graph generation)

---

Architecture

┌─────────────┐     REST API      ┌──────────────────┐     Cache      ┌─────────┐
│   React SPA  │ ◄──────────────► │  Django Backend   │ ◄───────────► │  MySQL  │
│  (Vite dev)  │                  │  (DRF + JWT Auth) │               └─────────┘
└─────────────┘                  └────────┬───────────┘
                                          │
                                 ┌────────▼───────────┐
                                 │   ML Pipeline       │
                                 │  XGBoost + Sklearn  │
                                 │  Feature Engineering│
                                 └─────────────────────┘

Frontend proxies /api requests to Django via Vite dev server proxy. The ML model (.pkl) is loaded on each prediction request. Dashboard graphs are generated server-side using Matplotlib and served as base64-encoded images.

---

Getting Started

Prerequisites

• Python 3.10+
• Node.js 18+
• MySQL 8+

1. Clone & Setup Backend

git clone https://github.com/yourusername/stockflow.git
cd stockflow/Backend

python -m venv venv
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

pip install -r requirements.txt

2. Configure Environment

Copy the example and fill in your values:

cp .env.example .env

SECRET_KEY=your-secret-key
DEBUG=True
DB_NAME=stockflow
DB_USER=root
DB_PASSWORD=your-password
DB_HOST=localhost
DB_PORT=3306

3. Initialize Database

python manage.py migrate
python manage.py createsuperuser

4. Train the ML Model

Open notebooks/eda_and_model.ipynb and run all cells. This will generate notebooks/model.pkl required for predictions.

5. Start Backend

python manage.py runserver

6. Setup Frontend

cd ../frontend
npm install
npm run dev

7. Access the App

Service	URL
Frontend	http://localhost:5174
Backend API	http://localhost:8000/api/
Admin Panel	http://localhost:8000/admin/

---

ML Pipeline

Feature Engineering

Feature	Description
week_sin, week_cos	Sinusoidal encoding of week number for cyclical seasonality
discount	Calculated as (base_price - total_price) / base_price
is_featured_sku	Binary flag for promotional products
is_display_sku	Binary flag for display products
store_id_*, sku_id_*	One-hot encoded categorical features

Model

• Algorithm: XGBoost Regressor
• Optimization: RandomizedSearchCV for hyperparameter tuning
• Evaluation: Cross-validated on historical sales data

---

API Endpoints

Method	Endpoint	Auth	Description
POST	/api/auth/register/	No	User registration
POST	/api/auth/login/	No	Login (email or username)
POST	/api/auth/logout/	Yes	Logout & invalidate token
GET/PUT	/api/auth/profile/	Yes	View/update profile
POST	/api/auth/predict/	Yes	Upload CSV, get predictions
GET	/api/auth/dashboard_graphs/	Yes	Get dashboard analytics
POST	/api/auth/choose-plan/	Yes	Update subscription plan

---

Project Structure

stockflow/
├── Backend/
│   ├── Backend/          # Django project settings
│   │   ├── settings.py   # Environment-based config
│   │   └── urls.py
│   ├── users/            # Auth, profiles, subscriptions, predictions
│   │   ├── models.py     # CustomUser with subscription logic
│   │   ├── views.py      # API views
│   │   └── serializers.py
│   ├── ai/               # ML preprocessing utilities
│   │   ├── utils.py
│   │   └── data_preprocessing.py
│   ├── dashboard/        # Graph generation
│   │   └── utils.py      # Matplotlib visualizations
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── api/          # Axios instance with interceptors
│   │   ├── components/   # Navbar, Sidebar, ErrorBoundary, etc.
│   │   ├── context/      # AuthContext (login, register, logout)
│   │   └── pages/        # Dashboard, Predict, Pricing, Profile
│   └── package.json
├── notebooks/
│   └── eda_and_model.ipynb  # EDA + model training
├── data/
│   └── dataset_devcamp.csv  # Training dataset
└── README.md

---

Subscription Plans

Plan	Predictions	Features	Price (DZD)
Free Trial	3	Basic predictions	Free
Basic Monthly	5	Dashboard analytics	15,000/mo
Premium Monthly	8	Dashboard + Reports	20,000/mo
Basic Annual	60	Dashboard + Annual discount	70,000/yr
Premium Annual	Unlimited	All features	100,000/yr

---

What I Learned

• Building a full-stack SaaS with subscription management from scratch
• Integrating ML models into a REST API pipeline
• Feature engineering for time-series forecasting (sinusoidal encoding, discount calculation)
• React Context API for global auth state management
• Django token authentication with DRF

---

Future Enhancements

• Docker Compose for one-command deployment
• CI/CD pipeline with GitHub Actions
• LSTM/Prophet models for time-series comparison
• Email notifications via Celery + Redis
• PDF report generation for premium users
• Mobile-responsive design improvements
• Arabic/French localization

---

Hackathon Context

DEVCAMP 3.0 — Built in 3 days as a team project. This repository represents the continued development with code quality improvements, proper authentication, and enhanced UI/UX after the hackathon.

---

If you found this project interesting, give it a star!