# fixaipro/analytics-engine architecture

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

- Interactive diagram: https://gitdiagram.com/fixaipro/analytics-engine
- Repository: https://github.com/fixaipro/analytics-engine

## Overview

1. **High-level shape**
   - This repo is a two-service analytics application: a **Flask backend** that runs statistical models, and a **React/Vite frontend** that provides a workbench UI for loading data, choosing a model, tuning parameters, and viewing results.

2. **Frontend boundary**
   - The frontend is a single-page app built from `frontend/src/App.jsx` and `main.jsx`.
   - It is organized around reusable workbench components such as `AnalysisWorkbench`, `ModelSelector`, `DataInput`, `NoiseToggle`, `ParamsPanel`, and `ResultsPanel`.
   - Charting is done client-side with **Recharts**, and API access is centralized in `frontend/src/api/client.js`.

3. **User interaction flow**
   - The typical flow is: pick a model, optionally load sample data, paste/upload CSV data, toggle noise reduction, set model-specific parameters, then send an analysis request.
   - Results come back as structured chart data plus a summary object, which the UI renders into plots and KPI-style outputs.
   - The UI also includes explanatory/educational surfaces such as `HowItWorks`, `NotebookTab`, and other analysis tabs, so the product is both an analysis tool and a reference app.

4. **Backend API boundary**
   - The backend entrypoint is `backend/app.py`.
   - It exposes a small API surface centered on:
     - `GET /health`
     - `GET /api/models`
     - `GET /api/sample-data/{model_name}`
     - `POST /api/analyze`
   - The backend is CORS-enabled and runs behind **Gunicorn/Flask** in containerized deployments.

5. **Core analysis pipeline**
   - `POST /api/analyze` is the main data flow boundary.
   - Incoming CSV-like records are converted into tabular data, optionally passed through noise reduction, then dispatched to the selected model implementation.
   - The backend returns a normalized response shape across all models: model id, `chart_data`, `summary`, and flags describing whether preprocessing was applied.

6. **Model subsystem**
   - Each statistical method lives in its own module under `backend/models/`.
   - The suite covers causal, predictive, forecasting, diagnostic, and exploratory analytics:
     - causal impact
     - regression
     - ARIMA
     - Holt-Winters
     - anomaly detection
     - difference-in-differences
     - changepoint detection
     - synthetic control
     - correlation
     - STL decomposition
   - The architecture is modular: each model appears to follow a common `run(df, params) -> dict` style contract, making model selection a dispatch problem rather than a branching monolith.

7. **Preprocessing and sample-data support**
   - Noise reduction lives in `backend/utils/noise_reduction.py` and is an optional pre-processing step before model execution.
   - Two smoothing methods are documented and implied by the code structure: **Savitzky-Golay** and **EWMA**.
   - Sample datasets are bundled in `backend/data/samples.py`, allowing the UI to auto-load model-appropriate input formats without needing external fixtures.

8. **Backend support/integration layer**
   - The backend also contains `utils/db.py`, `utils/gcs.py`, `utils/pubsub.py`, and `models_db/analysis_run.py`.
   - These suggest extension points for persistence and Google Cloud integration, but the documented primary runtime is still a mostly **stateless request/response analytics service**.
   - In other words, the main architecture does not depend on a live database for the core analysis loop.

9. **Client/server contract**
   - Frontend and backend are loosely coupled through the API payloads and the shared model registry.
   - The frontend metadata in `frontend/src/data/modelMeta.js` mirrors backend model names/categories so the UI can populate selectors, labels, and help text.
   - This makes the backend responsible for computation and the frontend responsible for presentation/orchestration.

10. **Deployment architecture**
   - Each tier has its own Docker image (`backend/Dockerfile`, `frontend/Dockerfile`).
   - `docker-compose.yml` supports local two-container development.
   - Production deployment targets **GCP Cloud Run**, with `deploy.sh` and `cloudbuild.yaml` building and publishing both services.
   - The frontend build receives the backend URL via `VITE_API_URL`, so the static UI can be deployed independently while still calling the correct API endpoint.

