# dmehta2396/segmentation_analysis_v2 architecture

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

- Interactive diagram: https://gitdiagram.com/dmehta2396/segmentation_analysis_v2
- Repository: https://github.com/dmehta2396/segmentation_analysis_v2

## Overview

1. This repository is a Python batch-analysis pipeline for segmenting entities by month and comparing how they move over time. It is not an application server; the main execution path is from command-line scripts into analysis modules that produce HTML and Excel deliverables.

2. The architecture is organized around three analysis phases:
   - Phase 00: data understanding and quality checks
   - Phase 01: base-month vs current-month comparison
   - Phase 02: movement analysis across segments
   Each phase is isolated under `analysis/phase_XX/`, which makes the phases the main functional boundaries in the system.

3. The `scripts/` directory is the orchestration layer. `run_phase_00.py`, `run_phase_01.py`, and `run_phase_02.py` act as entry points that select a phase, load data, run the corresponding analysis steps, and trigger output generation. `generate_data.py` is a supporting utility for creating sample input data.

4. Core data handling lives in `src/`. `data_loader.py` is the ingestion boundary for reading source files, `data_generator.py` supports synthetic or sample data creation, `validators.py` handles integrity checks, and `utils.py` contains shared helpers. This layer is the primary bridge between raw CSV inputs and the phase-specific analytics.

5. Configuration is centralized in `config/settings.py`, which likely defines column mappings, month selections, file naming conventions, and display colors. This matters architecturally because the rest of the pipeline appears to be schema-driven rather than hardcoded to one dataset layout.

6. `analysis/phase_00/` focuses on exploratory and diagnostic outputs: dataset overview, base month distribution, selected month inspection, data quality, metrics overview, and reference data. This phase establishes the baseline context and validates the inputs before comparison or movement analysis.

7. `analysis/phase_01/` contains the base-vs-current comparison logic, with `base_vs_current.py` as the main module. This phase compares entity counts and segment composition between two time points, producing growth/decline summaries and ranking changes. It acts as the bridge between descriptive profiling and movement-focused analysis.

8. `analysis/phase_02/` is the most specialized subsystem. `movement_core.py` appears to hold shared transition logic used by modules for movement matrix, new entities, lost entities, movement analysis, Sankey diagram generation, and summary reporting. This suggests a shared computation kernel feeding multiple visual/report outputs.

9. Visualization concerns are separated into `visualizations/`. `charts.py` likely contains reusable Plotly chart builders, while `styles.py` centralizes consistent formatting and color themes. That separation keeps analysis code focused on business logic and reduces duplication across phases.

10. Exporting is handled independently in `exports/excel_exporter.py`, which indicates that Excel generation is a first-class output path rather than an afterthought. The separation of HTML visualization generation and XLSX export means each analysis can emit both interactive and tabular artifacts from the same computed result set.

11. The data flow is straightforward: raw input data is loaded and validated, normalized using config mappings, processed by a phase module, rendered into Plotly-based visual outputs, and exported to formatted spreadsheets. The README’s `data/raw`, `data/processed`, and `outputs/phase_XX/{html,xlsx}` conventions describe the persistence boundaries of that flow.

12. Overall, the architecture is a layered offline analytics pipeline: configuration at the top, shared ingestion/validation in `src/`, phase-specific analytical computation in `analysis/`, reusable presentation logic in `visualizations/`, and output generation in `exports/`. An architecture diagram should emphasize the three analysis phases as parallel consumers of the same core data layer and config, with outputs split into HTML and Excel artifacts.

