# rj-hossan/optipulse architecture

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

- Interactive diagram: https://gitdiagram.com/rj-hossan/optipulse
- Repository: https://github.com/rj-hossan/optipulse

## Overview

1. **Overall shape**
   - OptiPulse is a **Streamlit-based analytics application** for telecom use cases.
   - The repository is organized as a **single UI entrypoint** plus a set of **feature-specific frontend modules** that each implement one analytics or prediction workflow.

2. **UI entrypoint and navigation**
   - `app.py` is the main launch file referenced by the README command `streamlit run app.py`.
   - The `frontend/` package contains the user-facing sections of the app, likely wired into Streamlit navigation or page selection.
   - `frontend/home.py` acts as the landing page, while the other modules represent specialized pages.

3. **Domain-specific application modules**
   - The frontend is split into telecom/business problem areas rather than technical layers.
   - Pages include:
     - anomaly detection
     - churn prediction
     - contract renewal prediction
     - customer satisfaction analysis
     - customer segmentation
     - revenue forecasting
     - maintenance scheduling
     - failure prediction
     - fault type prediction
     - severity level prediction
     - throughput, latency, packet loss, signal strength, interference, energy efficiency analysis
     - service adoption and lifetime value prediction
   - This suggests a **multi-tool decision support dashboard** rather than one monolithic model.

4. **Data flow through the app**
   - The typical flow is: **load telecom data → clean/transform features → apply model or analysis → visualize outputs in Streamlit**.
   - The README shows this pattern explicitly for anomaly detection:
     - read CSV data
     - fill missing values
     - select feature set
     - scale features
     - run ML algorithm
     - write labeled output
     - plot results
   - Other pages likely follow the same pattern for their respective business questions.

5. **Model usage and artifacts**
   - The `models/` directory stores serialized ML artifacts used at runtime:
     - `anomaly_model_oneSVM.pkl`
     - `customer_satisfaction_model_LR_best.pkl`
     - `kmeans_model.pkl`
   - This indicates a boundary between **offline training** and **online inference/UI**, with trained models loaded into the app for prediction or clustering.

6. **Analytical subsystems described in the README**
   - **Task 1: Telecom anomaly detection** uses classical unsupervised ML methods such as Isolation Forest, LOF, and One-Class SVM.
   - **Task 2: Customer satisfaction analysis** is a supervised regression workflow comparing linear regression, decision tree, random forest, and gradient boosting.
   - **Task 3: Customer segmentation** is an unsupervised clustering workflow centered on K-Means, silhouette analysis, and PCA.
   - These are the clearest “core analytics” subsystems and likely anchor the main product value.

7. **Visualization layer**
   - Visual output is an important part of the architecture.
   - The app uses plotting libraries such as Matplotlib and Seaborn to render scatter plots, pair plots, heatmaps, and performance charts.
   - `assets/figures/` likely holds static images used in documentation or embedded in the UI.
   - Visualization is not just decoration; it is part of the analysis workflow and how users interpret model results.

8. **Preprocessing and feature engineering boundary**
   - The workflows rely on standard ML preprocessing with Pandas, NumPy, and scikit-learn.
   - Common steps include:
     - missing-value handling
     - numeric scaling with `StandardScaler`
     - feature selection for specific tasks
     - encoding or dimensionality reduction for segmentation workflows
   - This preprocessing layer sits between raw telecom datasets and model inference.

9. **Runtime and dependencies**
   - The app runs in a Python environment managed by `requirements.txt`.
   - The README emphasizes local execution through Streamlit, so the app is intended to run as a **local interactive analytics tool**, not as a deployed backend service.
   - `.devcontainer/` indicates a containerized development setup for reproducible environments.

10. **Research and experimentation workspace**
   - `notebooks/` appears to be an exploratory workspace rather than production code.
   - This is where model experimentation, data exploration, and prototyping likely happened before serializing selected models into `models/`.
   - The notebook folder is therefore part of the development pipeline, but not the main runtime path.

11. **Repository boundary**
   - There is no separate API server, database layer, or message queue in the tree.
   - The architecture is therefore **self-contained and file-based**: input data is read from local files, models are loaded from local artifacts, and outputs are rendered or exported locally.
   - That makes the repo closer to an **interactive analytics workstation** than a distributed application.

