# aryan-s08/customer-segmentation architecture
> Architecture diagram of the GitHub repository aryan-s08/customer-segmentation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.
- Interactive diagram: https://gitdiagram.com/aryan-s08/customer-segmentation
- Repository: https://github.com/aryan-s08/customer-segmentation
## Overview
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`](https://github.com/aryan-s08/customer-segmentation/blob/HEAD/Project%20(1).ipynb) (K-Means)
## Diagram (Mermaid)
```mermaid
flowchart TD
subgraph group_g1["Input Data"]
node_n1[("Online Retail.csv
dataset")]
end
subgraph group_g2["Notebook Pipeline"]
node_n2["Notebook
orchestrator
[Project (1).ipynb]"]
node_n3["Load Data
ingest step
[Project (1).ipynb]"]
node_n4["Clean Data
prep step
[Project (1).ipynb]"]
node_n5["Total Price
feature
[Project (1).ipynb]"]
node_n6["EDA
analysis
[Project (1).ipynb]"]
node_n7["Transaction Table
clean data
[Project (1).ipynb]"]
node_n16["Results
outputs
[Project (1).ipynb]"]
end
subgraph group_g3["Segmentation"]
node_n8["RFM Builder
aggregation
[Project (1).ipynb]"]
node_n9["RFM Matrix
feature table
[Project (1).ipynb]"]
node_n10["Scaler
preprocessor
[Project (1).ipynb]"]
node_n11["Cluster Tuning
evaluation
[Project (1).ipynb]"]
node_n12["K-Means
clusterer
[Project (1).ipynb]"]
node_n13["Segment Labels
[Project (1).ipynb]"]
node_n14["PCA Plot
visualization
[Project (1).ipynb]"]
end
subgraph group_g4["Prediction"]
node_n15["Random Forest
classifier
[Project (1).ipynb]"]
end
node_n1 -->|"read"| node_n3
node_n2 -->|"run"| node_n3
node_n3 -->|"clean"| node_n4
node_n4 -->|"derive"| node_n5
node_n5 -->|"build"| node_n7
node_n7 -->|"analyze"| node_n6
node_n7 -->|"aggregate"| node_n8
node_n8 -->|"form"| node_n9
node_n9 -->|"scale"| node_n10
node_n10 -->|"tune"| node_n11
node_n10 -->|"cluster"| node_n12
node_n11 -->|"configure"| node_n12
node_n12 -->|"assign"| node_n13
node_n13 -->|"project"| node_n14
node_n9 -->|"train on"| node_n15
node_n13 -->|"target"| node_n15
node_n12 -->|"report"| node_n16
node_n15 -->|"evaluate"| node_n16
node_n6 -->|"show"| node_n16
node_n14 -->|"show"| node_n16
click node_n2 "https://github.com/aryan-s08/customer-segmentation/blob/main/Project (1).ipynb"
click node_n3 "https://github.com/aryan-s08/customer-segmentation/blob/main/Project (1).ipynb"
click node_n4 "https://github.com/aryan-s08/customer-segmentation/blob/main/Project (1).ipynb"
click node_n5 "https://github.com/aryan-s08/customer-segmentation/blob/main/Project (1).ipynb"
click node_n6 "https://github.com/aryan-s08/customer-segmentation/blob/main/Project (1).ipynb"
click node_n7 "https://github.com/aryan-s08/customer-segmentation/blob/main/Project (1).ipynb"
click node_n8 "https://github.com/aryan-s08/customer-segmentation/blob/main/Project (1).ipynb"
click node_n9 "https://github.com/aryan-s08/customer-segmentation/blob/main/Project (1).ipynb"
click node_n10 "https://github.com/aryan-s08/customer-segmentation/blob/main/Project (1).ipynb"
click node_n11 "https://github.com/aryan-s08/customer-segmentation/blob/main/Project (1).ipynb"
click node_n12 "https://github.com/aryan-s08/customer-segmentation/blob/main/Project (1).ipynb"
click node_n13 "https://github.com/aryan-s08/customer-segmentation/blob/main/Project (1).ipynb"
click node_n14 "https://github.com/aryan-s08/customer-segmentation/blob/main/Project (1).ipynb"
click node_n15 "https://github.com/aryan-s08/customer-segmentation/blob/main/Project (1).ipynb"
click node_n16 "https://github.com/aryan-s08/customer-segmentation/blob/main/Project (1).ipynb"
classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n1 toneBlue
class node_n2,node_n3,node_n4,node_n5,node_n6,node_n7,node_n16 toneAmber
class node_n8,node_n9,node_n10,node_n11,node_n12,node_n13,node_n14 toneMint
class node_n15 toneRose
```
## Components
### Input Data
Local retail transaction dataset used as the only external input.
- **Online Retail.csv**: dataset · 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](https://github.com/aryan-s08/customer-segmentation/blob/HEAD/Project%20(1).ipynb): orchestrator · Jupyter execution environment that runs the full analysis pipeline. · `Project (1).ipynb`
- [Load Data](https://github.com/aryan-s08/customer-segmentation/blob/HEAD/Project%20(1).ipynb): ingest step · Reads the CSV into a working dataframe. · `Project (1).ipynb`
- [Clean Data](https://github.com/aryan-s08/customer-segmentation/blob/HEAD/Project%20(1).ipynb): prep step · Removes missing, cancelled, negative-quantity, and zero-price records and normalizes dates. · `Project (1).ipynb`
- [Total Price](https://github.com/aryan-s08/customer-segmentation/blob/HEAD/Project%20(1).ipynb): feature · Derived transaction value computed as Quantity × UnitPrice. · `Project (1).ipynb`
- [EDA](https://github.com/aryan-s08/customer-segmentation/blob/HEAD/Project%20(1).ipynb): analysis · Explores sales patterns, distributions, top countries, top products, and monthly trends. · `Project (1).ipynb`
- [Transaction Table](https://github.com/aryan-s08/customer-segmentation/blob/HEAD/Project%20(1).ipynb): clean data · Analysis-ready transaction-level data after cleaning and basic feature derivation. · `Project (1).ipynb`
- [Results](https://github.com/aryan-s08/customer-segmentation/blob/HEAD/Project%20(1).ipynb): outputs · 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](https://github.com/aryan-s08/customer-segmentation/blob/HEAD/Project%20(1).ipynb): aggregation · Aggregates transactions into customer-level Recency, Frequency, and Monetary features. · `Project (1).ipynb`
- [RFM Matrix](https://github.com/aryan-s08/customer-segmentation/blob/HEAD/Project%20(1).ipynb): feature table · Customer behavior matrix used by both clustering and classification branches. · `Project (1).ipynb`
- [Scaler](https://github.com/aryan-s08/customer-segmentation/blob/HEAD/Project%20(1).ipynb): preprocessor · Standardizes RFM features before clustering. · `Project (1).ipynb`
- [Cluster Tuning](https://github.com/aryan-s08/customer-segmentation/blob/HEAD/Project%20(1).ipynb): evaluation · Uses elbow method and silhouette score to choose cluster count. · `Project (1).ipynb`
- [K-Means](https://github.com/aryan-s08/customer-segmentation/blob/HEAD/Project%20(1).ipynb): clusterer · Unsupervised model that assigns customer segment labels. · `Project (1).ipynb`
- [Segment Labels](https://github.com/aryan-s08/customer-segmentation/blob/HEAD/Project%20(1).ipynb): labels · Cluster assignments produced for each customer. · `Project (1).ipynb`
- [PCA Plot](https://github.com/aryan-s08/customer-segmentation/blob/HEAD/Project%20(1).ipynb): visualization · Projects customer features to two dimensions for segment visualization. · `Project (1).ipynb`
### Prediction
Supervised branch that learns to predict cluster membership.
- [Random Forest](https://github.com/aryan-s08/customer-segmentation/blob/HEAD/Project%20(1).ipynb): classifier · Supervised model trained to predict segment membership from customer features. · `Project (1).ipynb`
## Connections
- 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.