# shettyprasad-git/smart-sales-forecasting-system architecture

> Architecture diagram of the GitHub repository shettyprasad-git/smart-sales-forecasting-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shettyprasad-git/smart-sales-forecasting-system
- Repository: https://github.com/shettyprasad-git/smart-sales-forecasting-system

## Overview

Smart Sales Forecasting is a full-stack sales analytics and demand-forecasting platform. Users authenticate, manage datasets and sales, then view forecasts, anomaly investigations, recommendations, and what-if simulations through a React workspace backed by FastAPI and ML artifacts. Anomaly handling has distinct detection, investigation, deterministic explanation, and AI-reasoning stages; dataset runtime and model storage support the analytical features. The graph preserves README-documented capabilities, but many API and service implementations were not excerpted, so uncertain links are dashed and marked without evidence.

Main entry points: [`backend/app/api`](https://github.com/shettyprasad-git/smart-sales-forecasting-system/tree/main/backend/app/api) (Product API routes), [`backend/app/services/investigation_service.py`](https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/backend/app/services/investigation_service.py) (Root-cause investigation), [`backend/app/services/simulation_service.py`](https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/backend/app/services/simulation_service.py) (What-if simulation), [`backend/app/services/dataset_runtime_service.py`](https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/backend/app/services/dataset_runtime_service.py) (Dataset runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["User workspace"]
  node_web["React workspace<br/>[App.jsx]"]
  node_webpages["Analytics pages"]
  node_webapi["API client"]
end

subgraph group_api["Application API"]
  node_server["FastAPI application<br/>[main.py]"]
  node_routes["Product API routes"]
  node_auth["Authentication<br/>[auth.py]"]
end

subgraph group_intelligence["Sales intelligence"]
  node_anomaly["Anomaly detection<br/>[anomaly_service.py]"]
  node_investigation["Root-cause investigation"]
  node_explanation["Executive explanation"]
  node_reasoning["AI reasoning"]
  node_recommendations["Recommendations"]
  node_simulation["What-if simulation"]
  node_provider["Gemini provider<br/>[gemini_provider.py]"]
end

subgraph group_forecasting["Forecasting ML"]
  node_forecast["Forecast service"]
  node_features["Feature engineering"]
  node_training["Model training<br/>[company_trainer.py]"]
  node_evaluation["Model evaluation"]
end

subgraph group_platform["Data and infrastructure"]
  node_datasets["Dataset runtime"]
  node_salesdata[("Sales and products<br/>[models.py]")]
  node_storage["Model artifact storage<br/>[storage_service.py]"]
end

node_user(("Business user"))
node_llm{{"Google Gemini"}}

node_user -->|"uses"| node_web
node_web -->|"routes to"| node_webpages
node_webpages -.->|"requests data"| node_webapi
node_webapi -->|"calls REST API"| node_server
node_server -->|"registers routes"| node_routes
node_routes -->|"routes auth"| node_auth
node_auth -->|"reads and writes users"| node_salesdata
node_routes -.->|"dispatches dataset operations"| node_datasets
node_datasets -->|"persists dataset records"| node_salesdata
node_datasets -->|"uses model storage"| node_storage
node_datasets -.->|"requests forecasts"| node_forecast
node_training -->|"builds features"| node_features
node_training -.->|"evaluates models"| node_evaluation
node_forecast -->|"builds features"| node_features
node_routes -.->|"dispatches detection"| node_anomaly
node_investigation -->|"uses detections"| node_anomaly
node_routes -.->|"dispatches investigations"| node_investigation
node_routes -.->|"dispatches explanations"| node_explanation
node_reasoning -->|"uses evidence"| node_investigation
node_reasoning -->|"uses narrative"| node_explanation
node_reasoning -->|"requests reasoning"| node_provider
node_provider -->|"generates analysis"| node_llm
node_routes -.->|"dispatches recommendations"| node_recommendations
node_recommendations -->|"uses evidence"| node_investigation
node_routes -.->|"dispatches simulations"| node_simulation
node_simulation -->|"uses forecasts"| node_forecast
node_simulation -->|"uses evidence"| node_investigation
node_simulation -->|"requests explanation"| node_provider

click node_web "https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/frontend/src/App.jsx"
click node_webpages "https://github.com/shettyprasad-git/smart-sales-forecasting-system/tree/main/frontend/src/pages"
click node_webapi "https://github.com/shettyprasad-git/smart-sales-forecasting-system/tree/main/frontend/src/api"
click node_server "https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/backend/app/main.py"
click node_routes "https://github.com/shettyprasad-git/smart-sales-forecasting-system/tree/main/backend/app/api"
click node_auth "https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/backend/app/api/auth.py"
click node_datasets "https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/backend/app/services/dataset_runtime_service.py"
click node_salesdata "https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/backend/app/database/models.py"
click node_storage "https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/backend/app/services/storage_service.py"
click node_forecast "https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/ml/inference/forecast_service.py"
click node_features "https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/ml/features/feature_pipeline.py"
click node_training "https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/ml/training/company_trainer.py"
click node_evaluation "https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/ml/evaluation/evaluate_production_models.py"
click node_anomaly "https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/backend/app/services/anomaly_service.py"
click node_investigation "https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/backend/app/services/investigation_service.py"
click node_explanation "https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/backend/app/services/explanation_service.py"
click node_reasoning "https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/backend/app/services/ai_reasoning_service.py"
click node_recommendations "https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/backend/app/services/recommendation_service.py"
click node_simulation "https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/backend/app/services/simulation_service.py"
click node_provider "https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/backend/app/llm/gemini_provider.py"

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_web,node_webpages,node_webapi,node_user toneBlue
class node_server,node_routes,node_auth toneAmber
class node_anomaly,node_investigation,node_explanation,node_reasoning,node_recommendations,node_simulation,node_provider toneMint
class node_forecast,node_features,node_training,node_evaluation toneRose
class node_datasets,node_salesdata,node_storage,node_llm toneIndigo
```

## Components

### User workspace

- [React workspace](https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Analytics pages](https://github.com/shettyprasad-git/smart-sales-forecasting-system/tree/main/frontend/src/pages): `frontend/src/pages`
- [API client](https://github.com/shettyprasad-git/smart-sales-forecasting-system/tree/main/frontend/src/api): `frontend/src/api`

### Application API

- [FastAPI application](https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/backend/app/main.py): `backend/app/main.py`
- [Product API routes](https://github.com/shettyprasad-git/smart-sales-forecasting-system/tree/main/backend/app/api): `backend/app/api`
- [Authentication](https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`

### Sales intelligence

- [Anomaly detection](https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/backend/app/services/anomaly_service.py): `backend/app/services/anomaly_service.py`
- [Root-cause investigation](https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/backend/app/services/investigation_service.py): `backend/app/services/investigation_service.py`
- [Executive explanation](https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/backend/app/services/explanation_service.py): `backend/app/services/explanation_service.py`
- [AI reasoning](https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/backend/app/services/ai_reasoning_service.py): `backend/app/services/ai_reasoning_service.py`
- [Recommendations](https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/backend/app/services/recommendation_service.py): `backend/app/services/recommendation_service.py`
- [What-if simulation](https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/backend/app/services/simulation_service.py): `backend/app/services/simulation_service.py`
- [Gemini provider](https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/backend/app/llm/gemini_provider.py): `backend/app/llm/gemini_provider.py`

### Forecasting ML

- [Forecast service](https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/ml/inference/forecast_service.py): `ml/inference/forecast_service.py`
- [Feature engineering](https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/ml/features/feature_pipeline.py): `ml/features/feature_pipeline.py`
- [Model training](https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/ml/training/company_trainer.py): `ml/training/company_trainer.py`
- [Model evaluation](https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/ml/evaluation/evaluate_production_models.py): `ml/evaluation/evaluate_production_models.py`

### Data and infrastructure

- [Dataset runtime](https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/backend/app/services/dataset_runtime_service.py): `backend/app/services/dataset_runtime_service.py`
- [Sales and products](https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/backend/app/database/models.py): `backend/app/database/models.py`
- [Model artifact storage](https://github.com/shettyprasad-git/smart-sales-forecasting-system/blob/main/backend/app/services/storage_service.py): `backend/app/services/storage_service.py`

### Other components

- **Business user**
- **Google Gemini**

## Connections

- Business user → React workspace: uses (evidence: `frontend/src/App.jsx`)
- React workspace → Analytics pages: routes to (evidence: `frontend/src/App.jsx`)
- Analytics pages → API client: requests data (evidence: `frontend/src/pages/Datasets.jsx`)
- API client → FastAPI application: calls REST API (evidence: `README.md`)
- FastAPI application → Product API routes: registers routes (evidence: `backend/app/main.py`)
- Product API routes → Authentication: routes auth (evidence: `backend/app/main.py`)
- Authentication → Sales and products: reads and writes users (evidence: `backend/app/api/auth.py`)
- Product API routes → Dataset runtime: dispatches dataset operations (evidence: `backend/app/api/ai_reasoning.py`)
- Dataset runtime → Sales and products: persists dataset records (evidence: `backend/app/services/dataset_runtime_service.py`)
- Dataset runtime → Model artifact storage: uses model storage (evidence: `backend/app/services/dataset_runtime_service.py`)
- Dataset runtime → Forecast service: requests forecasts
- Model training → Feature engineering: builds features (evidence: `ml/training/company_trainer.py`)
- Model training → Model evaluation: evaluates models
- Forecast service → Feature engineering: builds features (evidence: `ml/inference/forecast_service.py`)
- Product API routes → Anomaly detection: dispatches detection
- Root-cause investigation → Anomaly detection: uses detections (evidence: `backend/app/services/investigation_service.py`)
- Product API routes → Root-cause investigation: dispatches investigations
- Product API routes → Executive explanation: dispatches explanations
- AI reasoning → Root-cause investigation: uses evidence (evidence: `backend/app/services/ai_reasoning_service.py`)
- AI reasoning → Executive explanation: uses narrative (evidence: `backend/app/services/ai_reasoning_service.py`)
- AI reasoning → Gemini provider: requests reasoning (evidence: `backend/app/services/ai_reasoning_service.py`)
- Gemini provider → Google Gemini: generates analysis (evidence: `README.md`)
- Product API routes → Recommendations: dispatches recommendations
- Recommendations → Root-cause investigation: uses evidence (evidence: `backend/app/services/recommendation_service.py`)
- Product API routes → What-if simulation: dispatches simulations
- What-if simulation → Forecast service: uses forecasts (evidence: `backend/app/services/simulation_service.py`)
- What-if simulation → Root-cause investigation: uses evidence (evidence: `backend/app/services/simulation_service.py`)
- What-if simulation → Gemini provider: requests explanation (evidence: `backend/app/services/simulation_service.py`)
