City-Wide Dark Store Network Projection

An analytics platform for optimizing dark store placement across urban areas. Uses machine learning (KMeans clustering, XGBoost) and geospatial analysis to identify optimal locations for new dark stores, predict delivery times, and generate business insights powered by the Gemini API.

Features

• Store Location Optimization - KMeans clustering on order data to suggest optimal new store locations
• Delivery Time Prediction - XGBoost model for estimating delivery times based on distance, traffic, and order volume
• Interactive Map View - Leaflet-based maps showing existing stores, suggested locations, and delivery zones
• Impact Analysis - Evaluate how new store placements affect delivery coverage and times
• Business Insights - Gemini-powered analysis for operational recommendations
• Dashboard Analytics - Revenue tracking, store counts, and high-demand area identification
• Store Management - CRUD operations for store data with MySQL backend
• OTP Authentication - Email-based OTP login system via Nodemailer
• PDF Reports - Generate exportable reports for store network analysis

Tech Stack

ML/API Layer (Python)

• FastAPI for REST endpoints
• scikit-learn (KMeans clustering)
• XGBoost for delivery time prediction
• geopy for distance calculations
• Google Generative AI (Gemini) for business insights
• joblib for model serialization

Backend (Node.js)

• Express.js server
• MySQL2 for database operations
• Nodemailer for OTP email delivery
• Axios for inter-service communication
• bcryptjs and JWT for authentication

Frontend (React)

• React 19 with React Router v7
• Ant Design component library
• Leaflet / React-Leaflet for maps
• Chart.js / Recharts for data visualization
• React PDF Renderer for report generation

Project Structure

city-wide-dark-store-network-projection/
├── api/                           # Python ML microservice
│   ├── main.py                    # FastAPI cluster & delivery prediction
│   ├── locator.py                 # Store location suggestion engine
│   ├── mistral.py                 # Gemini-powered impact analysis
│   ├── requirements.txt           # Python dependencies
│   ├── kmeans_model.pkl           # Trained KMeans model
│   ├── xgboost_model.pkl          # Trained XGBoost model
│   ├── scaler.pkl                 # Feature scaler
│   ├── clustered_orders.csv       # Processed order data
│   └── synthetic_orders.csv       # Synthetic training data
├── Back/                          # Node.js backend
│   ├── server.js                  # Express server with MySQL
│   ├── locatermodel.js            # Location analysis with LLM
│   └── package.json
├── front/                         # React frontend
│   ├── public/
│   ├── src/
│   │   ├── App.js                 # Main routing
│   │   ├── components/
│   │   │   ├── MapComponent.js    # Leaflet map with store markers
│   │   │   ├── Navbar.js
│   │   │   ├── Sidebar.js
│   │   │   └── Footer.js
│   │   ├── pages/
│   │   │   ├── LandingPage.js     # Public landing page
│   │   │   ├── Login.js           # OTP-based authentication
│   │   │   ├── Dashboard.js       # Analytics dashboard
│   │   │   ├── MapView.js         # Interactive map view
│   │   │   ├── Reports.js         # Report generation
│   │   │   ├── StoreAnalytics.js  # Per-store analytics
│   │   │   ├── ManageStores.js    # Store CRUD operations
│   │   │   └── AdminProfile.js    # Admin settings
│   │   ├── styles/                # CSS modules
│   │   └── assets/                # Static images
│   └── package.json
└── README.md

Getting Started

Prerequisites

• Python 3.9+
• Node.js 18+
• MySQL 8.0+

ML API Setup

cd api
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

Backend Setup

cd Back
npm install
node server.js

The Express server runs on port 3000 (or 5000 depending on configuration).

Frontend Setup

cd front
npm install
npm start

The React app runs on http://localhost:3000.

Database Setup

Create a MySQL database named hackron (or avishkar_hackron) and set up the required tables for stores, users, and potential store locations.

API Endpoints

Python ML API (port 8000)

• POST /predict-cluster - Predict order cluster assignment
• POST /predict-delivery-time - Estimate delivery time
• POST /suggest-new-stores - Suggest optimal store locations
• POST /analyze-impact - Full impact analysis with business insights

Node.js Backend (port 5000)

• GET /api/stores - Fetch all stores
• GET /api/stores/count - Get total store count
• GET /api/possible-stores - Get ML-suggested store locations
• POST /api/login - Login with email/password (triggers OTP)
• POST /api/verify-otp - Verify email OTP

License

This project is for educational and research purposes.

Environment Variables

Copy .env.example to .env and fill in your configuration:

cp .env.example .env