# theshahnawazali/argus architecture

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

- Interactive diagram: https://gitdiagram.com/theshahnawazali/argus
- Repository: https://github.com/theshahnawazali/argus

## Overview

Argus is a financial-fraud ML project with a FastAPI interface around training, model evaluation, and SHAP explanations. The principal implemented workflow loads and joins transaction and identity data, splits it, builds a preprocessing-and-classifier pipeline, trains it, and saves a model artifact. Evaluation and explanation are separate API actions. The README also describes Optuna tuning and prediction APIs, but sampled runtime code does not show a tuning implementation or a /predict route; those capabilities are therefore not drawn as live request flows.

Main entry points: [`main.py`](https://github.com/theshahnawazali/argus/blob/main/main.py) (FastAPI routes), [`pipeline/explain.py`](https://github.com/theshahnawazali/argus/blob/main/pipeline/explain.py) (SHAP explanations), [`models/xgb_pipeline.pkl`](https://github.com/theshahnawazali/argus/blob/main/models/xgb_pipeline.pkl) (XGBoost pipeline), [`pipeline/data_loader.py`](https://github.com/theshahnawazali/argus/blob/main/pipeline/data_loader.py) (Data loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API actions"]
  node_fastapi["FastAPI routes<br/>[main.py]"]
  node_request_schema["Explanation request<br/>[predict.py]"]
end

subgraph group_data["Data preparation"]
  node_config["Paths and parameters<br/>[config.py]"]
  node_loader["Data loader<br/>[data_loader.py]"]
  node_split["Train-test split<br/>[train.py]"]
end

subgraph group_models["Model lifecycle"]
  node_transformers["Missing-value handler<br/>[transformers.py]"]
  node_builder["Pipeline builders"]
  node_xgb_artifact["XGBoost pipeline<br/>[xgb_pipeline.pkl]"]
  node_gbm_artifact["GBM pipeline<br/>[gbm_pipeline.pkl]"]
  node_tuning["Hyperparameter tuning"]
end

subgraph group_insight["Evaluation and explanation"]
  node_metrics["Evaluation metrics<br/>[main.py]"]
  node_explainer["SHAP explanations<br/>[explain.py]"]
  node_shap_work["SHAP analysis"]
end

node_client(("API caller"))
node_dataset[("IEEE-CIS files")]

node_client -->|"calls routes"| node_fastapi
node_fastapi -->|"validates request"| node_request_schema
node_fastapi -->|"loads data"| node_loader
node_loader -->|"reads and joins"| node_dataset
node_fastapi -->|"uses settings"| node_config
node_fastapi -->|"splits data"| node_split
node_fastapi -->|"builds pipeline"| node_builder
node_builder -->|"uses transformer"| node_transformers
node_fastapi -->|"trains and saves"| node_xgb_artifact
node_fastapi -->|"trains and saves"| node_gbm_artifact
node_fastapi -->|"loads for evaluation"| node_xgb_artifact
node_fastapi -->|"computes metrics"| node_metrics
node_fastapi -->|"requests explanation"| node_explainer
node_explainer -->|"loads pipeline"| node_xgb_artifact
node_explainer -->|"loads pipeline"| node_gbm_artifact
node_tuning -.->|"documents tuning"| node_xgb_artifact
node_shap_work -.->|"explores explanations"| node_explainer

click node_fastapi "https://github.com/theshahnawazali/argus/blob/main/main.py"
click node_request_schema "https://github.com/theshahnawazali/argus/blob/main/schemas/predict.py"
click node_dataset "https://github.com/theshahnawazali/argus/tree/main/data/raw"
click node_config "https://github.com/theshahnawazali/argus/blob/main/pipeline/config.py"
click node_loader "https://github.com/theshahnawazali/argus/blob/main/pipeline/data_loader.py"
click node_split "https://github.com/theshahnawazali/argus/blob/main/pipeline/train.py"
click node_transformers "https://github.com/theshahnawazali/argus/blob/main/pipeline/transformers.py"
click node_builder "https://github.com/theshahnawazali/argus/blob/main/pipeline/pipeline_builder.py"
click node_xgb_artifact "https://github.com/theshahnawazali/argus/blob/main/models/xgb_pipeline.pkl"
click node_gbm_artifact "https://github.com/theshahnawazali/argus/blob/main/models/gbm_pipeline.pkl"
click node_metrics "https://github.com/theshahnawazali/argus/blob/main/main.py"
click node_explainer "https://github.com/theshahnawazali/argus/blob/main/pipeline/explain.py"
click node_tuning "https://github.com/theshahnawazali/argus/blob/main/notebooks/05_hyperparameter_tunning.ipynb"
click node_shap_work "https://github.com/theshahnawazali/argus/blob/main/notebooks/09_shap_explainability.ipynb"

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_fastapi,node_request_schema toneBlue
class node_config,node_loader,node_split,node_dataset toneAmber
class node_transformers,node_builder,node_xgb_artifact,node_gbm_artifact,node_tuning,node_client toneMint
class node_metrics,node_explainer,node_shap_work toneRose
```

## Components

### API actions

- [FastAPI routes](https://github.com/theshahnawazali/argus/blob/main/main.py): `main.py`
- [Explanation request](https://github.com/theshahnawazali/argus/blob/main/schemas/predict.py): `schemas/predict.py`

### Data preparation

- [Paths and parameters](https://github.com/theshahnawazali/argus/blob/main/pipeline/config.py): `pipeline/config.py`
- [Data loader](https://github.com/theshahnawazali/argus/blob/main/pipeline/data_loader.py): `pipeline/data_loader.py`
- [Train-test split](https://github.com/theshahnawazali/argus/blob/main/pipeline/train.py): `pipeline/train.py`

### Model lifecycle

- [Missing-value handler](https://github.com/theshahnawazali/argus/blob/main/pipeline/transformers.py): `pipeline/transformers.py`
- [Pipeline builders](https://github.com/theshahnawazali/argus/blob/main/pipeline/pipeline_builder.py): `pipeline/pipeline_builder.py`
- [XGBoost pipeline](https://github.com/theshahnawazali/argus/blob/main/models/xgb_pipeline.pkl): `models/xgb_pipeline.pkl`
- [GBM pipeline](https://github.com/theshahnawazali/argus/blob/main/models/gbm_pipeline.pkl): `models/gbm_pipeline.pkl`
- [Hyperparameter tuning](https://github.com/theshahnawazali/argus/blob/main/notebooks/05_hyperparameter_tunning.ipynb): `notebooks/05_hyperparameter_tunning.ipynb`

### Evaluation and explanation

- [Evaluation metrics](https://github.com/theshahnawazali/argus/blob/main/main.py): `main.py`
- [SHAP explanations](https://github.com/theshahnawazali/argus/blob/main/pipeline/explain.py): `pipeline/explain.py`
- [SHAP analysis](https://github.com/theshahnawazali/argus/blob/main/notebooks/09_shap_explainability.ipynb): `notebooks/09_shap_explainability.ipynb`

### Other components

- **API caller**
- [IEEE-CIS files](https://github.com/theshahnawazali/argus/tree/main/data/raw): `data/raw`

## Connections

- API caller → FastAPI routes: calls routes
- FastAPI routes → Explanation request: validates request
- FastAPI routes → Data loader: loads data
- Data loader → IEEE-CIS files: reads and joins
- FastAPI routes → Paths and parameters: uses settings
- FastAPI routes → Train-test split: splits data
- FastAPI routes → Pipeline builders: builds pipeline
- Pipeline builders → Missing-value handler: uses transformer
- FastAPI routes → XGBoost pipeline: trains and saves
- FastAPI routes → GBM pipeline: trains and saves
- FastAPI routes → XGBoost pipeline: loads for evaluation
- FastAPI routes → Evaluation metrics: computes metrics
- FastAPI routes → SHAP explanations: requests explanation
- SHAP explanations → XGBoost pipeline: loads pipeline
- SHAP explanations → GBM pipeline: loads pipeline
- Hyperparameter tuning → XGBoost pipeline: documents tuning
- SHAP analysis → SHAP explanations: explores explanations