# gouravverma23/mplads-risk-analytics architecture

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

- Interactive diagram: https://gitdiagram.com/gouravverma23/mplads-risk-analytics
- Repository: https://github.com/gouravverma23/mplads-risk-analytics

## Overview

This repository implements a FastAPI risk analytics service for public-works expenditures and project execution. Users submit single or batch records; the API engineers features from the records and historical CSV baselines, scores them with the corresponding anomaly or execution model, and returns risk metrics, explanations, flags, and recommended actions. The two pillars share the API but have distinct feature-engineering and scoring stages. The sampled source supports these request paths and model/index responsibilities; startup wiring and some endpoint details are only partially shown, so uncertain links are omitted.

Main entry points: [`app/main.py`](https://github.com/gouravverma23/mplads-risk-analytics/blob/main/app/main.py) (FastAPI service), [`app/services/execution_feature_engineering.py`](https://github.com/gouravverma23/mplads-risk-analytics/blob/main/app/services/execution_feature_engineering.py) (Execution features), [`app/services/feature_engineering.py`](https://github.com/gouravverma23/mplads-risk-analytics/blob/main/app/services/feature_engineering.py) (Expenditure features), [`models/expenditure_anomaly_model.joblib`](https://github.com/gouravverma23/mplads-risk-analytics/blob/main/models/expenditure_anomaly_model.joblib) (Expenditure model artifact)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and contracts"]
  node_service["FastAPI service<br/>[main.py]"]
  node_exp_schema["Expenditure contracts"]
  node_exec_schema["Work contracts"]
end

subgraph group_expenditure["Expenditure risk"]
  node_exp_features["Expenditure features"]
  node_exp_model["Expenditure scorer"]
  node_exp_artifact["Expenditure model artifact"]
end

subgraph group_execution["Execution risk"]
  node_exec_features["Execution features"]
  node_exec_model["Execution scorer"]
  node_exec_artifact["Execution model artifact"]
end

subgraph group_data["Historical data"]
  node_exp_history["Expenditure history"]
  node_allocations["MP allocations"]
  node_recommended["Recommended works"]
  node_sanctioned["Sanctioned works"]
  node_completed["Completed works"]
end

node_caller(("API client"))
node_risk_result["Risk results"]

node_caller -->|"submits request"| node_service
node_service -->|"validates expenditure"| node_exp_schema
node_service -->|"validates work"| node_exec_schema
node_service -->|"engineers features"| node_exp_features
node_service -->|"scores transaction"| node_exp_model
node_service -->|"engineers features"| node_exec_features
node_service -->|"scores project"| node_exec_model
node_exp_history -->|"historical records"| node_exp_features
node_allocations -->|"budget baseline"| node_exp_features
node_recommended -->|"work history"| node_exec_features
node_sanctioned -->|"work history"| node_exec_features
node_completed -->|"completion history"| node_exec_features
node_exp_artifact -->|"loaded at startup"| node_service
node_exec_artifact -->|"loaded at startup"| node_service
node_service -->|"returns scores"| node_risk_result
node_risk_result -->|"delivers response"| node_caller

click node_service "https://github.com/gouravverma23/mplads-risk-analytics/blob/main/app/main.py"
click node_exp_schema "https://github.com/gouravverma23/mplads-risk-analytics/blob/main/app/schemas/expenditure_schema.py"
click node_exec_schema "https://github.com/gouravverma23/mplads-risk-analytics/blob/main/app/schemas/execution_schema.py"
click node_exp_features "https://github.com/gouravverma23/mplads-risk-analytics/blob/main/app/services/feature_engineering.py"
click node_exp_model "https://github.com/gouravverma23/mplads-risk-analytics/blob/main/ExpenditureModelModule.py"
click node_exec_features "https://github.com/gouravverma23/mplads-risk-analytics/blob/main/app/services/execution_feature_engineering.py"
click node_exec_model "https://github.com/gouravverma23/mplads-risk-analytics/blob/main/ExecutionModelModule.py"
click node_exp_history "https://github.com/gouravverma23/mplads-risk-analytics/blob/main/New%20Datasets/Expenditures%20Lok%20Sabha.csv"
click node_allocations "https://github.com/gouravverma23/mplads-risk-analytics/blob/main/New%20Datasets/Allocated%20Limit%20MP%20Lok%20Sabha.csv"
click node_recommended "https://github.com/gouravverma23/mplads-risk-analytics/blob/main/New%20Datasets/Works%20Recommended.csv"
click node_sanctioned "https://github.com/gouravverma23/mplads-risk-analytics/blob/main/New%20Datasets/Works%20Sanctioned.csv"
click node_completed "https://github.com/gouravverma23/mplads-risk-analytics/blob/main/New%20Datasets/Works%20Completed.csv"
click node_exp_artifact "https://github.com/gouravverma23/mplads-risk-analytics/blob/main/models/expenditure_anomaly_model.joblib"
click node_exec_artifact "https://github.com/gouravverma23/mplads-risk-analytics/blob/main/models/execution_delay_model.joblib"

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_service,node_exp_schema,node_exec_schema,node_caller toneBlue
class node_exp_features,node_exp_model,node_exp_artifact toneAmber
class node_exec_features,node_exec_model,node_exec_artifact toneMint
class node_exp_history,node_allocations,node_recommended,node_sanctioned,node_completed toneRose
class node_risk_result toneIndigo
```

## Components

### API and contracts

- [FastAPI service](https://github.com/gouravverma23/mplads-risk-analytics/blob/main/app/main.py): `app/main.py`
- [Expenditure contracts](https://github.com/gouravverma23/mplads-risk-analytics/blob/main/app/schemas/expenditure_schema.py): `app/schemas/expenditure_schema.py`
- [Work contracts](https://github.com/gouravverma23/mplads-risk-analytics/blob/main/app/schemas/execution_schema.py): `app/schemas/execution_schema.py`

### Expenditure risk

- [Expenditure features](https://github.com/gouravverma23/mplads-risk-analytics/blob/main/app/services/feature_engineering.py): `app/services/feature_engineering.py`
- [Expenditure scorer](https://github.com/gouravverma23/mplads-risk-analytics/blob/main/ExpenditureModelModule.py): `ExpenditureModelModule.py`
- [Expenditure model artifact](https://github.com/gouravverma23/mplads-risk-analytics/blob/main/models/expenditure_anomaly_model.joblib): `models/expenditure_anomaly_model.joblib`

### Execution risk

- [Execution features](https://github.com/gouravverma23/mplads-risk-analytics/blob/main/app/services/execution_feature_engineering.py): `app/services/execution_feature_engineering.py`
- [Execution scorer](https://github.com/gouravverma23/mplads-risk-analytics/blob/main/ExecutionModelModule.py): `ExecutionModelModule.py`
- [Execution model artifact](https://github.com/gouravverma23/mplads-risk-analytics/blob/main/models/execution_delay_model.joblib): `models/execution_delay_model.joblib`

### Historical data

- [Expenditure history](https://github.com/gouravverma23/mplads-risk-analytics/blob/main/New%20Datasets/Expenditures%20Lok%20Sabha.csv): `New Datasets/Expenditures Lok Sabha.csv`
- [MP allocations](https://github.com/gouravverma23/mplads-risk-analytics/blob/main/New%20Datasets/Allocated%20Limit%20MP%20Lok%20Sabha.csv): `New Datasets/Allocated Limit MP Lok Sabha.csv`
- [Recommended works](https://github.com/gouravverma23/mplads-risk-analytics/blob/main/New%20Datasets/Works%20Recommended.csv): `New Datasets/Works Recommended.csv`
- [Sanctioned works](https://github.com/gouravverma23/mplads-risk-analytics/blob/main/New%20Datasets/Works%20Sanctioned.csv): `New Datasets/Works Sanctioned.csv`
- [Completed works](https://github.com/gouravverma23/mplads-risk-analytics/blob/main/New%20Datasets/Works%20Completed.csv): `New Datasets/Works Completed.csv`

### Other components

- **API client**
- **Risk results**

## Connections

- API client → FastAPI service: submits request
- FastAPI service → Expenditure contracts: validates expenditure
- FastAPI service → Work contracts: validates work
- FastAPI service → Expenditure features: engineers features
- FastAPI service → Expenditure scorer: scores transaction
- FastAPI service → Execution features: engineers features
- FastAPI service → Execution scorer: scores project
- Expenditure history → Expenditure features: historical records
- MP allocations → Expenditure features: budget baseline
- Recommended works → Execution features: work history
- Sanctioned works → Execution features: work history
- Completed works → Execution features: completion history
- Expenditure model artifact → FastAPI service: loaded at startup
- Execution model artifact → FastAPI service: loaded at startup
- FastAPI service → Risk results: returns scores
- Risk results → API client: delivers response