Main entry points: [`scripts/run_phase_02.py`](https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/scripts/run_phase_02.py) (Run phase 02), [`scripts/run_phase_00.py`](https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/scripts/run_phase_00.py) (Run phase 00), [`config/settings.py`](https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/config/settings.py) (Settings), [`src/data_loader.py`](https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/src/data_loader.py) (Data loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_scripts["Scripts"]
  node_scripts_run_phase_00["Run phase 00<br/>cli entrypoint<br/>[run_phase_00.py]"]
  node_scripts_run_phase_01["Run phase 01<br/>cli entrypoint<br/>[run_phase_01.py]"]
  node_scripts_run_phase_02["Run phase 02<br/>cli entrypoint<br/>[run_phase_02.py]"]
end

subgraph group_group_config["Config"]
  node_config_settings["Settings<br/>config schema<br/>[settings.py]"]
end

subgraph group_group_src["Core data"]
  node_src_data_loader[("Data loader<br/>ingestion<br/>[data_loader.py]")]
  node_src_validators["Validators<br/>integrity checks<br/>[validators.py]"]
  node_src_utils["Utils<br/>shared helpers<br/>[utils.py]"]
  node_src_data_generator["Data generator<br/>sample data<br/>[data_generator.py]"]
end

subgraph group_group_phase00["Phase 00"]
  node_phase00_overview["Overview<br/>profiling report"]
  node_phase00_quality["Quality checks<br/>diagnostics<br/>[d_data_quality.py]"]
  node_phase00_reference["Reference data<br/>reference lookup"]
end

subgraph group_group_phase01["Phase 01"]
  node_phase01_compare["Base vs current<br/>comparison analysis<br/>[base_vs_current.py]"]
end

subgraph group_group_phase02["Phase 02"]
  node_phase02_core["Movement core<br/>transition kernel<br/>[movement_core.py]"]
  node_phase02_matrix["Movement matrix<br/>transition report"]
  node_phase02_new["New entities<br/>movement report<br/>[b_new_entities.py]"]
  node_phase02_lost["Lost entities<br/>movement report<br/>[c_lost_entities.py]"]
  node_phase02_analysis["Movement analysis"]
  node_phase02_sankey["Sankey diagram<br/>visual report"]
  node_phase02_summary["Summary"]
end

subgraph group_group_visuals["Visuals"]
  node_viz_charts["Charts<br/>plot builders<br/>[charts.py]"]
  node_viz_styles["Styles<br/>theme config<br/>[styles.py]"]
end

subgraph group_group_exports["Exports"]
  node_exports_excel[("Excel export<br/>xlsx exporter<br/>[excel_exporter.py]")]
end

node_scripts_run_phase_00 -->|"loads settings"| node_config_settings
node_scripts_run_phase_00 -->|"loads data"| node_src_data_loader
node_scripts_run_phase_00 -->|"validates"| node_src_validators
node_scripts_run_phase_00 -->|"runs"| node_phase00_overview
node_scripts_run_phase_00 -->|"runs"| node_phase00_quality
node_scripts_run_phase_00 -->|"runs"| node_phase00_reference
node_scripts_run_phase_01 -->|"loads settings"| node_config_settings
node_scripts_run_phase_01 -->|"loads data"| node_src_data_loader
node_scripts_run_phase_01 -->|"runs"| node_phase01_compare
node_scripts_run_phase_02 -->|"loads settings"| node_config_settings
node_scripts_run_phase_02 -->|"loads data"| node_src_data_loader
node_scripts_run_phase_02 -->|"uses core"| node_phase02_core
node_scripts_run_phase_02 -->|"runs"| node_phase02_matrix
node_scripts_run_phase_02 -->|"runs"| node_phase02_new
node_scripts_run_phase_02 -->|"runs"| node_phase02_lost
node_scripts_run_phase_02 -->|"runs"| node_phase02_analysis
node_scripts_run_phase_02 -->|"runs"| node_phase02_sankey
node_scripts_run_phase_02 -->|"runs"| node_phase02_summary
node_phase00_overview -->|"renders with"| node_viz_charts
node_phase00_quality -->|"renders with"| node_viz_charts
node_phase01_compare -->|"renders with"| node_viz_charts
node_phase02_matrix -->|"renders with"| node_viz_charts
node_phase02_sankey -->|"renders with"| node_viz_charts
node_phase00_overview -->|"applies"| node_viz_styles
node_phase01_compare -->|"applies"| node_viz_styles
node_phase02_summary -->|"applies"| node_viz_styles
node_phase00_overview -->|"exports"| node_exports_excel
node_phase01_compare -->|"exports"| node_exports_excel
node_phase02_summary -->|"exports"| node_exports_excel
node_src_data_loader -->|"passes through"| node_src_validators
node_src_data_loader -->|"uses"| node_src_utils
node_src_data_generator -->|"feeds"| node_src_data_loader
node_config_settings -->|"configures"| node_phase00_overview
node_config_settings -->|"configures"| node_phase01_compare
node_config_settings -->|"configures"| node_phase02_core

click node_scripts_run_phase_00 "https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/scripts/run_phase_00.py"
click node_scripts_run_phase_01 "https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/scripts/run_phase_01.py"
click node_scripts_run_phase_02 "https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/scripts/run_phase_02.py"
click node_config_settings "https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/config/settings.py"
click node_src_data_loader "https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/src/data_loader.py"
click node_src_validators "https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/src/validators.py"
click node_src_utils "https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/src/utils.py"
click node_src_data_generator "https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/src/data_generator.py"
click node_phase00_overview "https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/analysis/phase_00/a_dataset_overview.py"
click node_phase00_quality "https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/analysis/phase_00/d_data_quality.py"
click node_phase00_reference "https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/analysis/phase_00/f_reference_data.py"
click node_phase01_compare "https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/analysis/phase_01/base_vs_current.py"
click node_phase02_core "https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/analysis/phase_02/movement_core.py"
click node_phase02_matrix "https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/analysis/phase_02/a_movement_matrix.py"
click node_phase02_new "https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/analysis/phase_02/b_new_entities.py"
click node_phase02_lost "https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/analysis/phase_02/c_lost_entities.py"
click node_phase02_analysis "https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/analysis/phase_02/d_movement_analysis.py"
click node_phase02_sankey "https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/analysis/phase_02/e_sankey_diagram.py"
click node_phase02_summary "https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/analysis/phase_02/f_movement_summary.py"
click node_viz_charts "https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/visualizations/charts.py"
click node_viz_styles "https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/visualizations/styles.py"
click node_exports_excel "https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/exports/excel_exporter.py"

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_scripts_run_phase_00,node_scripts_run_phase_01,node_scripts_run_phase_02,node_viz_charts,node_viz_styles toneBlue
class node_config_settings,node_exports_excel toneAmber
class node_src_data_loader,node_src_validators,node_src_utils,node_src_data_generator toneMint
class node_phase00_overview,node_phase00_quality,node_phase00_reference toneRose
class node_phase01_compare toneIndigo
class node_phase02_core,node_phase02_matrix,node_phase02_new,node_phase02_lost,node_phase02_analysis,node_phase02_sankey,node_phase02_summary toneTeal
```

## Components

### Scripts

Command-line entry points and orchestration

- [Run phase 00](https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/scripts/run_phase_00.py): cli entrypoint · Starts the exploratory and quality-check workflow · `scripts/run_phase_00.py`
- [Run phase 01](https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/scripts/run_phase_01.py): cli entrypoint · Starts the base-vs-current comparison workflow · `scripts/run_phase_01.py`
- [Run phase 02](https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/scripts/run_phase_02.py): cli entrypoint · Starts the movement analysis workflow · `scripts/run_phase_02.py`

### Config

Centralized settings and schema mappings

- [Settings](https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/config/settings.py): config schema · Shared mappings, month selection, naming, and display settings · `config/settings.py`

### Core data

Ingestion, validation, shared helpers, and sample data support

- [Data loader](https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/src/data_loader.py): ingestion · Reads source files into the analysis pipeline · `src/data_loader.py`
- [Validators](https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/src/validators.py): integrity checks · Validates input data quality and required structure · `src/validators.py`
- [Utils](https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/src/utils.py): shared helpers · Common utility functions used across phases · `src/utils.py`
- [Data generator](https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/src/data_generator.py): sample data · Creates synthetic or example inputs for the pipeline · `src/data_generator.py`

### Phase 00

Dataset understanding and quality checks

- [Overview](https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/analysis/phase_00/a_dataset_overview.py): profiling report · Summarizes dataset structure and baseline context · `analysis/phase_00/a_dataset_overview.py`
- [Quality checks](https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/analysis/phase_00/d_data_quality.py): diagnostics · Checks data completeness and consistency · `analysis/phase_00/d_data_quality.py`
- [Reference data](https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/analysis/phase_00/f_reference_data.py): reference lookup · Shows supporting reference tables and baseline slices · `analysis/phase_00/f_reference_data.py`

### Phase 01

Base-month vs current-month comparison

- [Base vs current](https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/analysis/phase_01/base_vs_current.py): comparison analysis · Compares entity counts and segment composition across two months · `analysis/phase_01/base_vs_current.py`

### Phase 02

Movement analysis across segments

- [Movement core](https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/analysis/phase_02/movement_core.py): transition kernel · Shared movement logic used by all phase 02 reports · `analysis/phase_02/movement_core.py`
- [Movement matrix](https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/analysis/phase_02/a_movement_matrix.py): transition report · Computes segment-to-segment movement counts · `analysis/phase_02/a_movement_matrix.py`
- [New entities](https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/analysis/phase_02/b_new_entities.py): movement report · Identifies entities entering the system or segment · `analysis/phase_02/b_new_entities.py`
- [Lost entities](https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/analysis/phase_02/c_lost_entities.py): movement report · Identifies entities leaving the system or segment · `analysis/phase_02/c_lost_entities.py`
- [Movement analysis](https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/analysis/phase_02/d_movement_analysis.py): movement analysis · Explains movement patterns across segments · `analysis/phase_02/d_movement_analysis.py`
- [Sankey diagram](https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/analysis/phase_02/e_sankey_diagram.py): visual report · Builds the flow diagram for segment transitions · `analysis/phase_02/e_sankey_diagram.py`
- [Summary](https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/analysis/phase_02/f_movement_summary.py): summary report · Consolidates the phase 02 findings · `analysis/phase_02/f_movement_summary.py`

### Visuals

Reusable charting and styling

- [Charts](https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/visualizations/charts.py): plot builders · Reusable Plotly chart constructors · `visualizations/charts.py`
- [Styles](https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/visualizations/styles.py): theme config · Shared colors and formatting rules · `visualizations/styles.py`

### Exports

Spreadsheet output generation

- [Excel export](https://github.com/dmehta2396/segmentation_analysis_v2/blob/main/exports/excel_exporter.py): xlsx exporter · Writes formatted spreadsheet deliverables · `exports/excel_exporter.py`

## Connections

- Run phase 00 → Settings: loads settings · Uses centralized mappings and output conventions
- Run phase 00 → Data loader: loads data · Reads source inputs for analysis
- Run phase 00 → Validators: validates · Checks input integrity before reporting
- Run phase 00 → Overview: runs · Executes the phase 00 analysis modules
- Run phase 00 → Quality checks: runs · Executes data quality diagnostics
- Run phase 00 → Reference data: runs · Produces reference and baseline views
- Run phase 01 → Settings: loads settings · Uses shared comparison configuration
- Run phase 01 → Data loader: loads data · Reads source inputs for comparison
- Run phase 01 → Base vs current: runs · Executes base-vs-current comparison
- Run phase 02 → Settings: loads settings · Uses shared movement configuration
- Run phase 02 → Data loader: loads data · Reads source inputs for movement analysis
- Run phase 02 → Movement core: uses core · Delegates transition logic to the shared kernel
- Run phase 02 → Movement matrix: runs · Generates movement matrix output
- Run phase 02 → New entities: runs · Generates new-entity output
- Run phase 02 → Lost entities: runs · Generates lost-entity output
- Run phase 02 → Movement analysis: runs · Produces analytical movement commentary
- Run phase 02 → Sankey diagram: runs · Produces transition visualization
- Run phase 02 → Summary: runs · Compiles final phase summary
- Overview → Charts: renders with · Uses shared chart primitives for HTML output
- Quality checks → Charts: renders with · Uses charts for diagnostic presentation
- Base vs current → Charts: renders with · Uses shared chart primitives for comparison views
- Movement matrix → Charts: renders with · Uses chart builders for matrix display
- Sankey diagram → Charts: renders with · Uses chart builders for Sankey output
- Overview → Styles: applies · Uses shared theme and formatting
- Base vs current → Styles: applies · Uses shared theme and formatting
- Summary → Styles: applies · Uses shared theme and formatting
- Overview → Excel export: exports · Writes spreadsheet deliverables
- Base vs current → Excel export: exports · Writes spreadsheet deliverables
- Summary → Excel export: exports · Writes spreadsheet deliverables
- Data loader → Validators: passes through · Loaded records are validated before analysis
- Data loader → Utils: uses · Relies on common helper functions
- Data generator → Data loader: feeds · Generates sample inputs for ingestion
- Settings → Overview: configures · Shapes month selection and labeling
- Settings → Base vs current: configures · Shapes base/current comparison rules
- Settings → Movement core: configures · Defines segment and transition behavior