# vik1292/auto-loan-project architecture

> Architecture diagram of the GitHub repository vik1292/auto-loan-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vik1292/auto-loan-project
- Repository: https://github.com/vik1292/auto-loan-project

## Overview

##### Project Type & Purpose
- This is a standalone, command-line driven machine-learning pipeline for auto-loan default risk prediction.
- Key capabilities: data generation/ingestion, preprocessing & feature engineering, model training & selection, model explainability (SHAP), and automated risk-assessment reporting.

##### File Structure (High-Level Components)
- **main.py / run_demo.py**: CLI entry points driving the pipeline modes (full, train, report).
- **src/**: Core modules, each implementing a pipeline stage:
- data_generator.py (synthetic data ingestion)
- data_preprocessing.py (cleaning + feature engineering)
- model_training.py (train & evaluate LogisticRegression, RF, XGBoost + select best)
- model_explainability.py (SHAP analysis)
- risk_assessment_report.py (risk categorization, summary + detailed reports)
- **data/**: Raw and processed datasets.
- **models/**: Serialized trained model artifacts (best_model.pkl).
- **output/** (described in README): Generated reports, plots, JSON for dashboards.
- **logs/**: Application log files.
- **requirements.txt / setup.py**: Environment & deployment config.

##### Main Components & Their Interactions
a. Data Ingestion
- Synthetic generation (data_generator.py) or user-supplied CSV (--data-file).
- Output: raw data → data/raw storage.
b. Data Preprocessing & Feature Engineering
- Reads raw data → cleans, engineers features (DTI, payment ratios).
- Outputs processed dataset → data/processed storage.
c. Model Training & Selection
- Trains multiple models, evaluates metrics (ROC, AUC).
- Selects best model → serializes to models/best_model.pkl.
d. Model Explainability
- Loads best_model → computes SHAP values → generates feature importance, waterfall plots.
- Outputs visuals & JSON summaries.
e. Risk Assessment & Reporting
- Applies best_model on processed data → computes risk scores.
- Categorizes risk levels (High, Medium, Low).
- Produces: executive summary (.txt), detailed customer reports, dashboard_data.json.
f. Logging & Monitoring
- All stages emit logs to logs/ for debugging & audit.
g. CLI Interface
- main.py orchestrates modes (full, train, report), wiring all components in sequence.

##### Architectural Patterns & Design Principles
- Pipeline / ETL pattern: sequential stages with clear inputs/outputs.
- Modular separation: each src/ module encapsulates one concern.
- Artifact management: models/ for model binaries; data/ for datasets; output/ for results.

##### Technologies & Frameworks
- Python 3.7+
- pandas, numpy for data handling
- scikit-learn, xgboost for modeling
- shap for explainability
- matplotlib, seaborn for plots
- joblib for serialization

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Interfaces
    User["User (CLI)"]:::external
    Dashboard["Dashboard"]:::external

    %% CLI Orchestrator
    subgraph "CLI Orchestrator"
        direction TB
        CLI1[/main.py/]:::cli
        CLI2[/run_demo.py/]:::cli
    end

    %% Pipeline Modules
    subgraph "Pipeline Modules"
        direction TB
        DI["Data Ingestion<br/>(data_generator.py)"]:::process
        DP["Data Preprocessing<br/>(data_preprocessing.py)"]:::process
        MT["Model Training & Selection<br/>(model_training.py)"]:::model
        ME["Model Explainability<br/>(model_explainability.py)"]:::model
        RR["Risk Assessment & Reporting<br/>(risk_assessment_report.py)"]:::report
    end

    %% Artifact Repositories
    subgraph "Artifact Repositories"
        direction TB
        RawData[(Raw Data Store<br/>data/)]:::datastore
        ProcessedData[(Processed Data Store<br/>data/)]:::datastore
        ModelStore[(Model Store<br/>models/)]:::datastore
        OutputStore[(Output Reports & JSON<br/>output/)]:::datastore
        LogsStore[(Logs Store<br/>logs/)]:::logs
    end

    %% Data Flow
    User -->|runs| CLI1
    User -->|runs| CLI2
    CLI1 -->|full/train/report| DI
    CLI2 -->|demo mode| DI

    DI -->|raw_data.csv| RawData
    RawData -->|read| DP
    DP -->|processed_data.csv| ProcessedData
    ProcessedData -->|features.csv| MT
    MT -->|best_model.pkl| ModelStore
    ModelStore -->|model load| ME
    ME -->|shap_summary.json<br/>shap_plots.png| OutputStore
    ProcessedData -->|features.csv| RR
    ModelStore -->|best_model.pkl| RR
    RR -->|reports.txt<br/>dashboard_data.json| OutputStore
    OutputStore -->|json| Dashboard

    %% Logging
    DI -->|logs| LogsStore
    DP -->|logs| LogsStore
    MT -->|logs| LogsStore
    ME -->|logs| LogsStore
    RR -->|logs| LogsStore
    CLI1 -->|logs| LogsStore
    CLI2 -->|logs| LogsStore

    %% Click Events
    click CLI1 "https://github.com/vik1292/auto-loan-project/blob/main/main.py"
    click CLI2 "https://github.com/vik1292/auto-loan-project/blob/main/run_demo.py"
    click DI "https://github.com/vik1292/auto-loan-project/blob/main/src/data_generator.py"
    click DP "https://github.com/vik1292/auto-loan-project/blob/main/src/data_preprocessing.py"
    click MT "https://github.com/vik1292/auto-loan-project/blob/main/src/model_training.py"
    click ME "https://github.com/vik1292/auto-loan-project/blob/main/src/model_explainability.py"
    click RR "https://github.com/vik1292/auto-loan-project/blob/main/src/risk_assessment_report.py"
    click RawData "https://github.com/vik1292/auto-loan-project/tree/main/data/"
    click ProcessedData "https://github.com/vik1292/auto-loan-project/tree/main/data/"
    click ModelStore "https://github.com/vik1292/auto-loan-project/tree/main/models/"
    click LogsStore "https://github.com/vik1292/auto-loan-project/tree/main/logs/"

    %% Styles
    classDef external fill:#E6E6FA,stroke:#333,stroke-width:1px
    classDef cli fill:#D8BFD8,stroke:#333,stroke-width:1px
    classDef process fill:#98FB98,stroke:#333,stroke-width:1px
    classDef model fill:#FFA500,stroke:#333,stroke-width:1px
    classDef report fill:#FFFF99,stroke:#333,stroke-width:1px
    classDef datastore fill:#ADD8E6,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef logs fill:#D3D3D3,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
