# shubham-soni-coder/telso_churm_eda architecture

> Architecture diagram of the GitHub repository shubham-soni-coder/telso_churm_eda, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shubham-soni-coder/telso_churm_eda
- Repository: https://github.com/shubham-soni-coder/telso_churm_eda

## Overview

1. **Repository type and scope**
   This is a single-purpose **exploratory data analysis (EDA)** repository, not an application or service. The architecture is a **notebook-centered data pipeline** that loads a telecom churn dataset, cleans it, performs analysis, and produces visual/report artifacts.

2. **Primary input boundary**
   The main input is **`Telso_churm_data.csv`**, a flat file containing customer records and churn labels. It is the only explicit data source in the repo, so the entire analysis flow is file-driven rather than database- or API-driven.

3. **Execution environment**
   The core runtime is **Python in Jupyter Notebook**. The analysis appears to live in **`main.ipynb`**, which acts as both the computation layer and the presentation layer for results.

4. **Data processing subsystem**
   The notebook uses **Pandas** and **NumPy** for ingesting, inspecting, and transforming the tabular dataset. This layer handles:
   - schema inspection and type checking
   - missing-value treatment
   - duplicate validation
   - basic feature transformation

5. **Data quality handling**
   A key preprocessing step is the cleanup of **`TotalCharges`**, where blank values are replaced with `0` and the column is converted to numeric. Another transformation maps **`SeniorCitizen`** from numeric flags to human-readable labels (`Yes`/`No`) to support clearer analysis and plotting.

6. **EDA and analytics subsystem**
   The analytical core is descriptive rather than predictive. The notebook studies churn through segmented views such as:
   - overall churn distribution
   - customer tenure vs churn
   - contract type vs churn
   - senior citizen vs non-senior behavior
   - service adoption vs churn

7. **Visualization layer**
   **Matplotlib** and **Seaborn** provide the charting layer. They turn the cleaned data into count plots, pie charts, histograms, stacked bars, and heatmaps. In architectural terms, this is the presentation boundary that converts tabular analysis into interpretable business visuals.

8. **Output artifacts**
   The repo produces two main outputs:
   - the executed notebook itself, which contains the analysis narrative and embedded plots
   - **`analysis_summary.pdf`**, a static report artifact for sharing results outside the notebook environment

9. **Data flow**
   The end-to-end flow is straightforward:  
   **CSV dataset → notebook ingestion → cleaning/transformation → exploratory segmentation → visual summaries → PDF/notebook outputs**.  
   There is no feedback loop, model training pipeline, or external service integration.

10. **System boundaries**
   The important boundary is between **raw customer data** and **interpreted business insight**. The repo stops at insight generation; it does not include production scoring, deployment, dashboards, or persistence layers. That makes the architecture a **local analytical workflow** rather than an operational churn system.

11. **Project structure implications**
   The repo is intentionally minimal: one dataset, one notebook, one report, and the README. That means the architecture is centralized and easy to diagram as a **single notebook-driven analysis stack** with one input source and two output artifacts.

12. **Business focus**
   The analysis is centered on retention signals rather than technical complexity. The key domain factors surfaced by the notebook are contract length, tenure, age group, and service bundle adoption, which are the main business dimensions to represent in any architecture diagram.

Main entry points: [`main.ipynb`](https://github.com/shubham-soni-coder/telso_churm_eda/blob/main/main.ipynb) (Main notebook), [`analysis_summary.pdf`](https://github.com/shubham-soni-coder/telso_churm_eda/blob/main/analysis_summary.pdf) (PDF report), [`Telso_churm_data.csv`](https://github.com/shubham-soni-coder/telso_churm_eda/blob/main/Telso_churm_data.csv) (Churn data), [`README.md`](https://github.com/shubham-soni-coder/telso_churm_eda/blob/main/README.md) (README)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs"]
  node_dataset[("Churn data<br/>csv dataset")]
end

subgraph group_notebook["Notebook workflow"]
  node_notebook_main["Main notebook<br/>jupyter notebook<br/>[main.ipynb]"]
  node_ingest["Ingest<br/>pandas load"]
  node_clean["Clean data<br/>prep transform"]
  node_feature_fix["Feature fixes<br/>feature transform"]
  node_eda["Churn analysis<br/>descriptive EDA"]
  node_viz["Charts<br/>visualization layer"]
end

node_readme["README<br/>repo overview<br/>[README.md]"]
node_report["PDF report<br/>static artifact"]

node_readme -->|"documents"| node_notebook_main
node_dataset -->|"input"| node_notebook_main
node_notebook_main -->|"starts"| node_ingest
node_ingest -->|"feeds"| node_clean
node_clean -->|"refines"| node_feature_fix
node_feature_fix -->|"enables"| node_eda
node_eda -->|"renders"| node_viz
node_viz -->|"embeds"| node_notebook_main
node_viz -->|"exports"| node_report
node_notebook_main -->|"produces"| node_report

click node_readme "https://github.com/shubham-soni-coder/telso_churm_eda/blob/main/README.md"
click node_dataset "https://github.com/shubham-soni-coder/telso_churm_eda/blob/main/Telso_churm_data.csv"
click node_notebook_main "https://github.com/shubham-soni-coder/telso_churm_eda/blob/main/main.ipynb"
click node_report "https://github.com/shubham-soni-coder/telso_churm_eda/blob/main/analysis_summary.pdf"

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_dataset toneBlue
class node_notebook_main,node_ingest,node_clean,node_feature_fix,node_eda,node_viz toneAmber
class node_readme,node_report toneNeutral
```

## Components

### Inputs

Raw source data for the analysis

- [Churn data](https://github.com/shubham-soni-coder/telso_churm_eda/blob/main/Telso_churm_data.csv): csv dataset · Raw telecom customer records and churn labels · `Telso_churm_data.csv`

### Notebook workflow

Notebook-centered cleaning, analysis, and reporting

- [Main notebook](https://github.com/shubham-soni-coder/telso_churm_eda/blob/main/main.ipynb): jupyter notebook · Primary execution and presentation layer · `main.ipynb`
- **Ingest**: pandas load · Loads and inspects the tabular dataset
- **Clean data**: prep transform · Handles blanks, type conversion, and duplicates
- **Feature fixes**: feature transform · Normalizes TotalCharges and maps SeniorCitizen labels
- **Churn analysis**: descriptive EDA · Segments churn by tenure, contract, senior status, and services
- **Charts**: visualization layer · Builds plots, histograms, stacked bars, and heatmaps

### Other components

- [README](https://github.com/shubham-soni-coder/telso_churm_eda/blob/main/README.md): repo overview · Project summary and usage context · `README.md`
- [PDF report](https://github.com/shubham-soni-coder/telso_churm_eda/blob/main/analysis_summary.pdf): static artifact · Exported summary for sharing outside the notebook · `analysis_summary.pdf`

## Connections

- README → Main notebook: documents · Describes the notebook-driven workflow
- Churn data → Main notebook: input · Raw churn records feed the notebook
- Main notebook → Ingest: starts · Notebook begins by loading the dataset
- Ingest → Clean data: feeds · Loaded data is checked and prepared
- Clean data → Feature fixes: refines · Preprocessing applies field-specific corrections
- Feature fixes → Churn analysis: enables · Cleaned features support segmented analysis
- Churn analysis → Charts: renders · Analytical slices are turned into charts
- Charts → Main notebook: embeds · Plots and narrative live in the executed notebook
- Charts → PDF report: exports · Visual findings are packaged into a PDF summary
- Main notebook → PDF report: produces · The notebook execution yields the shareable report artifact