How fixaipro/analytics-engine works
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: app.py Flask API · AnalysisWorkbench.jsx Workbench · docker-compose.yml Container build · App.jsx App shell
Components 18
Frontend
React/Vite SPA and UI composition
- App shell · Top-level client entry and page composition
frontend/src/App.jsx - Workbench · Main user flow for loading data, selecting models, tuning parameters, and viewing results
frontend/src/components/AnalysisWorkbench.jsx - Data input · CSV paste/upload and sample-data entry point
frontend/src/components/DataInput.jsx - Model picker · Chooses the analysis method and drives model-specific UI
frontend/src/components/ModelSelector.jsx - Params panel · Collects model-specific parameters before analysis
frontend/src/components/ParamsPanel.jsx - Results panel · Renders charts and summary outputs from analysis responses
frontend/src/components/ResultsPanel.jsx - API client · Centralized frontend-to-backend request layer
frontend/src/api/client.js - Model meta · Frontend mirror of backend model names, categories, and help text
frontend/src/data/modelMeta.js
Backend
Flask analytics API and model execution
- Flask API · Backend entrypoint exposing health, model registry, sample data, and analysis endpoints
backend/app.py - Samples · Bundled example datasets for model-specific loading
backend/data/samples.py - Noise reduction · Optional smoothing step before model execution
backend/utils/noise_reduction.py - Causal models · Counterfactual and intervention-style analysis methods
backend/models/causal_impact.py - Time series · Forecasting and decomposition models
backend/models/arima_model.py - Diagnostics · Detection and relationship analysis methods
backend/models/anomaly_detection.py - Regression · Statistical regression analysis
backend/models/regression.py - Support utils · Persistence and Google Cloud extension points
backend/utils/db.py - Notebook route · Supplementary analysis or educational backend route
backend/routes/notebook.py
Deployment
Container and Cloud Run packaging
- Container build · Docker and Cloud Build packaging for both services
docker-compose.yml
Connections 18
- 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