# bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati architecture
> Architecture diagram of the GitHub repository bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.
- Interactive diagram: https://gitdiagram.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati
- Repository: https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati
## Overview
1. **Overall shape**
This repo is a two-part system: an offline analytics/model-training pipeline and an online Streamlit dashboard. Raw airline loyalty data is transformed into model artifacts, and the app layer loads those artifacts to produce customer-level intelligence and reports.
2. **Primary data sources**
The core inputs are four local CSV datasets under `dataset/`: customer loyalty history, monthly flight activity, calendar data, and the data dictionary. The architecture assumes 12 months of behavioral history per customer, which is the main unit of analysis throughout the system.
3. **Data preparation boundary**
`dataset/scripts/` is the feature-engineering and dataset-building layer. These scripts convert raw CSVs into training-ready tables and tensors, including static features, sequence features, and future-value labels. This is the boundary between source data and ML-ready inputs.
4. **Training subsystem**
`training/` contains the model-building pipelines for the project’s main predictive components: LSTM embeddings, XGBoost churn classification, hybrid modeling, and future-value regression. This layer produces the persisted artifacts stored under `dataset/graphs/`.
5. **Artifact store / model registry**
`dataset/graphs/` acts as a local artifact repository rather than just a plotting folder. It holds trained models, embeddings, scalers, encoders, metrics, and feature-importance outputs. Runtime inference depends on these saved artifacts instead of retraining.
6. **Behavioral modeling flow**
The predictive pipeline starts with the LSTM encoder, which turns 12-month customer sequences into behavior embeddings. Those embeddings and engineered features then feed downstream churn and segment logic. This is the core behavioral intelligence layer of the platform.
7. **Prediction and segmentation**
The main inference logic lives in `app/testing/` despite the name. It includes customer-level prediction, business profiling, retention logic, and report generation helpers. The app uses this layer to produce churn risk, priority, customer value, and segment labels for a selected customer or dataset.
8. **Forecasting and value estimation**
Separate regression models forecast future flights, distance, and loyalty points. These predictions are used to estimate future customer value and revenue at risk, which directly informs the retention strategy rather than just providing standalone forecasts.
9. **Retention decision engine**
The retention subsystem converts model outputs into business actions: priority tier, estimated loss, recommended interventions, and rationale. This is the bridge from ML outputs to decision support, and it is the main business logic boundary in the repo.
10. **LLM reporting layer**
The generative AI component uses Qwen 3 8B through Ollama to turn structured customer intelligence into executive summaries, customer messages, and management recommendations. This is a separate external runtime dependency, used after the predictive and retention layers have already produced structured inputs.
11. **Streamlit presentation layer**
`app/Home.py` is the dashboard entrypoint, with `app/pages/` providing a multi-page workflow: overview, forecast, retention strategy, AI executive summary, customer message, and report export. The UI is organized as a guided analysis flow rather than a generic dashboard.
12. **Output and export flow**
The system’s end products are customer profiles, AI-generated narratives, and downloadable reports. The final pages consolidate structured ML outputs and LLM-generated text into exportable business intelligence for analysts and managers.
13. **Architecture summary for diagramming**
A good diagram should show: raw CSV inputs → preprocessing/feature engineering → model training/artifacts → Streamlit inference layer → retention logic → Ollama/Qwen report generation → interactive dashboard/export. The key boundaries are offline training vs. online app execution, and structured ML outputs vs. generated narrative outputs.
Main entry points: [`dataset/scripts`](https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/tree/main/dataset/scripts) (Prep scripts), [`dataset/graphs`](https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/tree/main/dataset/graphs) (Model store), [`app/testing/business_predictor.py`](https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/app/testing/business_predictor.py) (Customer intel), [`app/pages`](https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/tree/main/app/pages) (Pages)
## Diagram (Mermaid)
```mermaid
flowchart TD
subgraph group_group_data["Data & Artifacts"]
node_node_loyalty_data["Loyalty history
raw csv"]
node_node_flight_data["Flight activity
raw csv"]
node_node_calendar_data["Calendar
raw csv
[Calendar.csv]"]
node_node_dictionary["Data dictionary
reference csv"]
node_node_artifacts[("Model store
artifact registry")]
end
subgraph group_group_train["Offline Training"]
node_node_data_scripts["Prep scripts
feature engineering"]
node_node_training_dataset["Training set
dataset builder"]
node_node_features["Features
feature engineering
[features.py]"]
node_node_tensors["Tensors
tensor builder
[tensors.py]"]
node_node_future_data["Future labels
label builder"]
node_node_training["Training
model pipelines"]
node_node_lstm_train(("LSTM encoder
sequence model
[lstm_embeddings.py]"))
node_node_xgb_train(("Churn model
classifier
[xg_baseline.py]"))
node_node_hybrid_train(("Hybrid model
ensemble
[hybrid.py]"))
node_node_regressor_train(("Value model
regressor
[regressor.py]"))
end
subgraph group_group_app["Streamlit App"]
node_node_inference["Inference
scoring layer
[inference.py]"]
node_node_business_predictor["Customer intel
prediction logic"]
node_node_retention["Retention engine
decision logic"]
node_node_llm["LLM reports
generative layer
[llm_report.py]"]
node_node_home["Dashboard
streamlit app
[Home.py]"]
node_node_pages["Pages"]
end
node_node_loyalty_data -->|"raw input"| node_node_data_scripts
node_node_flight_data -->|"raw input"| node_node_data_scripts
node_node_calendar_data -->|"raw input"| node_node_data_scripts
node_node_dictionary -->|"schema"| node_node_data_scripts
node_node_data_scripts -->|"build"| node_node_training_dataset
node_node_data_scripts -->|"derive"| node_node_features
node_node_data_scripts -->|"tensorize"| node_node_tensors
node_node_data_scripts -->|"label prep"| node_node_future_data
node_node_training_dataset -->|"train data"| node_node_xgb_train
node_node_features -->|"feature input"| node_node_hybrid_train
node_node_tensors -->|"sequence input"| node_node_lstm_train
node_node_tensors -->|"forecast input"| node_node_regressor_train
node_node_future_data -->|"targets"| node_node_regressor_train
node_node_lstm_train -->|"save"| node_node_artifacts
node_node_xgb_train -->|"save"| node_node_artifacts
node_node_hybrid_train -->|"save"| node_node_artifacts
node_node_regressor_train -->|"save"| node_node_artifacts
node_node_artifacts -->|"load"| node_node_inference
node_node_inference -->|"scores"| node_node_business_predictor
node_node_business_predictor -->|"decision input"| node_node_retention
node_node_business_predictor -->|"structured context"| node_node_llm
node_node_retention -->|"strategy context"| node_node_llm
node_node_inference -->|"runtime data"| node_node_home
node_node_business_predictor -->|"analysis views"| node_node_pages
node_node_retention -->|"strategy views"| node_node_pages
node_node_llm -->|"narratives"| node_node_pages
node_node_home -->|"navigation"| node_node_pages
click node_node_loyalty_data "https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/dataset/Customer Loyalty History.csv"
click node_node_flight_data "https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/dataset/Customer Flight Activity.csv"
click node_node_calendar_data "https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/dataset/Calendar.csv"
click node_node_dictionary "https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/dataset/Airline Loyalty Data Dictionary.csv"
click node_node_data_scripts "https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/tree/main/dataset/scripts"
click node_node_training_dataset "https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/dataset/scripts/training_dataset.py"
click node_node_features "https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/dataset/scripts/features.py"
click node_node_tensors "https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/dataset/scripts/tensors.py"
click node_node_future_data "https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/dataset/scripts/future_value_data.py"
click node_node_training "https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/tree/main/training"
click node_node_lstm_train "https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/training/lstm_embeddings.py"
click node_node_xgb_train "https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/training/xg_baseline.py"
click node_node_hybrid_train "https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/training/hybrid.py"
click node_node_regressor_train "https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/training/regressor.py"
click node_node_artifacts "https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/tree/main/dataset/graphs"
click node_node_inference "https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/app/testing/inference.py"
click node_node_business_predictor "https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/app/testing/business_predictor.py"
click node_node_retention "https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/app/testing/retention_engine.py"
click node_node_llm "https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/app/testing/llm_report.py"
click node_node_home "https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/app/Home.py"
click node_node_pages "https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/tree/main/app/pages"
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_node_loyalty_data,node_node_flight_data,node_node_calendar_data,node_node_dictionary,node_node_artifacts toneBlue
class node_node_data_scripts,node_node_training_dataset,node_node_features,node_node_tensors,node_node_future_data,node_node_training,node_node_lstm_train,node_node_xgb_train,node_node_hybrid_train,node_node_regressor_train toneAmber
class node_node_inference,node_node_business_predictor,node_node_retention,node_node_llm,node_node_home,node_node_pages toneMint
```
## Components
### Data & Artifacts
Raw datasets, engineered tables, tensors, and persisted model artifacts.
- [Loyalty history](https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/HEAD/dataset/Customer%20Loyalty%20History.csv): raw csv · Customer loyalty history source dataset. · `dataset/Customer Loyalty History.csv`
- [Flight activity](https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/HEAD/dataset/Customer%20Flight%20Activity.csv): raw csv · Monthly customer flight activity source dataset. · `dataset/Customer Flight Activity.csv`
- [Calendar](https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/dataset/Calendar.csv): raw csv · Date and seasonality reference data. · `dataset/Calendar.csv`
- [Data dictionary](https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/HEAD/dataset/Airline%20Loyalty%20Data%20Dictionary.csv): reference csv · Schema and field definitions for the airline loyalty data. · `dataset/Airline Loyalty Data Dictionary.csv`
- [Model store](https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/tree/main/dataset/graphs): artifact registry · Persisted models, embeddings, scalers, encoders, metrics, and feature importances. · `dataset/graphs`
### Offline Training
Feature engineering and model training pipelines that populate the artifact store.
- [Prep scripts](https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/tree/main/dataset/scripts): feature engineering · Data loading, feature construction, tensorization, and training-table generation. · `dataset/scripts`
- [Training set](https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/dataset/scripts/training_dataset.py): dataset builder · Builds merged customer-level datasets and labels from raw sources. · `dataset/scripts/training_dataset.py`
- [Features](https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/dataset/scripts/features.py): feature engineering · Creates static, sequence, and derived behavioral features. · `dataset/scripts/features.py`
- [Tensors](https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/dataset/scripts/tensors.py): tensor builder · Produces sequence tensors, scaled static inputs, encoders, and forecast labels. · `dataset/scripts/tensors.py`
- [Future labels](https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/dataset/scripts/future_value_data.py): label builder · Constructs future-value training data for regression targets. · `dataset/scripts/future_value_data.py`
- [Training](https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/tree/main/training): model pipelines · Offline model training entrypoints for churn, hybrid, embeddings, and regression. · `training`
- [LSTM encoder](https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/training/lstm_embeddings.py): sequence model · Learns behavior embeddings from 12-month customer sequences. · `training/lstm_embeddings.py`
- [Churn model](https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/training/xg_baseline.py): classifier · Baseline churn prediction model and feature importance pipeline. · `training/xg_baseline.py`
- [Hybrid model](https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/training/hybrid.py): ensemble · Combines sequence embeddings with engineered features for downstream prediction. · `training/hybrid.py`
- [Value model](https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/training/regressor.py): regressor · Forecasts future flights, distance, and loyalty-point value. · `training/regressor.py`
### Streamlit App
Online inference, retention logic, LLM reporting, and user-facing pages.
- [Inference](https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/app/testing/inference.py): scoring layer · Loads artifacts and produces customer-level predictions and intermediate outputs. · `app/testing/inference.py`
- [Customer intel](https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/app/testing/business_predictor.py): prediction logic · Customer profiling, churn risk, customer value, and segment assignment. · `app/testing/business_predictor.py`
- [Retention engine](https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/app/testing/retention_engine.py): decision logic · Converts model outputs into priority, estimated loss, and recommended actions. · `app/testing/retention_engine.py`
- [LLM reports](https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/app/testing/llm_report.py): generative layer · Uses Qwen 3 8B via Ollama to generate executive summaries and customer-facing narratives. · `app/testing/llm_report.py`
- [Dashboard](https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/blob/main/app/Home.py): streamlit app · Main Streamlit entrypoint. · `app/Home.py`
- [Pages](https://github.com/bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati/tree/main/app/pages): streamlit pages · Multi-page workflow for overview, forecast, retention, AI summary, message, and export. · `app/pages`
## Connections
- Loyalty history → Prep scripts: raw input · Feeds customer history into preprocessing.
- Flight activity → Prep scripts: raw input · Feeds monthly activity into preprocessing.
- Calendar → Prep scripts: raw input · Provides time context for feature building.
- Data dictionary → Prep scripts: schema · Defines field meanings used during ingestion.
- Prep scripts → Training set: build · Creates merged training tables.
- Prep scripts → Features: derive · Generates engineered static and sequence features.
- Prep scripts → Tensors: tensorize · Produces scaled arrays and encoders.
- Prep scripts → Future labels: label prep · Builds future-target regression data.
- Training set → Churn model: train data · Supplies tabular inputs for churn models.
- Features → Hybrid model: feature input · Supplies engineered features to hybrid modeling.
- Tensors → LSTM encoder: sequence input · Supplies customer sequences for embedding learning.
- Tensors → Value model: forecast input · Supplies forecast tensors and targets.
- Future labels → Value model: targets · Provides future-value labels.
- LSTM encoder → Model store: save · Persists embedding and sequence models.
- Churn model → Model store: save · Persists churn baseline models and diagnostics.
- Hybrid model → Model store: save · Persists hybrid churn artifacts.
- Value model → Model store: save · Persists future-value predictors and metrics.
- Model store → Inference: load · Runtime inference depends on saved models and preprocessors.
- Inference → Customer intel: scores · Produces customer-level predictions and derived signals.
- Customer intel → Retention engine: decision input · Feeds business metrics into retention logic.
- Customer intel → LLM reports: structured context · Provides customer intelligence for narrative generation.
- Retention engine → LLM reports: strategy context · Provides actions and rationale for AI summaries.
- Inference → Dashboard: runtime data · Supplies dashboard views with scored outputs.
- Customer intel → Pages: analysis views · Feeds forecast and overview pages.
- Retention engine → Pages: strategy views · Feeds retention strategy and export pages.
- LLM reports → Pages: narratives · Feeds AI summary and customer message pages.
- Dashboard → Pages: navigation · Main entrypoint routes into the multi-page workflow.