12. **What an architecture diagram should show**
   - One central Streamlit app entrypoint.
   - A set of frontend modules as independently navigable analytics pages.
   - Local model artifacts feeding selected pages.
   - Shared preprocessing/plotting logic implied by the use of scikit-learn, Pandas, and Seaborn.
   - Static assets and notebooks as supporting, non-runtime resources.

Main entry points: [`frontend/home.py`](https://github.com/rj-hossan/optipulse/blob/main/frontend/home.py) (Home), [`assets/figures`](https://github.com/rj-hossan/optipulse/tree/main/assets/figures) (Figures), [`app.py`](https://github.com/rj-hossan/optipulse/blob/main/app.py) (App), [`frontend/customer_satisfaction_analysis.py`](https://github.com/rj-hossan/optipulse/blob/main/frontend/customer_satisfaction_analysis.py) (Satisfaction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI Shell"]
  node_app_py["App<br/>streamlit entrypoint<br/>[app.py]"]
  node_home_py["Home<br/>landing page<br/>[home.py]"]
  node_collaborators_py["Collaborators<br/>info page<br/>[collaborators.py]"]
end

subgraph group_customer["Customer Analytics"]
  node_customer_satisfaction_py["Satisfaction<br/>regression analysis"]
  node_customer_segmentation_py["Segmentation<br/>clustering workflow"]
  node_churn_prediction_py["Churn<br/>retention model"]
  node_contract_renewal_py["Renewal"]
  node_lifetime_value_py["LTV<br/>value model"]
  node_revenue_forecasting_py["Revenue<br/>forecasting page"]
  node_service_adoption_py["Adoption"]
end

subgraph group_network["Network Analytics"]
  node_throughput_py["Throughput<br/>kpi analysis"]
  node_latency_py["Latency<br/>kpi analysis"]
  node_packet_loss_py["Packet Loss<br/>kpi analysis"]
  node_signal_strength_py["Signal<br/>kpi analysis"]
  node_interference_py["Interference<br/>kpi analysis"]
  node_energy_efficiency_py["Energy<br/>kpi analysis"]
end

subgraph group_ops["Operations"]
  node_anomaly_detection_py["Anomaly<br/>unsupervised detection"]
  node_failure_prediction_py["Failure"]
  node_maintenance_scheduling_py["Maintenance<br/>planning workflow"]
  node_fault_type_prediction_py["Fault Type<br/>fault classifier"]
  node_severity_level_prediction_py["Severity"]
end

subgraph group_support["Support"]
  node_anomaly_model[("Anomaly Model<br/>serialized model")]
  node_satisfaction_model[("Sat Model<br/>serialized model")]
  node_kmeans_model[("K-Means<br/>serialized model<br/>[kmeans_model.pkl]")]
  node_figures["Figures<br/>static assets"]
  node_notebook["Notebook<br/>exploration workspace<br/>[temp.ipynb]"]
  node_requirements["Deps<br/>dependency manifest<br/>[requirements.txt]"]
end

node_app_py -->|"launches"| node_home_py
node_home_py -->|"nav"| node_anomaly_detection_py
node_home_py -->|"nav"| node_customer_satisfaction_py
node_home_py -->|"nav"| node_customer_segmentation_py
node_home_py -->|"nav"| node_churn_prediction_py
node_home_py -->|"nav"| node_contract_renewal_py
node_home_py -->|"nav"| node_revenue_forecasting_py
node_home_py -->|"nav"| node_service_adoption_py
node_home_py -->|"nav"| node_throughput_py
node_home_py -->|"nav"| node_latency_py
node_home_py -->|"nav"| node_packet_loss_py
node_home_py -->|"nav"| node_signal_strength_py
node_home_py -->|"nav"| node_interference_py
node_home_py -->|"nav"| node_energy_efficiency_py
node_home_py -->|"nav"| node_failure_prediction_py
node_home_py -->|"nav"| node_fault_type_prediction_py
node_home_py -->|"nav"| node_severity_level_prediction_py
node_home_py -->|"nav"| node_maintenance_scheduling_py
node_home_py -->|"info"| node_collaborators_py
node_anomaly_detection_py -->|"loads"| node_anomaly_model
node_customer_satisfaction_py -->|"loads"| node_satisfaction_model
node_customer_segmentation_py -->|"loads"| node_kmeans_model
node_anomaly_detection_py -->|"plots"| node_figures
node_customer_satisfaction_py -->|"plots"| node_figures
node_customer_segmentation_py -->|"plots"| node_figures
node_failure_prediction_py -->|"plots"| node_figures
node_throughput_py -->|"plots"| node_figures
node_latency_py -->|"plots"| node_figures
node_packet_loss_py -->|"plots"| node_figures
node_signal_strength_py -->|"plots"| node_figures
node_interference_py -->|"plots"| node_figures
node_app_py -->|"depends on"| node_requirements
node_app_py -.->|"informed by"| node_notebook

click node_app_py "https://github.com/rj-hossan/optipulse/blob/main/app.py"
click node_home_py "https://github.com/rj-hossan/optipulse/blob/main/frontend/home.py"
click node_collaborators_py "https://github.com/rj-hossan/optipulse/blob/main/frontend/collaborators.py"
click node_anomaly_detection_py "https://github.com/rj-hossan/optipulse/blob/main/frontend/anomaly_detection.py"
click node_failure_prediction_py "https://github.com/rj-hossan/optipulse/blob/main/frontend/failure_prediction.py"
click node_maintenance_scheduling_py "https://github.com/rj-hossan/optipulse/blob/main/frontend/maintenance_scheduling.py"
click node_fault_type_prediction_py "https://github.com/rj-hossan/optipulse/blob/main/frontend/fault_type_prediction.py"
click node_severity_level_prediction_py "https://github.com/rj-hossan/optipulse/blob/main/frontend/severity_level_prediction.py"
click node_customer_satisfaction_py "https://github.com/rj-hossan/optipulse/blob/main/frontend/customer_satisfaction_analysis.py"
click node_customer_segmentation_py "https://github.com/rj-hossan/optipulse/blob/main/frontend/customer_segmentation.py"
click node_churn_prediction_py "https://github.com/rj-hossan/optipulse/blob/main/frontend/churn_prediction.py"
click node_contract_renewal_py "https://github.com/rj-hossan/optipulse/blob/main/frontend/contract_renewal_prediction.py"
click node_lifetime_value_py "https://github.com/rj-hossan/optipulse/blob/main/frontend/lifetime_value_prediction.py"
click node_revenue_forecasting_py "https://github.com/rj-hossan/optipulse/blob/main/frontend/revenue_forecasting.py"
click node_service_adoption_py "https://github.com/rj-hossan/optipulse/blob/main/frontend/service_adoption_analysis.py"
click node_throughput_py "https://github.com/rj-hossan/optipulse/blob/main/frontend/throughput_prediction.py"
click node_latency_py "https://github.com/rj-hossan/optipulse/blob/main/frontend/latency_reduction_analysis.py"
click node_packet_loss_py "https://github.com/rj-hossan/optipulse/blob/main/frontend/packet_loss_rate_analysis.py"
click node_signal_strength_py "https://github.com/rj-hossan/optipulse/blob/main/frontend/signal_strength_analysis.py"
click node_interference_py "https://github.com/rj-hossan/optipulse/blob/main/frontend/interference_level_analysis.py"
click node_energy_efficiency_py "https://github.com/rj-hossan/optipulse/blob/main/frontend/energy_efficiency_modeling.py"
click node_anomaly_model "https://github.com/rj-hossan/optipulse/blob/main/models/anomaly_model_oneSVM.pkl"
click node_satisfaction_model "https://github.com/rj-hossan/optipulse/blob/main/models/customer_satisfaction_model_LR_best.pkl"
click node_kmeans_model "https://github.com/rj-hossan/optipulse/blob/main/models/kmeans_model.pkl"
click node_figures "https://github.com/rj-hossan/optipulse/tree/main/assets/figures"
click node_notebook "https://github.com/rj-hossan/optipulse/blob/main/notebooks/temp.ipynb"
click node_requirements "https://github.com/rj-hossan/optipulse/blob/main/requirements.txt"

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_app_py,node_home_py,node_collaborators_py toneBlue
class node_customer_satisfaction_py,node_customer_segmentation_py,node_churn_prediction_py,node_contract_renewal_py,node_lifetime_value_py,node_revenue_forecasting_py,node_service_adoption_py toneAmber
class node_throughput_py,node_latency_py,node_packet_loss_py,node_signal_strength_py,node_interference_py,node_energy_efficiency_py toneMint
class node_anomaly_detection_py,node_failure_prediction_py,node_maintenance_scheduling_py,node_fault_type_prediction_py,node_severity_level_prediction_py toneRose
class node_anomaly_model,node_satisfaction_model,node_kmeans_model,node_figures,node_notebook,node_requirements toneIndigo
```

## Components

### UI Shell

Streamlit entrypoint and landing/navigation layer

- [App](https://github.com/rj-hossan/optipulse/blob/main/app.py): streamlit entrypoint · Main Streamlit launch file and top-level app router · `app.py`
- [Home](https://github.com/rj-hossan/optipulse/blob/main/frontend/home.py): landing page · Front page and navigation hub · `frontend/home.py`
- [Collaborators](https://github.com/rj-hossan/optipulse/blob/main/frontend/collaborators.py): info page · Team or project information page · `frontend/collaborators.py`

### Customer Analytics

Customer-facing prediction and segmentation workflows

- [Satisfaction](https://github.com/rj-hossan/optipulse/blob/main/frontend/customer_satisfaction_analysis.py): regression analysis · Customer satisfaction modeling and comparison · `frontend/customer_satisfaction_analysis.py`
- [Segmentation](https://github.com/rj-hossan/optipulse/blob/main/frontend/customer_segmentation.py): clustering workflow · Customer grouping with clustering and projection · `frontend/customer_segmentation.py`
- [Churn](https://github.com/rj-hossan/optipulse/blob/main/frontend/churn_prediction.py): retention model · Predicts customer churn risk · `frontend/churn_prediction.py`
- [Renewal](https://github.com/rj-hossan/optipulse/blob/main/frontend/contract_renewal_prediction.py): renewal predictor · Predicts contract renewal likelihood · `frontend/contract_renewal_prediction.py`
- [LTV](https://github.com/rj-hossan/optipulse/blob/main/frontend/lifetime_value_prediction.py): value model · Predicts customer lifetime value · `frontend/lifetime_value_prediction.py`
- [Revenue](https://github.com/rj-hossan/optipulse/blob/main/frontend/revenue_forecasting.py): forecasting page · Revenue forecasting and trend analysis · `frontend/revenue_forecasting.py`
- [Adoption](https://github.com/rj-hossan/optipulse/blob/main/frontend/service_adoption_analysis.py): adoption analysis · Service adoption analysis and prediction · `frontend/service_adoption_analysis.py`

### Network Analytics

Telecom network quality and KPI analysis pages

- [Throughput](https://github.com/rj-hossan/optipulse/blob/main/frontend/throughput_prediction.py): kpi analysis · Throughput analysis or prediction page · `frontend/throughput_prediction.py`
- [Latency](https://github.com/rj-hossan/optipulse/blob/main/frontend/latency_reduction_analysis.py): kpi analysis · Latency reduction analysis page · `frontend/latency_reduction_analysis.py`
- [Packet Loss](https://github.com/rj-hossan/optipulse/blob/main/frontend/packet_loss_rate_analysis.py): kpi analysis · Packet loss rate analysis page · `frontend/packet_loss_rate_analysis.py`
- [Signal](https://github.com/rj-hossan/optipulse/blob/main/frontend/signal_strength_analysis.py): kpi analysis · Signal strength analysis page · `frontend/signal_strength_analysis.py`
- [Interference](https://github.com/rj-hossan/optipulse/blob/main/frontend/interference_level_analysis.py): kpi analysis · Interference level analysis page · `frontend/interference_level_analysis.py`
- [Energy](https://github.com/rj-hossan/optipulse/blob/main/frontend/energy_efficiency_modeling.py): kpi analysis · Energy efficiency modeling page · `frontend/energy_efficiency_modeling.py`

### Operations

Operational prediction and maintenance workflows

- [Anomaly](https://github.com/rj-hossan/optipulse/blob/main/frontend/anomaly_detection.py): unsupervised detection · Telecom anomaly detection workflow · `frontend/anomaly_detection.py`
- [Failure](https://github.com/rj-hossan/optipulse/blob/main/frontend/failure_prediction.py): failure predictor · Predicts network or service failures · `frontend/failure_prediction.py`
- [Maintenance](https://github.com/rj-hossan/optipulse/blob/main/frontend/maintenance_scheduling.py): planning workflow · Schedules maintenance based on predicted conditions · `frontend/maintenance_scheduling.py`
- [Fault Type](https://github.com/rj-hossan/optipulse/blob/main/frontend/fault_type_prediction.py): fault classifier · Classifies fault categories · `frontend/fault_type_prediction.py`
- [Severity](https://github.com/rj-hossan/optipulse/blob/main/frontend/severity_level_prediction.py): severity classifier · Predicts incident severity levels · `frontend/severity_level_prediction.py`

### Support

Models, figures, and exploratory work

- [Anomaly Model](https://github.com/rj-hossan/optipulse/blob/main/models/anomaly_model_oneSVM.pkl): serialized model · Saved anomaly detection artifact · `models/anomaly_model_oneSVM.pkl`
- [Sat Model](https://github.com/rj-hossan/optipulse/blob/main/models/customer_satisfaction_model_LR_best.pkl): serialized model · Saved customer satisfaction regression artifact · `models/customer_satisfaction_model_LR_best.pkl`
- [K-Means](https://github.com/rj-hossan/optipulse/blob/main/models/kmeans_model.pkl): serialized model · Saved clustering artifact for segmentation · `models/kmeans_model.pkl`
- [Figures](https://github.com/rj-hossan/optipulse/tree/main/assets/figures): static assets · Stored figures and images used by the app and docs · `assets/figures`
- [Notebook](https://github.com/rj-hossan/optipulse/blob/main/notebooks/temp.ipynb): exploration workspace · Interactive experimentation and prototyping space · `notebooks/temp.ipynb`
- [Deps](https://github.com/rj-hossan/optipulse/blob/main/requirements.txt): dependency manifest · Python package requirements for the Streamlit app · `requirements.txt`

## Connections

- App → Home: launches · Streamlit starts on the home page
- Home → Anomaly: nav · Landing page links to analysis modules
- Home → Satisfaction: nav · Landing page links to analysis modules
- Home → Segmentation: nav · Landing page links to analysis modules
- Home → Churn: nav · Landing page links to analysis modules
- Home → Renewal: nav · Landing page links to analysis modules
- Home → Revenue: nav · Landing page links to analysis modules
- Home → Adoption: nav · Landing page links to analysis modules
- Home → Throughput: nav · Landing page links to analysis modules
- Home → Latency: nav · Landing page links to analysis modules
- Home → Packet Loss: nav · Landing page links to analysis modules
- Home → Signal: nav · Landing page links to analysis modules
- Home → Interference: nav · Landing page links to analysis modules
- Home → Energy: nav · Landing page links to analysis modules
- Home → Failure: nav · Landing page links to analysis modules
- Home → Fault Type: nav · Landing page links to analysis modules
- Home → Severity: nav · Landing page links to analysis modules
- Home → Maintenance: nav · Landing page links to analysis modules
- Home → Collaborators: info · Home page also exposes project information
- Anomaly → Anomaly Model: loads · Uses saved anomaly detector at runtime
- Satisfaction → Sat Model: loads · Uses saved satisfaction regression model at runtime
- Segmentation → K-Means: loads · Uses saved clustering artifact at runtime
- Anomaly → Figures: plots · Renders analysis outputs as visuals
- Satisfaction → Figures: plots · Renders analysis outputs as visuals
- Segmentation → Figures: plots · Renders analysis outputs as visuals
- Failure → Figures: plots · Renders analysis outputs as visuals
- Throughput → Figures: plots · Renders analysis outputs as visuals
- Latency → Figures: plots · Renders analysis outputs as visuals
- Packet Loss → Figures: plots · Renders analysis outputs as visuals
- Signal → Figures: plots · Renders analysis outputs as visuals
- Interference → Figures: plots · Renders analysis outputs as visuals
- App → Deps: depends on · Runtime dependency set for the Streamlit app
- App → Notebook: informed by · Exploration and prototyping feed the app and artifacts