PredictiStore Engine is a highly optimized, full-stack Single-Page Application (SPA) designed to act as a dynamic retail inventory manager. It allows users to upload raw sales datasets (CSV), stores them efficiently, manages complex supplier networks, and utilizes Machine Learning to instantly forecast future demand.
The primary goal of PredictiStore is to prevent retail stockouts by predicting the exact inventory volume required over the next 14 days and generating automated supplier procurement drafts when deficits are detected.
The technology stack has been selected to ensure performance, portability, and clean design patterns:
| Layer | Technology | Rationale |
|---|---|---|
| Backend | FastAPI (Python) | Optimized for asynchronous execution, enabling fast performance. It handles parsing datasets and executing Machine Learning models over HTTP endpoints without blocking the main event loop. |
| Machine Learning | LightGBM | An advanced, fast gradient-boosting framework developed by Microsoft. It trains complex decision trees on the fly, allowing it to handle nonlinear patterns (such as weekend sales spikes) with high accuracy and low computational overhead. |
| Database | SQLite3 | A lightweight, embedded relational database. It requires no standalone server setup, which ensures the project is portable and runs instantly on any machine while supporting relational queries between inventory and sales history tables. |
| Frontend | Vanilla HTML5, CSS3, & JavaScript | Built natively without heavy frameworks (such as React, Angular, or Vue) to eliminate dependency bloat, reduce build complexity, and achieve near-instantaneous page load times using glassmorphism styling. |
Below is a breakdown of the primary components in the repository:
- app.py
- Usage: Main entry point for starting the backend server.
- Details: Auto-deletes old database files on startup to ensure a clean database state, then runs the FastAPI application via Uvicorn on port 8001 with hot-reload enabled.
- start.bat
- Usage: User-friendly batch file launcher for Windows.
- Details: Forcefully terminates duplicate or orphaned Python server processes to prevent port conflicts, starts the FastAPI server, waits briefly for initialization, and launches the browser to the application page.
- backend/main.py
- Usage: Core API routing and database controllers.
- Details: Exposes REST endpoints (
/api/dashboard,/api/inventory, and/api/upload-dataset). It manages database connections, parses multipart CSV payloads using SQLINSERT OR REPLACElogic, and handles application state.
- backend/forecaster.py
- Usage: Time-series machine learning model.
- Details: Contains the forecasting logic. It loads historical time-series sales data, performs feature engineering (e.g., weekday vs. weekend features), trains a LightGBM regressor in real time, and predicts sales demand for the next 14 days.
- frontend/index.html
- Usage: The client interface (SPA).
- Details: A single page styled with a modern dark-mode aesthetic. JavaScript handles SPA routing, drag-and-drop file ingestion, reactive state management, and updates the dynamic chart using Chart.js based on backend responses.
- generate_mock_data.py
- Usage: Testing utility.
- Details: Generates synthetic CSV sales datasets containing multiple items, mock suppliers, and months of transaction logs with realistic weekday/weekend distributions.
When the application launches via start.bat, the backend database is cleared. The frontend client queries the server for dashboard metrics. Since no products exist, the API responds with a 404 Not Found error. The frontend catches this error, hides empty graph containers, and presents a "System awaits initialization" screen directing the user to load a dataset.
The user uploads a compatible CSV file (such as sample_dataset.csv) via the Data Hub. The frontend sends this file to /api/upload-dataset. The backend reads the CSV in memory, splits the data, creates records in the inventory table, and commits transaction records to the sales_history table. Upon completion, the UI transitions the user to the Inventory view.
When a user clicks "Analyze" on an inventory item:
- The frontend stores the target SKU in its state and navigates to the Dashboard view.
- The browser requests
/api/dashboard?sku=SKU_ID. - The backend fetches the item's details and the past 30 days of sales history from SQLite.
- The history is passed to
forecaster.py, where a LightGBM model is trained to generate a 14-day forecast. - The backend compares projected demand against current stock to calculate the expected deficit. If demand exceeds stock, a high stockout risk flag is activated.
- The combined payload is returned to the frontend to draw the forecast curve and fill in KPI metrics.
- Anti-Ghosting Protocol: The startup script automatically shuts down orphaned Python processes to prevent port conflicts on port 8001.
- Graceful State Handling: The application handles empty databases, missing records, or server connection drops without UI crashes or JavaScript errors.
- Zero-Reload SPA: Seamless view switching is handled entirely via DOM manipulation, resulting in instant navigation transitions.
- Dynamic Content Updating: UI dropdowns, list views, and tables adjust automatically based on database states.
- SMTP Integration: Connect the email-drafting generator to a mail transmission service (such as SendGrid or standard SMTP) to automatically email suppliers when deficits are projected.
- JWT Authentication: Add secure user logins using JSON Web Tokens (JWT) so only authenticated coordinators can upload datasets or adjust inventory counts.
- Database Upgrades: Transition from a local SQLite database to a managed SQL database (such as PostgreSQL) to support concurrent multi-user environments.
- Advanced ML Models: Implement models that account for yearly seasonality (such as Facebook's Prophet) for longer-term demand planning.