# alirezamohamadian1998/default-prediction architecture

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

- Interactive diagram: https://gitdiagram.com/alirezamohamadian1998/default-prediction
- Repository: https://github.com/alirezamohamadian1998/default-prediction

## Overview

This repository implements an AMEX customer-default risk pipeline: validate monthly statements and labels, aggregate histories into customer-level features, train and select LightGBM models, then score new customers with an ensemble and saved threshold. Supporting branches tune hyperparameters and analyze model results and probability calibration. DuckDB-backed auditing and feature aggregation form the preparation layer. Relationships reflect the README and shown imports/calls; unsampled modules are included only for documented capabilities, with no inferred internal call chains.

Main entry points: [`src/amex_default/prepare.py`](https://github.com/alirezamohamadian1998/default-prediction/blob/main/src/amex_default/prepare.py) (History preparation), [`src/amex_default/predict.py`](https://github.com/alirezamohamadian1998/default-prediction/blob/main/src/amex_default/predict.py) (Ensemble prediction), [`src/amex_default/audit.py`](https://github.com/alirezamohamadian1998/default-prediction/blob/main/src/amex_default/audit.py) (Dataset audit), [`src/amex_default/train.py`](https://github.com/alirezamohamadian1998/default-prediction/blob/main/src/amex_default/train.py) (Baseline training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_preparation["Data preparation"]
  node_audit["Dataset audit<br/>[audit.py]"]
  node_duckdb["DuckDB access<br/>[database.py]"]
  node_features["Feature expressions<br/>[features.py]"]
  node_prepare["History preparation<br/>[prepare.py]"]
end

subgraph group_modeling["Model development"]
  node_train["Baseline training<br/>[train.py]"]
  node_metrics["Risk metrics<br/>[metrics.py]"]
  node_tune["Hyperparameter tuning<br/>[tune.py]"]
  node_select["Candidate selection<br/>[select_model.py]"]
end

subgraph group_scoring["Prediction"]
  node_predict["Ensemble prediction<br/>[predict.py]"]
end

subgraph group_analysis["Evaluation"]
  node_results["Model results analysis<br/>[model_results.py]"]
  node_calibration["Calibration evaluation"]
end

node_data["Statement data"]
node_labels["Default labels"]
node_operator(("Pipeline operator"))
node_prepared["Customer features"]
node_model["Selected fold models"]
node_predictions["Customer predictions"]

node_operator -->|"runs audit"| node_audit
node_data -->|"validates"| node_audit
node_labels -->|"checks coverage"| node_audit
node_audit -->|"queries via"| node_duckdb
node_operator -->|"runs preparation"| node_prepare
node_prepare -->|"audits inputs"| node_audit
node_prepare -->|"uses expressions"| node_features
node_prepare -->|"connects through"| node_duckdb
node_data -->|"aggregates histories"| node_prepare
node_prepare -->|"writes features"| node_prepared
node_operator -->|"runs training"| node_train
node_prepared -->|"trains on"| node_train
node_labels -->|"trains against"| node_train
node_train -->|"evaluates with"| node_metrics
node_operator -->|"runs tuning"| node_tune
node_prepared -->|"tunes on"| node_tune
node_labels -->|"tunes against"| node_tune
node_tune -->|"scores trials"| node_metrics
node_operator -->|"runs comparison"| node_select
node_select -->|"reuses training"| node_train
node_select -->|"retains winner"| node_model
node_operator -->|"runs scoring"| node_predict
node_data -->|"provides statements"| node_predict
node_predict -->|"prepares features"| node_prepare
node_model -->|"supplies ensemble"| node_predict
node_predict -->|"writes probabilities"| node_predictions
node_operator -->|"runs analysis"| node_results
node_results -->|"compares artifacts"| node_model
node_operator -->|"runs evaluation"| node_calibration
node_predictions -->|"evaluates probabilities"| node_calibration

click node_audit "https://github.com/alirezamohamadian1998/default-prediction/blob/main/src/amex_default/audit.py"
click node_duckdb "https://github.com/alirezamohamadian1998/default-prediction/blob/main/src/amex_default/database.py"
click node_features "https://github.com/alirezamohamadian1998/default-prediction/blob/main/src/amex_default/features.py"
click node_prepare "https://github.com/alirezamohamadian1998/default-prediction/blob/main/src/amex_default/prepare.py"
click node_train "https://github.com/alirezamohamadian1998/default-prediction/blob/main/src/amex_default/train.py"
click node_metrics "https://github.com/alirezamohamadian1998/default-prediction/blob/main/src/amex_default/metrics.py"
click node_tune "https://github.com/alirezamohamadian1998/default-prediction/blob/main/src/amex_default/tune.py"
click node_select "https://github.com/alirezamohamadian1998/default-prediction/blob/main/src/amex_default/select_model.py"
click node_predict "https://github.com/alirezamohamadian1998/default-prediction/blob/main/src/amex_default/predict.py"
click node_results "https://github.com/alirezamohamadian1998/default-prediction/blob/main/analysis/model_results.py"
click node_calibration "https://github.com/alirezamohamadian1998/default-prediction/blob/main/analysis/evaluate_calibration.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_audit,node_duckdb,node_features,node_prepare toneBlue
class node_train,node_metrics,node_tune,node_select toneAmber
class node_predict toneMint
class node_results,node_calibration toneRose
class node_data,node_labels,node_operator,node_prepared,node_model,node_predictions toneIndigo
```

## Components

### Data preparation

- [Dataset audit](https://github.com/alirezamohamadian1998/default-prediction/blob/main/src/amex_default/audit.py): `src/amex_default/audit.py`
- [DuckDB access](https://github.com/alirezamohamadian1998/default-prediction/blob/main/src/amex_default/database.py): `src/amex_default/database.py`
- [Feature expressions](https://github.com/alirezamohamadian1998/default-prediction/blob/main/src/amex_default/features.py): `src/amex_default/features.py`
- [History preparation](https://github.com/alirezamohamadian1998/default-prediction/blob/main/src/amex_default/prepare.py): `src/amex_default/prepare.py`

### Model development

- [Baseline training](https://github.com/alirezamohamadian1998/default-prediction/blob/main/src/amex_default/train.py): `src/amex_default/train.py`
- [Risk metrics](https://github.com/alirezamohamadian1998/default-prediction/blob/main/src/amex_default/metrics.py): `src/amex_default/metrics.py`
- [Hyperparameter tuning](https://github.com/alirezamohamadian1998/default-prediction/blob/main/src/amex_default/tune.py): `src/amex_default/tune.py`
- [Candidate selection](https://github.com/alirezamohamadian1998/default-prediction/blob/main/src/amex_default/select_model.py): `src/amex_default/select_model.py`

### Prediction

- [Ensemble prediction](https://github.com/alirezamohamadian1998/default-prediction/blob/main/src/amex_default/predict.py): `src/amex_default/predict.py`

### Evaluation

- [Model results analysis](https://github.com/alirezamohamadian1998/default-prediction/blob/main/analysis/model_results.py): `analysis/model_results.py`
- [Calibration evaluation](https://github.com/alirezamohamadian1998/default-prediction/blob/main/analysis/evaluate_calibration.py): `analysis/evaluate_calibration.py`

### Other components

- **Statement data**
- **Default labels**
- **Pipeline operator**
- **Customer features**
- **Selected fold models**
- **Customer predictions**

## Connections

- Pipeline operator → Dataset audit: runs audit (evidence: `README.md`)
- Statement data → Dataset audit: validates (evidence: `README.md`)
- Default labels → Dataset audit: checks coverage (evidence: `README.md`)
- Dataset audit → DuckDB access: queries via (evidence: `src/amex_default/audit.py`)
- Pipeline operator → History preparation: runs preparation (evidence: `README.md`)
- History preparation → Dataset audit: audits inputs (evidence: `src/amex_default/prepare.py`)
- History preparation → Feature expressions: uses expressions (evidence: `src/amex_default/prepare.py`)
- History preparation → DuckDB access: connects through (evidence: `src/amex_default/prepare.py`)
- Statement data → History preparation: aggregates histories (evidence: `README.md`)
- History preparation → Customer features: writes features (evidence: `README.md`)
- Pipeline operator → Baseline training: runs training (evidence: `README.md`)
- Customer features → Baseline training: trains on (evidence: `README.md`)
- Default labels → Baseline training: trains against (evidence: `README.md`)
- Baseline training → Risk metrics: evaluates with (evidence: `src/amex_default/train.py`)
- Pipeline operator → Hyperparameter tuning: runs tuning (evidence: `README.md`)
- Customer features → Hyperparameter tuning: tunes on (evidence: `README.md`)
- Default labels → Hyperparameter tuning: tunes against (evidence: `README.md`)
- Hyperparameter tuning → Risk metrics: scores trials (evidence: `src/amex_default/tune.py`)
- Pipeline operator → Candidate selection: runs comparison (evidence: `README.md`)
- Candidate selection → Baseline training: reuses training (evidence: `src/amex_default/select_model.py`)
- Candidate selection → Selected fold models: retains winner (evidence: `README.md`)
- Pipeline operator → Ensemble prediction: runs scoring (evidence: `README.md`)
- Statement data → Ensemble prediction: provides statements (evidence: `README.md`)
- Ensemble prediction → History preparation: prepares features (evidence: `src/amex_default/predict.py`)
- Selected fold models → Ensemble prediction: supplies ensemble (evidence: `README.md`)
- Ensemble prediction → Customer predictions: writes probabilities (evidence: `README.md`)
- Pipeline operator → Model results analysis: runs analysis (evidence: `README.md`)
- Model results analysis → Selected fold models: compares artifacts (evidence: `README.md`)
- Pipeline operator → Calibration evaluation: runs evaluation (evidence: `README.md`)
- Customer predictions → Calibration evaluation: evaluates probabilities (evidence: `README.md`)
