Who are your best customers, who is slipping away, and which group does a new customer belong to? This repo turns the
retail_project.ipynbanalysis of the UCI Online Retail dataset into a running app: a FastAPI service plus a React dashboard, started with onedocker compose up.
Marketing budgets go further when each group of customers gets the offer that fits it. This app scores customers by recency, frequency and spend, clusters them with K-Means, and assigns new customers to a segment through an API. On the UCI Online Retail data, about 16% of customers bring in about 64% of revenue, which is why the groups matter. docs/BUSINESS_CASE.md covers the use cases, an illustrative ROI model and the limits.
A UK online gift retailer has 397,884 cleaned transactions from 4,338 customers between Dec 2010 and Dec 2011, worth about £8.9M. Marketing can't treat 4,338 people one at a time, and treating them all the same wastes budget. Segmentation splits them into groups that behave alike, so each group gets its own playbook.
flowchart LR
A[UCI Online Retail<br/>xlsx, ~540k rows] --> B[Clean<br/>drop missing IDs,<br/>returns, zero prices]
B --> C[RFM per customer<br/>Recency · Frequency · Monetary]
C --> D[Quartile scores 1–4<br/>RFM score e.g. 111]
D --> E[Named RFM segments<br/>Best, Loyal, At Risk…]
C --> F[log1p → StandardScaler → K-Means k=4]
F --> G[Behavioural clusters<br/>Champions … Hibernating]
B --> H[Monthly cohort retention]
E & G & H --> I[(artifacts/)]
I --> J[FastAPI] --> K[React dashboard]
Two complementary views:
| View | How it works | Good for |
|---|---|---|
| RFM segments | Each customer gets a 1–4 score on R, F and M (1 = best) from the dataset's quartiles. Rules map scores to names: 111 Best Customers, 411 Lost Customers, 444 Lost Cheap, F=1 Loyal, M=1 Big Spenders… |
Explainable rules a marketer can read |
| K-Means clusters | RFM values are log-transformed, standardized and clustered (k=4, silhouette 0.335). Clusters are named by ranking their median value. | Data-driven groups with no hand-set thresholds |
| Cluster | Customers | Share of revenue | Median recency | Median orders | Median spend |
|---|---|---|---|---|---|
| Champions | 686 | 63.8% | 7 days | 10 | £3,774 |
| Loyal Regulars | 1,199 | 24.7% | 51 days | 4 | £1,380 |
| Potential | 808 | 4.9% | 16 days | 2 | £470 |
| Hibernating | 1,645 | 6.5% | 173 days | 1 | £300 |
About 16% of customers bring in about 64% of revenue. The Potential group is recent but light, so it's the natural target for a second-purchase campaign. Hibernating is the largest group and needs win-back offers, or no spend at all.
Typically 20–25% of a monthly cohort comes back the next month. The December 2010 cohort, which holds the earliest and most loyal buyers, stays at 30–50% all year.
Enter days since last order, number of orders and total spend. The API scores the customer against the fitted quartiles and K-Means model.
curl -X POST localhost:8000/assign -H 'content-type: application/json' \
-d '{"recency": 200, "frequency": 2, "monetary": 350}'
# {"R":4,"F":3,"M":3,"rfm_score":"433","segment":"At Risk","cluster":"Hibernating"}flowchart LR
U((Browser)) -->|:8080| W[web<br/>nginx + React build]
W -->|/api/* proxy| A[api<br/>FastAPI + uvicorn :8000]
A --> S[(artifacts/<br/>customers.csv<br/>kmeans.joblib<br/>meta.json)]
subgraph build["docker build (api image)"]
D[download UCI zip] --> T[segmentation.build] --> S
end
The dataset is downloaded and the model fitted during docker build, so no data or model files are committed.
| Endpoint | Purpose |
|---|---|
GET /health |
Liveness |
GET /summary |
KPIs, period, monthly revenue |
GET /segments |
RFM segment sizes, revenue share and medians |
GET /clusters |
K-Means cluster profiles |
GET /cohorts |
Monthly cohort retention matrix |
GET /customers?segment=&cluster=&limit=&sample= |
Top (or sampled) customers |
GET /customers/{id} |
One customer's RFM, segment and cluster |
POST /assign |
Score a new customer |
cp .env.example .env
docker compose up --build # first build downloads ~23 MB and fits the model (~1 min)
# dashboard: http://localhost:8080 API docs: http://localhost:8000/docs
docker compose downLocal development without Docker:
uv sync
uv run python -m segmentation.build # writes artifacts/
uv run uvicorn segmentation.api:app --reload # :8000
cd web && npm install && npm run dev # :5173, proxies /api to :8000
uv run pytest -qScreenshots are taken from the running stack with uv run --with playwright python scripts/screenshots.py.
src/segmentation/ core.py (cleaning, RFM, scoring, K-Means, cohorts) · build.py · api.py
web/ React + Vite + TypeScript dashboard, served by nginx
tests/ pytest unit + API tests on synthetic data
retail_project.ipynb original analysis notebook
docs/ANALYSIS.md original write-up of the notebook
PRODUCTIONIZING.md notebook → service notes
legacy/ superseded helper code (data_class.py)
- Frequency counts distinct invoices. The notebook counted invoice lines, which inflates customers who order many items at once.
- k = 4 instead of 13. Thirteen clusters were later merged by hand into Low, Middle and High. Four log-scaled clusters give readable profiles directly, and
N_CLUSTERSin.envchanges k. - RFM segments are mutually exclusive (rules are checked in priority order), so their counts add up to the customer total.





