# shalvi-surve/neuralretail architecture

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

- Interactive diagram: https://gitdiagram.com/shalvi-surve/neuralretail
- Repository: https://github.com/shalvi-surve/neuralretail

## Overview

NeuralRetail is a Streamlit retail-intelligence application: users explore business KPIs, customer segments and churn risk, sales forecasts, and inventory recommendations. The documented analytical workflow transforms retail transactions through preprocessing and feature engineering into segmentation, churn, forecasting, and inventory outputs, which the dashboard presents. Shared dashboard initialization and data-loading utilities form the internal application layer. Pipeline sequencing and several product capabilities are documented in the README; unsampled page and model implementation details are not assumed.

Main entry points: [`src/dashboard_base.py`](https://github.com/shalvi-surve/neuralretail/blob/main/src/dashboard_base.py) (Dashboard setup), [`pages/2_Customers.py`](https://github.com/shalvi-surve/neuralretail/blob/main/pages/2_Customers.py) (Customer intelligence), [`pages/3_Churn.py`](https://github.com/shalvi-surve/neuralretail/blob/main/pages/3_Churn.py) (Churn center), [`pages/4_Forecast.py`](https://github.com/shalvi-surve/neuralretail/blob/main/pages/4_Forecast.py) (Forecast center)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_analytics["Analytics Pipeline"]
  node_preprocessing["Data cleaning<br/>[preprocessing.py]"]
  node_features["Feature engineering"]
  node_artifacts[("Generated datasets")]
end

subgraph group_customer["Customer Intelligence"]
  node_segmentation["Customer segmentation"]
  node_churn_model["Churn prediction"]
end

subgraph group_planning["Demand and Inventory"]
  node_forecast_model["Demand forecasting"]
  node_inventory_model["Inventory optimization<br/>[inventory.py]"]
end

subgraph group_dashboard["Dashboard Experience"]
  node_app["Streamlit entry<br/>[app.py]"]
  node_dashboard_page["Executive dashboard<br/>[1_Dashboard.py]"]
  node_customers_page["Customer intelligence<br/>[2_Customers.py]"]
  node_churn_page["Churn center<br/>[3_Churn.py]"]
  node_forecast_page["Forecast center<br/>[4_Forecast.py]"]
  node_inventory_page["Inventory center<br/>[5_Inventory.py]"]
  node_headers["Page headers<br/>[header.py]"]
  node_cards["KPI and insight cards<br/>[cards.py]"]
  node_charts["Interactive charts<br/>[charts.py]"]
  node_tables["Data tables<br/>[tables.py]"]
  node_metrics["Metric components<br/>[metrics.py]"]
  node_insights["Insight components<br/>[insights.py]"]
end

subgraph group_shared["Shared Services"]
  node_dashboard_base["Dashboard setup<br/>[dashboard_base.py]"]
  node_repository["Data repository<br/>[utils.py]"]
  node_sidebar["Navigation sidebar<br/>[sidebar.py]"]
end

node_user(("Retail user"))

node_user -->|"opens"| node_app
node_preprocessing -->|"cleans for"| node_features
node_features -->|"engineers inputs"| node_segmentation
node_features -->|"engineers inputs"| node_churn_model
node_features -->|"engineers inputs"| node_forecast_model
node_features -->|"engineers inputs"| node_inventory_model
node_segmentation -->|"generates outputs"| node_artifacts
node_churn_model -->|"generates outputs"| node_artifacts
node_forecast_model -->|"generates outputs"| node_artifacts
node_inventory_model -->|"generates outputs"| node_artifacts
node_app -.->|"hosts"| node_dashboard_page
node_dashboard_page -->|"initializes via"| node_dashboard_base
node_customers_page -->|"initializes via"| node_dashboard_base
node_churn_page -->|"initializes via"| node_dashboard_base
node_forecast_page -->|"initializes via"| node_dashboard_base
node_inventory_page -->|"initializes via"| node_dashboard_base
node_dashboard_base -->|"creates"| node_repository
node_dashboard_base -->|"imports"| node_sidebar
node_repository -->|"loads datasets"| node_artifacts
node_dashboard_page -->|"renders"| node_headers
node_customers_page -->|"renders"| node_headers
node_customers_page -->|"renders"| node_cards
node_customers_page -->|"renders"| node_charts
node_customers_page -->|"renders"| node_tables
node_churn_page -->|"renders"| node_headers
node_churn_page -->|"renders"| node_cards
node_churn_page -->|"renders"| node_charts
node_churn_page -->|"renders"| node_tables
node_forecast_page -->|"renders"| node_headers
node_forecast_page -->|"renders"| node_cards
node_forecast_page -->|"renders"| node_charts
node_forecast_page -->|"renders"| node_tables
node_inventory_page -->|"renders"| node_headers
node_inventory_page -->|"renders"| node_cards
node_inventory_page -->|"renders"| node_charts
node_inventory_page -->|"renders"| node_tables

click node_app "https://github.com/shalvi-surve/neuralretail/blob/main/app.py"
click node_preprocessing "https://github.com/shalvi-surve/neuralretail/blob/main/src/preprocessing.py"
click node_features "https://github.com/shalvi-surve/neuralretail/blob/main/src/feature_engineering.py"
click node_segmentation "https://github.com/shalvi-surve/neuralretail/blob/main/src/customer_segmentation.py"
click node_churn_model "https://github.com/shalvi-surve/neuralretail/blob/main/src/churn_prediction.py"
click node_forecast_model "https://github.com/shalvi-surve/neuralretail/blob/main/src/demand_forecasting.py"
click node_inventory_model "https://github.com/shalvi-surve/neuralretail/blob/main/src/inventory.py"
click node_artifacts "https://github.com/shalvi-surve/neuralretail/tree/main/artifacts"
click node_dashboard_page "https://github.com/shalvi-surve/neuralretail/blob/main/pages/1_Dashboard.py"
click node_customers_page "https://github.com/shalvi-surve/neuralretail/blob/main/pages/2_Customers.py"
click node_churn_page "https://github.com/shalvi-surve/neuralretail/blob/main/pages/3_Churn.py"
click node_forecast_page "https://github.com/shalvi-surve/neuralretail/blob/main/pages/4_Forecast.py"
click node_inventory_page "https://github.com/shalvi-surve/neuralretail/blob/main/pages/5_Inventory.py"
click node_dashboard_base "https://github.com/shalvi-surve/neuralretail/blob/main/src/dashboard_base.py"
click node_repository "https://github.com/shalvi-surve/neuralretail/blob/main/src/utils.py"
click node_sidebar "https://github.com/shalvi-surve/neuralretail/blob/main/components/sidebar.py"
click node_headers "https://github.com/shalvi-surve/neuralretail/blob/main/components/header.py"
click node_cards "https://github.com/shalvi-surve/neuralretail/blob/main/components/cards.py"
click node_charts "https://github.com/shalvi-surve/neuralretail/blob/main/components/charts.py"
click node_tables "https://github.com/shalvi-surve/neuralretail/blob/main/components/tables.py"
click node_metrics "https://github.com/shalvi-surve/neuralretail/blob/main/components/metrics.py"
click node_insights "https://github.com/shalvi-surve/neuralretail/blob/main/components/insights.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_preprocessing,node_features,node_artifacts,node_user toneBlue
class node_segmentation,node_churn_model toneAmber
class node_forecast_model,node_inventory_model toneMint
class node_app,node_dashboard_page,node_customers_page,node_churn_page,node_forecast_page,node_inventory_page,node_headers,node_cards,node_charts,node_tables,node_metrics,node_insights toneRose
class node_dashboard_base,node_repository,node_sidebar toneIndigo
```

## Components

### Analytics Pipeline

- [Data cleaning](https://github.com/shalvi-surve/neuralretail/blob/main/src/preprocessing.py): `src/preprocessing.py`
- [Feature engineering](https://github.com/shalvi-surve/neuralretail/blob/main/src/feature_engineering.py): `src/feature_engineering.py`
- [Generated datasets](https://github.com/shalvi-surve/neuralretail/tree/main/artifacts): `artifacts`

### Customer Intelligence

- [Customer segmentation](https://github.com/shalvi-surve/neuralretail/blob/main/src/customer_segmentation.py): `src/customer_segmentation.py`
- [Churn prediction](https://github.com/shalvi-surve/neuralretail/blob/main/src/churn_prediction.py): `src/churn_prediction.py`

### Demand and Inventory

- [Demand forecasting](https://github.com/shalvi-surve/neuralretail/blob/main/src/demand_forecasting.py): `src/demand_forecasting.py`
- [Inventory optimization](https://github.com/shalvi-surve/neuralretail/blob/main/src/inventory.py): `src/inventory.py`

### Dashboard Experience

- [Streamlit entry](https://github.com/shalvi-surve/neuralretail/blob/main/app.py): `app.py`
- [Executive dashboard](https://github.com/shalvi-surve/neuralretail/blob/main/pages/1_Dashboard.py): `pages/1_Dashboard.py`
- [Customer intelligence](https://github.com/shalvi-surve/neuralretail/blob/main/pages/2_Customers.py): `pages/2_Customers.py`
- [Churn center](https://github.com/shalvi-surve/neuralretail/blob/main/pages/3_Churn.py): `pages/3_Churn.py`
- [Forecast center](https://github.com/shalvi-surve/neuralretail/blob/main/pages/4_Forecast.py): `pages/4_Forecast.py`
- [Inventory center](https://github.com/shalvi-surve/neuralretail/blob/main/pages/5_Inventory.py): `pages/5_Inventory.py`
- [Page headers](https://github.com/shalvi-surve/neuralretail/blob/main/components/header.py): `components/header.py`
- [KPI and insight cards](https://github.com/shalvi-surve/neuralretail/blob/main/components/cards.py): `components/cards.py`
- [Interactive charts](https://github.com/shalvi-surve/neuralretail/blob/main/components/charts.py): `components/charts.py`
- [Data tables](https://github.com/shalvi-surve/neuralretail/blob/main/components/tables.py): `components/tables.py`
- [Metric components](https://github.com/shalvi-surve/neuralretail/blob/main/components/metrics.py): `components/metrics.py`
- [Insight components](https://github.com/shalvi-surve/neuralretail/blob/main/components/insights.py): `components/insights.py`

### Shared Services

- [Dashboard setup](https://github.com/shalvi-surve/neuralretail/blob/main/src/dashboard_base.py): `src/dashboard_base.py`
- [Data repository](https://github.com/shalvi-surve/neuralretail/blob/main/src/utils.py): `src/utils.py`
- [Navigation sidebar](https://github.com/shalvi-surve/neuralretail/blob/main/components/sidebar.py): `components/sidebar.py`

### Other components

- **Retail user**

## Connections

- Retail user → Streamlit entry: opens (evidence: `README.md`)
- Data cleaning → Feature engineering: cleans for (evidence: `README.md`)
- Feature engineering → Customer segmentation: engineers inputs (evidence: `README.md`)
- Feature engineering → Churn prediction: engineers inputs (evidence: `README.md`)
- Feature engineering → Demand forecasting: engineers inputs (evidence: `README.md`)
- Feature engineering → Inventory optimization: engineers inputs (evidence: `README.md`)
- Customer segmentation → Generated datasets: generates outputs (evidence: `README.md`)
- Churn prediction → Generated datasets: generates outputs (evidence: `README.md`)
- Demand forecasting → Generated datasets: generates outputs (evidence: `README.md`)
- Inventory optimization → Generated datasets: generates outputs (evidence: `README.md`)
- Streamlit entry → Executive dashboard: hosts
- Executive dashboard → Dashboard setup: initializes via (evidence: `pages/1_Dashboard.py`)
- Customer intelligence → Dashboard setup: initializes via (evidence: `pages/2_Customers.py`)
- Churn center → Dashboard setup: initializes via (evidence: `pages/3_Churn.py`)
- Forecast center → Dashboard setup: initializes via (evidence: `pages/4_Forecast.py`)
- Inventory center → Dashboard setup: initializes via (evidence: `pages/5_Inventory.py`)
- Dashboard setup → Data repository: creates (evidence: `src/dashboard_base.py`)
- Dashboard setup → Navigation sidebar: imports (evidence: `src/dashboard_base.py`)
- Data repository → Generated datasets: loads datasets (evidence: `src/utils.py`)
- Executive dashboard → Page headers: renders (evidence: `pages/1_Dashboard.py`)
- Customer intelligence → Page headers: renders (evidence: `pages/2_Customers.py`)
- Customer intelligence → KPI and insight cards: renders (evidence: `pages/2_Customers.py`)
- Customer intelligence → Interactive charts: renders (evidence: `pages/2_Customers.py`)
- Customer intelligence → Data tables: renders (evidence: `pages/2_Customers.py`)
- Churn center → Page headers: renders (evidence: `pages/3_Churn.py`)
- Churn center → KPI and insight cards: renders (evidence: `pages/3_Churn.py`)
- Churn center → Interactive charts: renders (evidence: `pages/3_Churn.py`)
- Churn center → Data tables: renders (evidence: `pages/3_Churn.py`)
- Forecast center → Page headers: renders (evidence: `pages/4_Forecast.py`)
- Forecast center → KPI and insight cards: renders (evidence: `pages/4_Forecast.py`)
- Forecast center → Interactive charts: renders (evidence: `pages/4_Forecast.py`)
- Forecast center → Data tables: renders (evidence: `pages/4_Forecast.py`)
- Inventory center → Page headers: renders (evidence: `pages/5_Inventory.py`)
- Inventory center → KPI and insight cards: renders (evidence: `pages/5_Inventory.py`)
- Inventory center → Interactive charts: renders (evidence: `pages/5_Inventory.py`)
- Inventory center → Data tables: renders (evidence: `pages/5_Inventory.py`)
