# souley225/customer_segmentation_project architecture

> Architecture diagram of the GitHub repository souley225/customer_segmentation_project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/souley225/customer_segmentation_project
- Repository: https://github.com/souley225/customer_segmentation_project

## Overview

##### Project type and purpose
- This is a full-stack, modular Data Science application in Python.
- Purpose: run a reproducible RFM segmentation + Market-Basket Analysis pipeline and expose results in an interactive Streamlit dashboard for customer segmentation and product cross-sell/upsell recommendations.

##### File structure
─ Top-level:
app.py            → entry point redirecting to the Streamlit app
config/           → YAML config (paths, thresholds, parameters)
models/           → serialized outputs (rfm_segments.csv, association_rules.csv, metadata.json)
src/              → core pipeline modules (data_cleaning, rfm_segmentation, basket_analysis, recommendation, visualization, utils)
requirements.txt  → list of Python dependencies
─ app/
├─ streamlit_app.py   → UI layer
├─ components/        → reusable UI widgets
└─ assets/            → static assets (images, CSS)
─ Note: There is no external database yet, data is read from files (raw → interim → processed).

##### README for additional insights
- Describes four main stages:
1. Data cleaning
2. RFM segmentation
3. Market Basket Analysis (Apriori)
4. Streamlit Dashboard
- Specifies reproducibility, modularity, and possible future FastAPI or SQL store additions.

a. Main components
- Configuration loader
- Data pipeline:
– Data Cleaning module
– RFM Segmentation module
– Basket Analysis module
– Recommendation engine
– Visualization utilities
- Storage:
– Raw / interim / processed data folders
– models/ output store (CSV, JSON)
- Frontend:
– Streamlit app (app/streamlit_app.py + components)
- (Future) API layer (FastAPI) and relational DB

b. Relationships and interactions
1. At startup, Streamlit app reads config.yaml via utils
2. Streamlit UI triggers pipeline scripts in src/ (or loads cached outputs from models/)
3. Data flows:
raw data → data_cleaning → interim/processed files → rfm_segmentation → segments output → basket_analysis → association_rules → recommendation → displayed charts
4. Visualization utilities produce Plotly graphs fed into Streamlit
5. Models folder acts as a persistent cache between pipeline runs

c. Architectural patterns & principles
- Modular separation: config, data-processing, UI, assets, model outputs
- Pipeline pattern: sequential ETL + ML modules
- Single-page interactive UI via Streamlit
- Clear separation of concerns: utils for logging/config, core logic in src, presentation in app/

d. Technologies / frameworks
- Python 3.x with pandas, numpy, scikit-learn, mlxtend, plotly
- Streamlit for frontend
- PyYAML for config
- File-based “database” (CSV / JSON), with future option for FastAPI + PostgreSQL

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Define layers
    subgraph "Backend Pipeline"
        direction TB
        CFG["Config Loader"]:::utils
        DC["Data Cleaning Module"]:::processing
        RFM["RFM Segmentation Module"]:::processing
        BA["Basket Analysis Module"]:::processing
        REC["Recommendation Engine"]:::processing
        VIZ["Visualization Utilities"]:::processing
    end

    subgraph "Storage"
        direction TB
        RAW["Raw Data"]:::storage
        INTERIM["Interim/Processed Data"]:::storage
        MODELS["models/ (Cache)"]:::storage
    end

    subgraph "Frontend Layer"
        direction TB
        APP["Streamlit Dashboard"]:::frontend
    end

    %% Backend pipeline flow
    CFG -->|reads config.yaml| DC
    CFG -->|injects config| RFM
    CFG -->|injects config| BA
    CFG -->|injects config| REC
    CFG -->|injects config| VIZ

    DC -->|"cleaned.csv"| RFM
    RFM -->|"segments.csv"| BA
    BA -->|"association_rules.csv"| REC
    REC -->|"recommendations"| VIZ

    %% Storage interactions
    RAW -->|raw data input| DC
    DC -->|writes interim| INTERIM
    INTERIM -->|processed input| RFM
    RFM -->|writes segments| MODELS
    BA -->|writes rules| MODELS
    VIZ -->|reads cache| MODELS

    %% Frontend interactions
    APP -->|triggers pipeline or loads cache| DC
    APP -->|displays charts| VIZ

    %% Click events
    click CFG "https://github.com/souley225/customer_segmentation_project/blob/master/config/config.yaml"
    click CFG "https://github.com/souley225/customer_segmentation_project/blob/master/src/utils.py"
    click DC "https://github.com/souley225/customer_segmentation_project/blob/master/src/data_cleaning.py"
    click RFM "https://github.com/souley225/customer_segmentation_project/blob/master/src/rfm_segmentation.py"
    click BA "https://github.com/souley225/customer_segmentation_project/blob/master/src/basket_analysis.py"
    click REC "https://github.com/souley225/customer_segmentation_project/blob/master/src/recommendation.py"
    click VIZ "https://github.com/souley225/customer_segmentation_project/blob/master/src/visualization.py"
    click APP "https://github.com/souley225/customer_segmentation_project/blob/master/app/streamlit_app.py"
    click APP "https://github.com/souley225/customer_segmentation_project/blob/master/app.py"
    click MODELS "https://github.com/souley225/customer_segmentation_project/tree/master/models/"

    %% Styles
    classDef processing fill:#E0F7FA,stroke:#0288D1,stroke-width:2px
    classDef storage fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px
    classDef frontend fill:#FFF3E0,stroke:#F57C00,stroke-width:2px
    classDef utils fill:#F3E5F5,stroke:#6A1B9A,stroke-width:2px
```
