# sohelraja/customer-churn-analysis architecture

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

- Interactive diagram: https://gitdiagram.com/sohelraja/customer-churn-analysis
- Repository: https://github.com/sohelraja/customer-churn-analysis

## Overview

##### Project Type and Purpose
- This is a data-science pipeline project (Customer-Churn-Analysis) implemented in Jupyter notebooks.
- Purpose: ingest telecom customer data, clean it, explore with Decision Trees, Clustering (Kmodes/Kprototypes), Association Rule Mining (Apriori), select best features, train multiple classifiers, then combine them in a Voting Ensemble to predict churn.

##### File-Structure Analysis
- Top-level directories map to pipeline stages:
- Datasets – raw and preprocessed CSV/XLSX files
- Decision Tree – notebooks for initial classification & feature importance
- Clustering – notebooks for Kmodes/Kprototypes cluster analysis
- Association Rule Mining – notebooks for Apriori rule extraction
- Ensemble Learning
– Other Classifiers – subfolders for Decision Tree, KNN, Logistic Regression, Naive Bayes, Random Forest, SVC
– Voting Classifier – notebook combining models
- Snapshots – images of workflow, graphs, metrics
- Key configuration: .gitignore for notebook artifacts; no service-oriented or deployment files – it’s an exploratory/analytical pipeline.

##### Insights from README
- Explicit modeling steps: data collection → preprocessing → Decision Tree → Clustering & Association Rules → feature selection → classifier comparison → voting ensemble → final accuracy & graphs.

a. Main Components
1. Data Sources
– WA_Fn-UseC_-Telco-Customer-Churn.csv (raw)
– new_telco.csv (preprocessed)
2. Data Preprocessing Module
– Jupyter notebooks handling cleaning, dummy encoding
3. Modeling Modules
- Decision Tree Classifier (initial feature ranking)
- Clustering Module (Kmodes & K-prototypes)
- Association Rule Mining Module (Apriori)
4. Feature Selection Component
– Intersection of top features from Decision Tree, Clustering, Association Rules
5. Classifier Modules (Other Classifiers)
– Decision Tree, KNN, Logistic Regression, Naive Bayes, Random Forest, SVC
6. Voting Ensemble Module
– Combines selected classifiers into a final predictor
7. Visualization & Reporting
– Snapshots folder holds graphs, workflow images, accuracy reports

b. Relationships & Data Flows
- Preprocessing → all three modeling modules in parallel
- Each modeling module outputs feature importance/cluster centroids/rules → Feature Selection
- Feature Selection → feeds datasets into each Other Classifier
- Outputs (accuracy metrics) from each classifier → Voting Ensemble
- Final predictions & metrics → Visualization & Reporting

c. Architectural Patterns & Principles
- Pipeline pattern: sequential & parallel stages
- Modularity: each algorithm in its own directory/notebook
- Data-centric flow: single source of truth (preprocessed CSV)
- Separation of concerns: modeling vs. feature selection vs. ensemble

d. Technologies & Libraries
- Jupyter Notebooks (presentation + code)
- Python (pandas, scikit-learn, mlxtend for Apriori, kmodes package)
- Visualization: matplotlib/seaborn (embedded in notebooks)

