retail analytics

The Problem

Retail businesses need to make sense of large volumes of sales data and customer feedback, but the analytics tools available to them are often fragmented. Sales forecasting, customer segmentation, and review analysis typically live in separate systems, making it hard to connect the dots between what customers say and what those comments mean for revenue. Decision-makers end up with dashboards that show numbers but not the reasoning behind them.

What This Does

retail-analytics is a full-stack analytics platform that combines sales forecasting, customer segmentation, and NLP-based product review analysis into a single application. The core logic lives in src/models/ (XGBoost forecasting, KMeans segmentation, BERT sentiment) and src/nlp/ (RAG pipeline with embeddings and vector search). A FastAPI layer in api/ exposes these capabilities via REST endpoints, and a Streamlit dashboard in dashboard/ provides the interactive UI.

The platform is structured around five functional areas: sales analytics, forecasting, customer segmentation, review analysis, and RAG-based Q&A. The api/routers/ directory contains separate routers for each domain. Data preprocessing and feature engineering are handled in src/data/, with drift detection and metric tracking in src/monitoring/ for MLOps concerns.

How To Use It

Setup: Install dependencies from requirements.txt. The README suggests uv pip install -r requirements.txt after creating a virtual environment.

Configuration: Copy .env.example to .env and edit. Additional configuration lives in config/ — apiconfig.yml, modelconfig.yml, and monitoringconfig.yml.

Running it: The README documents three entry points — the API via uvicorn api.main:app --reload --port 8000, the dashboard via streamlit run dashboard/app.py, and Docker via docker-compose up -d. A Makefile and setup.py are present for build tasks.

python -m venv venv source venv/bin/activate uv pip install -r requirements.txt cp .env.example .env uvicorn api.main:app --reload --port 8000

Real-World Use

A retail operations team could deploy this platform to monitor weekly sales forecasts, identify underperforming customer segments, and track sentiment shifts in product reviews. The RAG endpoint (api/routers/rag.py) lets analysts ask questions like "What do customers complain about most for the wireless headphones?" and get answers grounded in actual review data. The forecasting models in src/models/forecasting.py feed predictions into the dashboard's sales analysis pages, giving store managers a single view of expected demand and current customer sentiment.

Code Health & Issues

Med - No dependency lockfile: requirements.txt declares dependencies without pinned versions, so builds are not reproducible. This matters for a project claiming production readiness. Med - Duplicate test files: Tests exist in both tests/ and tests/unit/ with overlapping names (testapi.py, testmodels.py, testpreprocessing.py). This suggests either redundancy or confusion about the test layout. Low - Data files committed: data/raw/ contains CSV and JSONL data files. This is fine for a demo but not appropriate for a production system with real customer data. Low - Inconsistent notebook organization: Several notebooks live at the repo root (productreviewanalysisRAG.ipynb, salesforecastingcustomersegmentation.ipynb) alongside their markdown counterparts, while others are in notebooks/. The root-level placement is untidy. Positive: CI/CD is configured in .github/workflows/ (ci, cd, and tests workflows), 12 test files exist, and documentation is reasonably complete (docs/ has API docs, dashboard guide, MLOps design).

The Bottom Line

This is a well-scoped retail analytics platform with a sensible architecture and working ML components. The RAG-based Q&A feature is a differentiator, and the Docker/CI setup makes it deployable. The main weakness is dependency management — lack of a lockfile undermines the production-ready claim. Good fit for a mid-size retail team wanting an integrated analytics stack, less suitable for teams needing strict reproducibility or handling sensitive customer data.