rj-hossan/optipulse

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.