##### Detail
- Every high-level stage and its inputs/outputs.
- Modules with core libraries (e.g., scikit-learn) to show tech stack.
- Iterative nature: e.g., after Voting Ensemble, feedback loop could trigger hyperparameter tuning (future scope).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Artifacts
    subgraph "Data Sources"
        direction TB
        RawDataset(("WA_Fn-UseC_-Telco-Customer-Churn.csv")):::data
        PreprocessedDataset(("new_telco.csv")):::data
    end

    %% Preprocessing
    subgraph "Data Preprocessing Module"
        direction TB
        Preprocessing["Preprocessing Notebooks"]:::process
    end

    %% Modeling Modules
    subgraph "Modeling Modules"
        direction TB
        DTModule["Decision Tree Module"]:::process
        ClusteringModule["Clustering Module\n(Kmodes & K-prototypes)"]:::process
        ARMModule["Association Rule Mining Module"]:::process
    end

    %% Feature Selection
    FeatureSelection["Feature Selection Component"]:::process

    %% Other Classifiers
    subgraph "Other Classifiers"
        direction TB
        DTClassifier["Decision Tree Classifier"]:::process
        KNNClassifier["KNN Classifier"]:::process
        LRClassifier["Logistic Regression Classifier"]:::process
        NBClassifier["Naive Bayes Classifier"]:::process
        RFClassifier["Random Forest Classifier"]:::process
        SVCClassifier["SVC Classifier"]:::process
    end

    %% Voting Ensemble
    VotingEnsemble["Voting Ensemble Module"]:::process

    %% Visualization & Reporting
    Visualization["Visualization & Reporting\n(Snapshots)"]:::viz

    %% Data Flows
    RawDataset -->|ingest CSV| Preprocessing
    Preprocessing -->|outputs new_telco.csv| PreprocessedDataset
    PreprocessedDataset -->|pandas DataFrame| DTModule
    PreprocessedDataset -->|pandas DataFrame| ClusteringModule
    PreprocessedDataset -->|pandas DataFrame| ARMModule

    DTModule -->|top features| FeatureSelection
    ClusteringModule -->|cluster centroids & rules| FeatureSelection
    ARMModule -->|association rules| FeatureSelection

    FeatureSelection -->|selected features| DTClassifier
    FeatureSelection -->|selected features| KNNClassifier
    FeatureSelection -->|selected features| LRClassifier
    FeatureSelection -->|selected features| NBClassifier
    FeatureSelection -->|selected features| RFClassifier
    FeatureSelection -->|selected features| SVCClassifier

    DTClassifier --> VotingEnsemble
    KNNClassifier --> VotingEnsemble
    LRClassifier --> VotingEnsemble
    NBClassifier --> VotingEnsemble
    RFClassifier --> VotingEnsemble
    SVCClassifier --> VotingEnsemble

    VotingEnsemble -->|final predictions & metrics| Visualization

    %% Click Events
    click RawDataset "https://github.com/sohelraja/customer-churn-analysis/blob/master/Datasets/WA_Fn-UseC_-Telco-Customer-Churn.csv"
    click PreprocessedDataset "https://github.com/sohelraja/customer-churn-analysis/blob/master/Datasets/new_telco.csv"
    click Preprocessing "https://github.com/sohelraja/customer-churn-analysis/blob/master/Decision Tree/new_telco.csv"
    click DTModule "https://github.com/sohelraja/customer-churn-analysis/blob/master/Decision Tree/Decision_Tree_Customer_Churn.ipynb"
    click DTModule "https://github.com/sohelraja/customer-churn-analysis/blob/master/Decision Tree/Decision_Tree_Customer_Churn_v3.ipynb"
    click DTModule "https://github.com/sohelraja/customer-churn-analysis/blob/master/Decision Tree/Decision_Tree_Customer_Churn(final).ipynb"
    click ClusteringModule "https://github.com/sohelraja/customer-churn-analysis/blob/master/Clustering/Clustering(Kmodes_&_Kprototypes).ipynb"
    click ClusteringModule "https://github.com/sohelraja/customer-churn-analysis/blob/master/Clustering/Clustering(K_Prototype).ipynb"
    click ARMModule "https://github.com/sohelraja/customer-churn-analysis/blob/master/Association Rule Mining/AssociationRuleMining(On_original_dataset) (1).ipynb"
    click ARMModule "https://github.com/sohelraja/customer-churn-analysis/blob/master/Association Rule Mining/AssociationRuleMining(On_clusters).ipynb"
    click FeatureSelection "https://github.com/sohelraja/customer-churn-analysis/blob/master/Ensemble Learning/Other Classifiers/Decision Tree/Decision_Tree_Customer_Churn_best_features.ipynb"
    click DTClassifier "https://github.com/sohelraja/customer-churn-analysis/blob/master/Ensemble Learning/Other Classifiers/Decision Tree/Decision_Tree_Customer_Churn_best_features.ipynb"
    click KNNClassifier "https://github.com/sohelraja/customer-churn-analysis/blob/master/Ensemble Learning/Other Classifiers/KNN/KNNonChurnDataset.ipynb"
    click LRClassifier "https://github.com/sohelraja/customer-churn-analysis/blob/master/Ensemble Learning/Other Classifiers/Logistic Regression/LogisticRegressionClassifier.ipynb"
    click NBClassifier "https://github.com/sohelraja/customer-churn-analysis/blob/master/Ensemble Learning/Other Classifiers/Naive Bayes/Naive_bayes_Classifier.ipynb"
    click RFClassifier "https://github.com/sohelraja/customer-churn-analysis/blob/master/Ensemble Learning/Other Classifiers/Random Forest/Random_Forest_Classifier_Customer_Churn_v1.ipynb"
    click SVCClassifier "https://github.com/sohelraja/customer-churn-analysis/blob/master/Ensemble Learning/Other Classifiers/SVC/SVConChurnDataset.ipynb"
    click VotingEnsemble "https://github.com/sohelraja/customer-churn-analysis/blob/master/Ensemble Learning/Voting Classifier/VotingClassifier.ipynb"
    click Visualization "https://github.com/sohelraja/customer-churn-analysis/tree/master/Snapshots/"

    %% Styles
    classDef data fill:#CFE2F3,stroke:#6C8EBF,color:#0B5394;
    classDef process fill:#D9EAD3,stroke:#6AA84F,color:#274E13;
    classDef viz fill:#FCE5CD,stroke:#E69138,color:#734C00;
```