11. **Runtime and library choices that matter**
   - Backend analytics relies on **pandas**, **numpy**, **scipy**, **statsmodels**, and **ruptures**.
   - Frontend is **React 18 + Vite** with static serving through **nginx** in the production container.
   - These choices explain the architecture: compute-heavy statistical logic stays server-side, while the browser handles interaction and chart rendering only.

12. **Diagramming takeaway**
   - A good architecture diagram should show:
     - a browser SPA on the left
     - a Flask analytics API on the right
     - optional sample-data and preprocessing steps inside the backend
     - a set of independent model modules behind one analysis endpoint
     - container/Cloud Run deployment wrapping both services
   - The key boundary is not “frontend vs backend” only, but also **orchestration vs model execution** inside the backend.

Main entry points: [`backend/app.py`](https://github.com/fixaipro/analytics-engine/blob/main/backend/app.py) (Flask API), [`frontend/src/components/AnalysisWorkbench.jsx`](https://github.com/fixaipro/analytics-engine/blob/main/frontend/src/components/AnalysisWorkbench.jsx) (Workbench), [`docker-compose.yml`](https://github.com/fixaipro/analytics-engine/blob/main/docker-compose.yml) (Container build), [`frontend/src/App.jsx`](https://github.com/fixaipro/analytics-engine/blob/main/frontend/src/App.jsx) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App shell<br/>React SPA<br/>[App.jsx]"]
  node_workbench["Workbench<br/>analysis UI"]
  node_data_input["Data input<br/>input component<br/>[DataInput.jsx]"]
  node_model_selector["Model picker<br/>selector component<br/>[ModelSelector.jsx]"]
  node_params_panel["Params panel<br/>config component<br/>[ParamsPanel.jsx]"]
  node_results_panel["Results panel<br/>results UI<br/>[ResultsPanel.jsx]"]
  node_api_client["API client<br/>HTTP client<br/>[client.js]"]
  node_model_meta["Model meta<br/>registry data<br/>[modelMeta.js]"]
end

subgraph group_backend["Backend"]
  node_analysis_api["Flask API<br/>request API<br/>[app.py]"]
  node_sample_data["Samples<br/>seed data<br/>[samples.py]"]
  node_noise_reduction["Noise reduction<br/>preprocess<br/>[noise_reduction.py]"]
  node_causal_models["Causal models<br/>model family<br/>[causal_impact.py]"]
  node_timeseries_models["Time series<br/>model family<br/>[arima_model.py]"]
  node_diagnostic_models["Diagnostics<br/>model family"]
  node_regression_model["Regression<br/>model<br/>[regression.py]"]
  node_support_utils["Support utils<br/>integrations<br/>[db.py]"]
  node_notebook_route["Notebook route<br/>aux route<br/>[notebook.py]"]
end

subgraph group_deployment["Deployment"]
  node_container_build["Container build<br/>deployment<br/>[docker-compose.yml]"]
end

node_frontend_app -->|"composes"| node_workbench
node_workbench -->|"uses"| node_data_input
node_workbench -->|"uses"| node_model_selector
node_workbench -->|"uses"| node_params_panel
node_workbench -->|"renders"| node_results_panel
node_model_selector -->|"reads"| node_model_meta
node_workbench -->|"calls"| node_api_client
node_api_client -->|"POST/GET"| node_analysis_api
node_analysis_api -->|"serves"| node_sample_data
node_analysis_api -->|"preprocesses"| node_noise_reduction
node_analysis_api -->|"dispatches"| node_causal_models
node_analysis_api -->|"dispatches"| node_timeseries_models
node_analysis_api -->|"dispatches"| node_diagnostic_models
node_analysis_api -->|"dispatches"| node_regression_model
node_analysis_api -.->|"extends"| node_support_utils
node_analysis_api -->|"mounts"| node_notebook_route
node_container_build -->|"packages"| node_analysis_api
node_container_build -->|"packages"| node_frontend_app

click node_frontend_app "https://github.com/fixaipro/analytics-engine/blob/main/frontend/src/App.jsx"
click node_workbench "https://github.com/fixaipro/analytics-engine/blob/main/frontend/src/components/AnalysisWorkbench.jsx"
click node_data_input "https://github.com/fixaipro/analytics-engine/blob/main/frontend/src/components/DataInput.jsx"
click node_model_selector "https://github.com/fixaipro/analytics-engine/blob/main/frontend/src/components/ModelSelector.jsx"
click node_params_panel "https://github.com/fixaipro/analytics-engine/blob/main/frontend/src/components/ParamsPanel.jsx"
click node_results_panel "https://github.com/fixaipro/analytics-engine/blob/main/frontend/src/components/ResultsPanel.jsx"
click node_api_client "https://github.com/fixaipro/analytics-engine/blob/main/frontend/src/api/client.js"
click node_model_meta "https://github.com/fixaipro/analytics-engine/blob/main/frontend/src/data/modelMeta.js"
click node_analysis_api "https://github.com/fixaipro/analytics-engine/blob/main/backend/app.py"
click node_sample_data "https://github.com/fixaipro/analytics-engine/blob/main/backend/data/samples.py"
click node_noise_reduction "https://github.com/fixaipro/analytics-engine/blob/main/backend/utils/noise_reduction.py"
click node_causal_models "https://github.com/fixaipro/analytics-engine/blob/main/backend/models/causal_impact.py"
click node_timeseries_models "https://github.com/fixaipro/analytics-engine/blob/main/backend/models/arima_model.py"
click node_diagnostic_models "https://github.com/fixaipro/analytics-engine/blob/main/backend/models/anomaly_detection.py"
click node_regression_model "https://github.com/fixaipro/analytics-engine/blob/main/backend/models/regression.py"
click node_support_utils "https://github.com/fixaipro/analytics-engine/blob/main/backend/utils/db.py"
click node_notebook_route "https://github.com/fixaipro/analytics-engine/blob/main/backend/routes/notebook.py"
click node_container_build "https://github.com/fixaipro/analytics-engine/blob/main/docker-compose.yml"

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_frontend_app,node_workbench,node_data_input,node_model_selector,node_params_panel,node_results_panel,node_api_client,node_model_meta toneBlue
class node_analysis_api,node_sample_data,node_noise_reduction,node_causal_models,node_timeseries_models,node_diagnostic_models,node_regression_model,node_support_utils,node_notebook_route toneAmber
class node_container_build toneMint
```

## Components

### Frontend

React/Vite SPA and UI composition

- [App shell](https://github.com/fixaipro/analytics-engine/blob/main/frontend/src/App.jsx): React SPA · Top-level client entry and page composition · `frontend/src/App.jsx`
- [Workbench](https://github.com/fixaipro/analytics-engine/blob/main/frontend/src/components/AnalysisWorkbench.jsx): analysis UI · Main user flow for loading data, selecting models, tuning parameters, and viewing results · `frontend/src/components/AnalysisWorkbench.jsx`
- [Data input](https://github.com/fixaipro/analytics-engine/blob/main/frontend/src/components/DataInput.jsx): input component · CSV paste/upload and sample-data entry point · `frontend/src/components/DataInput.jsx`
- [Model picker](https://github.com/fixaipro/analytics-engine/blob/main/frontend/src/components/ModelSelector.jsx): selector component · Chooses the analysis method and drives model-specific UI · `frontend/src/components/ModelSelector.jsx`
- [Params panel](https://github.com/fixaipro/analytics-engine/blob/main/frontend/src/components/ParamsPanel.jsx): config component · Collects model-specific parameters before analysis · `frontend/src/components/ParamsPanel.jsx`
- [Results panel](https://github.com/fixaipro/analytics-engine/blob/main/frontend/src/components/ResultsPanel.jsx): results UI · Renders charts and summary outputs from analysis responses · `frontend/src/components/ResultsPanel.jsx`
- [API client](https://github.com/fixaipro/analytics-engine/blob/main/frontend/src/api/client.js): HTTP client · Centralized frontend-to-backend request layer · `frontend/src/api/client.js`
- [Model meta](https://github.com/fixaipro/analytics-engine/blob/main/frontend/src/data/modelMeta.js): registry data · Frontend mirror of backend model names, categories, and help text · `frontend/src/data/modelMeta.js`

### Backend

Flask analytics API and model execution

- [Flask API](https://github.com/fixaipro/analytics-engine/blob/main/backend/app.py): request API · Backend entrypoint exposing health, model registry, sample data, and analysis endpoints · `backend/app.py`
- [Samples](https://github.com/fixaipro/analytics-engine/blob/main/backend/data/samples.py): seed data · Bundled example datasets for model-specific loading · `backend/data/samples.py`
- [Noise reduction](https://github.com/fixaipro/analytics-engine/blob/main/backend/utils/noise_reduction.py): preprocess · Optional smoothing step before model execution · `backend/utils/noise_reduction.py`
- [Causal models](https://github.com/fixaipro/analytics-engine/blob/main/backend/models/causal_impact.py): model family · Counterfactual and intervention-style analysis methods · `backend/models/causal_impact.py`
- [Time series](https://github.com/fixaipro/analytics-engine/blob/main/backend/models/arima_model.py): model family · Forecasting and decomposition models · `backend/models/arima_model.py`
- [Diagnostics](https://github.com/fixaipro/analytics-engine/blob/main/backend/models/anomaly_detection.py): model family · Detection and relationship analysis methods · `backend/models/anomaly_detection.py`
- [Regression](https://github.com/fixaipro/analytics-engine/blob/main/backend/models/regression.py): model · Statistical regression analysis · `backend/models/regression.py`
- [Support utils](https://github.com/fixaipro/analytics-engine/blob/main/backend/utils/db.py): integrations · Persistence and Google Cloud extension points · `backend/utils/db.py`
- [Notebook route](https://github.com/fixaipro/analytics-engine/blob/main/backend/routes/notebook.py): aux route · Supplementary analysis or educational backend route · `backend/routes/notebook.py`

### Deployment

Container and Cloud Run packaging

- [Container build](https://github.com/fixaipro/analytics-engine/blob/main/docker-compose.yml): deployment · Docker and Cloud Build packaging for both services · `docker-compose.yml`

## Connections

- App shell → Workbench: composes · App shell assembles the main analysis experience
- Workbench → Data input: uses · Workbench accepts user data and sample loading
- Workbench → Model picker: uses · Workbench lets users choose an analysis method
- Workbench → Params panel: uses · Workbench gathers model-specific parameters
- Workbench → Results panel: renders · Workbench displays charts and summaries
- Model picker → Model meta: reads · Selector options and labels are driven by shared model metadata
- Workbench → API client: calls · UI submits analysis requests through the API client
- API client → Flask API: POST/GET · Frontend talks to the Flask API over the network
- Flask API → Samples: serves · Backend returns model-appropriate example datasets
- Flask API → Noise reduction: preprocesses · Optional smoothing before model execution
- Flask API → Causal models: dispatches · Analysis endpoint routes causal requests to model modules
- Flask API → Time series: dispatches · Analysis endpoint routes forecasting and decomposition requests
- Flask API → Diagnostics: dispatches · Analysis endpoint routes detection and relationship requests
- Flask API → Regression: dispatches · Analysis endpoint routes regression requests
- Flask API → Support utils: extends · Optional persistence and cloud integrations sit beside core analytics
- Flask API → Notebook route: mounts · Additional route surface for notebook-style analysis or education
- Container build → Flask API: packages · Backend container and build pipeline package the Flask service
- Container build → App shell: packages · Frontend container and build pipeline package the SPA
