How aryan-s08/customer-segmentation works
1. Repository shape
This is a very small, notebook-driven analytics/ML project. The core logic lives in a single Jupyter notebook, with the dataset stored locally as a CSV. There is no application server, package structure, or separate training/inference service.
2. Primary input boundary
The only external data source is the Online Retail.csv transaction dataset. It contains invoice-level retail records with fields such as invoice number, product description, quantity, invoice date, unit price, customer ID, and country.
3. Notebook as the orchestration layer
The notebook acts as the full pipeline controller: it loads the data, cleans it, engineers features, runs analysis, trains models, and displays results. In architecture terms, this is a single pipeline execution environment rather than a multi-component system.
4. Data cleaning subsystem
The first processing stage removes records that would distort downstream analysis: missing values, cancelled invoices, negative quantities, and zero-price transactions. It also converts dates to datetime and derives TotalPrice = Quantity × UnitPrice. This stage transforms raw transactional data into analysis-ready data.
5. Exploratory analysis subsystem
The cleaned transactional data is then used for EDA to understand sales patterns. The notebook generates visual summaries such as top countries, top products, monthly sales trends, and feature distributions. This stage is descriptive and feeds business interpretation rather than model training directly.
6. Customer aggregation and RFM feature engineering
The main modeling boundary is the transition from transaction-level data to customer-level data. The notebook aggregates purchases into RFM features:
- Recency: time since last purchase
- Frequency: number of purchases
- Monetary: total spend
This is the key abstraction that turns retail transactions into customer behavior profiles.
7. Scaling and clustering path
The RFM matrix is normalized with StandardScaler and then passed into K-Means clustering. This unsupervised branch discovers customer segments from behavioral similarity. The architecture here is: feature matrix → scaled feature matrix → cluster labels.
8. Cluster selection logic
The notebook evaluates cluster quality using the Elbow Method and Silhouette Score to choose a reasonable number of segments. These are not separate services; they are internal decision aids that determine the clustering configuration.
9. Visualization of segment structure
After clustering, PCA is used to compress the customer feature space to two dimensions for plotting. This is a visualization-only boundary: it helps interpret cluster separation, but it is not the segmentation model itself.
10. Supervised prediction subsystem
The generated cluster labels become the target classes for a Random Forest classifier. This creates a second modeling branch: a supervised model that learns to predict segment membership for new customers based on their RFM-style inputs.
11. End-to-end data flow
The effective data flow is: raw retail transactions → cleaned transaction table → customer RFM features → scaled features → K-Means segment labels → PCA visualization and Random Forest prediction model. The clustering model produces the labels; the classifier learns to reproduce them for future customers.
12. Outputs and artifacts
The repository does not expose deployed APIs or saved model artifacts in the file tree. The primary outputs appear to be notebook-generated charts, segment assignments, and model evaluation results produced interactively inside Jupyter.
13. Technology boundary
The stack is entirely Python-based, using Pandas/NumPy for data manipulation, Matplotlib/Seaborn for visualization, and scikit-learn for scaling, clustering, PCA, and classification. The runtime boundary is local notebook execution, not cloud infrastructure.
14. Architecture summary for diagramming
A good diagram would show one input dataset feeding a sequential notebook pipeline with two modeling branches: an unsupervised segmentation path and a supervised prediction path. The key domain boundary is the conversion from transaction-level retail data to customer-level behavioral features.
Main entry points: Project (1).ipynb K-Means
Components 16
Input Data
Local retail transaction dataset used as the only external input.
- Online Retail.csv · Raw invoice-level retail transactions with product, quantity, price, date, customer, and country fields.
Notebook Pipeline
Single Jupyter notebook that orchestrates loading, cleaning, analysis, and modeling.
- Notebook · Jupyter execution environment that runs the full analysis pipeline.
Project (1).ipynb - Load Data · Reads the CSV into a working dataframe.
Project (1).ipynb - Clean Data · Removes missing, cancelled, negative-quantity, and zero-price records and normalizes dates.
Project (1).ipynb - Total Price · Derived transaction value computed as Quantity × UnitPrice.
Project (1).ipynb - EDA · Explores sales patterns, distributions, top countries, top products, and monthly trends.
Project (1).ipynb - Transaction Table · Analysis-ready transaction-level data after cleaning and basic feature derivation.
Project (1).ipynb - Results · Interactive charts, cluster assignments, and model evaluation shown in the notebook.
Project (1).ipynb
Segmentation
Unsupervised customer segmentation branch built from RFM features.
- RFM Builder · Aggregates transactions into customer-level Recency, Frequency, and Monetary features.
Project (1).ipynb - RFM Matrix · Customer behavior matrix used by both clustering and classification branches.
Project (1).ipynb - Scaler · Standardizes RFM features before clustering.
Project (1).ipynb - Cluster Tuning · Uses elbow method and silhouette score to choose cluster count.
Project (1).ipynb - K-Means · Unsupervised model that assigns customer segment labels.
Project (1).ipynb - Segment Labels · Cluster assignments produced for each customer.
Project (1).ipynb - PCA Plot · Projects customer features to two dimensions for segment visualization.
Project (1).ipynb
Prediction
Supervised branch that learns to predict cluster membership.
- Random Forest · Supervised model trained to predict segment membership from customer features.
Project (1).ipynb
Connections 20
- Online Retail.csv → Load Data: read · Notebook loads the retail CSV.
- Notebook → Load Data: run · Notebook orchestrates ingestion.
- Load Data → Clean Data: clean · Raw transactions are filtered and normalized.
- Clean Data → Total Price: derive · Transaction value is computed from quantity and price.
- Total Price → Transaction Table: build · Clean transaction table is prepared for downstream analysis.
- Transaction Table → EDA: analyze · Clean data supports exploratory analysis.
- Transaction Table → RFM Builder: aggregate · Transactions are collapsed to customer level.
- RFM Builder → RFM Matrix: form · RFM features are assembled into a customer matrix.
- RFM Matrix → Scaler: scale · Features are standardized for clustering.
- Scaler → Cluster Tuning: tune · Cluster count is selected using evaluation metrics.
- Scaler → K-Means: cluster · Scaled RFM features feed K-Means.
- Cluster Tuning → K-Means: configure · Selected cluster count guides the final clustering run.
- K-Means → Segment Labels: assign · K-Means produces segment labels.
- Segment Labels → PCA Plot: project · PCA compresses segments for visualization.
- RFM Matrix → Random Forest: train on · RFM features are used to learn cluster prediction.
- Segment Labels → Random Forest: target · Cluster labels become the supervised classes.
- K-Means → Results: report · Segmentation results are displayed in the notebook.
- Random Forest → Results: evaluate · Classifier performance and predictions are reported interactively.
- EDA → Results: show · EDA charts are part of the notebook outputs.
- PCA Plot → Results: show · PCA plots help interpret segment structure.