# juniorcl/transaction-fraud-detection architecture

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

- Interactive diagram: https://gitdiagram.com/juniorcl/transaction-fraud-detection
- Repository: https://github.com/juniorcl/transaction-fraud-detection

## Overview

##### Project type and purpose
- This is a data-science project for transaction fraud detection, culminating in a lightweight Flask API that serves a trained XGBoost model.
- Its primary purpose is to take incoming transaction data, apply preprocessing (scaling, one-hot encoding), run the model, and return a fraud/non-fraud prediction.

##### File structure
Top-level directories:
- api/      ← Flask service
– handler.py
– fraud/Fraud.py  ← logic to load artifacts and serve predictions
- data/     ← raw data storage
– raw/fraud_0.1origbase.csv
- functions/← serialized preprocessing artifacts
– minmaxscaler_cycle1.joblib
– onehotencoder_cycle1.joblib
- models/   ← serialized trained model
– model_cycle1.joblib
- notebooks/← exploratory EDA and training pipeline in Jupyter
- reports/  ← figures and business results
- requirements.txt, README.md, LICENSE

##### README for additional insights
- Confirms a 10-step data science workflow from data description → EDA → feature engineering → model training → hyperparameter tuning → deployment.
- Final step “Model Deploy” uses Flask and joblib artifacts.

##### Main components
1. Data Source
- CSV store (data/raw)
- (Future: production database or streaming source)
2. Data Processing & Model Training (Offline Batch Pipeline)
- Jupyter Notebook component (notebooks/)
- Preprocessing jobs:
– min-max scaler
– one-hot encoder
- Feature selection & model training (XGBoost)
- Model registry (models/model_cycle1.joblib) and preprocessing artifacts (functions/*.joblib)
3. Model Serving (Flask API)
- API Container (api/handler.py)
- Fraud module (api/fraud/Fraud.py) loads joblib artifacts
- HTTP endpoint(s) receive JSON transaction → preprocess → predict → JSON response
4. Client / Consumer
- External client (web app, batch job, mobile app) invoking the HTTP REST endpoint
5. Reporting & Monitoring (Optional)
- reports/ figures archive
- (Future: add metrics store or dashboard)

##### Relationships & interactions
- Offline pipeline reads raw CSV → transforms → fits model → exports artifacts.
- Serving container mounts or loads artifacts at start-up.
- Client → HTTP POST → Flask API → Fraud.py pipeline → joblib scaler → joblib encoder → joblib model → response.
- (Optional) Logs metrics or stores predictions in a database.

##### Architectural patterns & design principles
- Separation of concerns:
- Offline ETL & training vs. online inference
- Preprocessing artifacts decoupled from code, loaded at runtime
- Modular design: each component (scaler, encoder, model) is its own artifact and function.
- Microservice: single‐purpose Flask API for inference.

##### Relevant technologies & frameworks
- Python 3.x
- Flask (api/handler.py)
- joblib (serialize/deserialize scaler, encoder, model)
- XGBoost (model training library)
- Jupyter Notebooks (EDA & prototyping)

##### Detail is crucial
- Every key module (minmaxscaler, onehotencoder, model) as its own node.
- “api/fraud/Fraud.py” component separately from handler.py.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Offline Batch Pipeline
    subgraph "Offline Batch Pipeline"
        direction TB
        RawCSV["Raw Data Store\n(data/raw)"]:::database
        Notebook["Jupyter Notebook\n(transaction-fraud-detection-cycle1.ipynb)"]:::batch
        Scaler["Preprocessing Artifact\n(MinMax Scaler)"]:::batch
        Encoder["Preprocessing Artifact\n(OneHot Encoder)"]:::batch
        ModelReg["Model Registry\n(XGBoost Model)"]:::batch
        Reports["Figures Archive\n(reports/figures)"]:::reports

        RawCSV -->|"load CSV"| Notebook
        Notebook -->|"fit scaler"| Scaler
        Notebook -->|"fit encoder"| Encoder
        Notebook -->|"train model"| ModelReg
        Notebook -->|"generate figures"| Reports
    end

    %% Online Serving Pipeline
    subgraph "Online Inference Pipeline"
        direction TB
        Client["External Client\n(Web/Mobile)"]:::external
        Handler["Flask API Handler\n(handler.py)"]:::api
        FraudModule["Fraud Prediction Module\n(Fraud.py)"]:::api
        Dependencies["Project Dependencies"]:::docs
        DocsSubgraph["Documentation"]:::docs
        subgraph "Documentation"
            direction TB
            Req["requirements.txt"]:::docs
            Readme["README.md"]:::docs
            License["LICENSE"]:::docs
        end

        Client -->|"HTTP POST"| Handler
        Handler -->|"invoke prediction"| FraudModule
        FraudModule -->|"apply scaler"| Scaler
        FraudModule -->|"apply encoder"| Encoder
        FraudModule -->|"run model"| ModelReg
        FraudModule -->|"return result"| Handler
        Handler -->|"HTTP Response"| Client
        Handler -->|"log/report"| Reports
    end

    %% Click Events
    click RawCSV "https://github.com/juniorcl/transaction-fraud-detection/blob/main/data/raw/fraud_0.1origbase.csv"
    click Notebook "https://github.com/juniorcl/transaction-fraud-detection/blob/main/notebooks/transaction-fraud-detection-cycle1.ipynb"
    click Scaler "https://github.com/juniorcl/transaction-fraud-detection/blob/main/functions/minmaxscaler_cycle1.joblib"
    click Encoder "https://github.com/juniorcl/transaction-fraud-detection/blob/main/functions/onehotencoder_cycle1.joblib"
    click ModelReg "https://github.com/juniorcl/transaction-fraud-detection/blob/main/models/model_cycle1.joblib"
    click Handler "https://github.com/juniorcl/transaction-fraud-detection/blob/main/api/handler.py"
    click FraudModule "https://github.com/juniorcl/transaction-fraud-detection/blob/main/api/fraud/Fraud.py"
    click Reports "https://github.com/juniorcl/transaction-fraud-detection/tree/main/reports/figures"
    click Req "https://github.com/juniorcl/transaction-fraud-detection/blob/main/requirements.txt"
    click Readme "https://github.com/juniorcl/transaction-fraud-detection/blob/main/README.md"
    click License "https://github.com/juniorcl/transaction-fraud-detection/tree/main/LICENSE"

    %% Styles
    classDef batch fill:#D6E9FF,stroke:#4A90E2
    classDef api fill:#E8F5E9,stroke:#388E3C
    classDef database fill:#FFF3E0,stroke:#FB8C00,stroke-width:2px
    classDef external fill:#FFEBEE,stroke:#D32F2F
    classDef reports fill:#F3E5F5,stroke:#8E24AA
    classDef docs fill:#ECEFF1,stroke:#607D8B
```
