# iencryptsaad/fraudulent-transaction-detection architecture

> Architecture diagram of the GitHub repository iencryptsaad/fraudulent-transaction-detection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iencryptsaad/fraudulent-transaction-detection
- Repository: https://github.com/iencryptsaad/fraudulent-transaction-detection

## Overview

##### Project Type and Purpose
- This is an end-to-end machine learning pipeline for financial fraud detection, implemented primarily in Jupyter notebooks.
- It ingests transactional data, performs preprocessing and feature engineering, builds and evaluates an XGBoost classifier (with SMOTE for class imbalance), and generates explainability visualizations via SHAP.

##### High-Level File Structure Overview
- Top-level:
- README.md, requirements.txt (project metadata)
- .gitignore
- notebook/
- fraud_detection_pipeline.ipynb (pipeline orchestration)
- xgboost_fraud_model.model (serialized model)
- plots/ (SHAP force plots, other HTML visualizations)

##### Key Components
a. Data Ingestion & Storage
- Raw transaction data (e.g., CSV/DB) → pandas DataFrame
b. Preprocessing & Feature Engineering
- Anomaly‐focused feature generator modules
- SMOTE oversampling for class balancing
c. Model Training & Evaluation
- XGBoost training component
- Evaluation sub‐component (confusion matrix, ROC‐AUC)
d. Model Persistence
- joblib/.model serialization
e. Explainability & Visualization
- SHAP value engine → global & local explainers
- Output visualizations (matplotlib/seaborn, SHAP plots)
f. Deployment Interfaces (optional/future)
- Flask API or Streamlit GUI
- Monitoring/dashboarding components

##### Architectural Patterns and Principles
- Modular pipeline stages (ETL → FE → Modeling → Eval → Explain)
- Single notebook acts as pipeline orchestrator
- Separation of concerns: data logic, modeling logic, explainability logic
- Reproducibility via versioned model artifact

##### Technologies & Frameworks to Annotate
- Python (Jupyter Notebook)
- pandas, numpy (data handling)
- imbalanced-learn SMOTE (oversampling)
- scikit-learn, XGBoost (modeling)
- SHAP (explainability)
- matplotlib/seaborn (visualization)
- joblib (model serialization)
- (Future) Flask, Streamlit (deployment)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Project Metadata"
        README["README.md"]:::meta
        Req["requirements.txt"]:::meta
        GIT[".gitignore"]:::meta
    end

    Orch["Pipeline Orchestration Notebook"]:::process
    click Orch "https://github.com/iencryptsaad/fraudulent-transaction-detection/blob/main/notebook/fraud_detection_pipeline.ipynb"

    subgraph "Data Ingestion & Storage"
        Raw["Raw Transaction Data"]:::data
    end

    subgraph "Preprocessing"
        Pre["Preprocessing & Cleaning"]:::process
    end

    subgraph "Feature Engineering"
        FE["Anomaly‐Focused Feature Engineering"]:::process
    end

    SMOTE["SMOTE Oversampling"]:::process

    subgraph "Modeling"
        Train["XGBoost Training"]:::model
        Eval["Evaluation (Confusion Matrix & ROC-AUC)"]:::model
    end

    Persist["Model Persistence (.model)"]:::store
    click Persist "https://github.com/iencryptsaad/fraudulent-transaction-detection/blob/main/notebook/xgboost_fraud_model.model"

    subgraph "Explainability & Visualization"
        SHAPengine["SHAP Value Engine"]:::explain
        SHAPviz["SHAP Visualizations"]:::explain
        SHAPForce["SHAP Force Plot"]:::explain
    end
    click SHAPviz "https://github.com/iencryptsaad/fraudulent-transaction-detection/tree/main/notebook/plots/"
    click SHAPForce "https://github.com/iencryptsaad/fraudulent-transaction-detection/blob/main/notebook/plots/shap_force_plot.html"

    Deploy["Deployment Interface (Flask/Streamlit)"]:::deploy

    %% Data Flow
    Orch --> Raw
    Raw -->|"DataFrame"| Pre
    Pre -->|"Clean DF"| FE
    FE -->|"Features"| SMOTE
    SMOTE -->|"Balanced DF"| Train
    Train -->|"Trained Model"| Eval
    Eval -->|"Metrics & Plots"| Persist
    Persist -->|"Serialized Model"| SHAPengine
    SHAPengine -->|"SHAP Values"| SHAPviz
    SHAPviz -->|"Force Plot"| SHAPForce
    Persist -->|"Exposed Model API"| Deploy

    %% Class Definitions
    classDef data fill:#FFD54F,stroke:#BF360C,color:#000;
    classDef process fill:#81D4FA,stroke:#0277BD,color:#000;
    classDef model fill:#A5D6A7,stroke:#2E7D32,color:#000;
    classDef store fill:#CE93D8,stroke:#6A1B9A,color:#000;
    classDef explain fill:#FFAB91,stroke:#D84315,color:#000;
    classDef deploy fill:#B39DDB,stroke:#512DA8,color:#000;
    classDef meta fill:#EEEEEE,stroke:#424242,color:#000;
```
