# chuksoo/sneaky-swipe-detector architecture

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

- Interactive diagram: https://gitdiagram.com/chuksoo/sneaky-swipe-detector
- Repository: https://github.com/chuksoo/sneaky-swipe-detector

## Overview

##### Project Type and Purpose
- This is a machine‐learning‐driven fraud detection service built in Python. Its main goal is to ingest transaction data, preprocess it, train a classification model to spot fraudulent “sneaky swipes,” and then make predictions on new data.
- Key features:
- Data ingestion & storage (raw Parquet files)
- Data preprocessing & feature engineering
- Model training pipeline
- Model inference/prediction pipeline
- Supporting notebooks for exploration and reports for documentation

##### File Structure Analysis
- Top‐level directories:
- data/raw: raw transaction datasets (Parquet)
- environment: setup docs and Conda/YAML files
- notebooks: Jupyter notebooks for exploratory data analysis
- reports: PDF/TeX end-to-end project plan
- scripts: operational scripts (data_download.py, train.py, predict.py, plotting.py)
- src/fraud_detection: core Python package (main service logic + utility modules)
- src/tests: unit tests for models and utilities
- Patterns & conventions:
- Scripts orchestrate each stage (download → preprocess → train → predict)
- Core logic isolated under src/fraud_detection (separation of concerns: data, utils, main entry point)
- Tests mirror code structure under src/tests for CI coverage

##### Key Insights from README
- Emphasis on a modular pipeline (data → features → modeling → API if added in future)
- Plans for orchestration (Prefect/Airflow) and deployment (Docker/Kubernetes), though not yet present
- Clear separation of concerns: development (notebooks), operations (scripts), packaging (setup.py), testing

a. Main Components
1. Data Store
– Raw Data (Parquet files under data/raw)
– Artifacts (trained model files saved locally or in a models/ directory)
2. Data Ingestion & Preprocessing
– script: data_download.py
– module: fraud_detection.utils.data_preprocessing
3. Feature Engineering & Utility Functions
– module: fraud_detection.utils.utils
4. Model Training Pipeline
– script: train.py
– entry point: src/fraud_detection/main.py (train flow)
5. Model Serving / Inference
– script: predict.py
– entry point: src/fraud_detection/main.py (predict flow)
6. Notebooks & Reports
– notebooks: exploratory analysis (sneaky-swipe-detect.ipynb)
– reports: project plan documentation
7. Testing & CI
– src/tests/test_models.py, src/tests/utils.py
8. Environment & Packaging
– environment/*.yml, setup.py, requirements.txt

b. Relationships and Data Flow
1. Data Download → Raw Data Store
2. Raw Data → Preprocessing Module → Processed Data
3. Processed Data → Feature Engineering → Training Routine
4. Training Routine → Trained Model Artifact
5. Trained Model + New Input Data → Inference Routine → Predictions
6. Notebooks read Raw/Processed Data & Trained Model for analysis and visualization
7. Tests validate utility modules and model outputs

c. Architectural Patterns & Design Principles
- Modular pipeline: each stage separated into scripts and library code
- Single-responsibility: preprocessing, training, inference isolated
- Test-driven development: mirrors code structure in src/tests
- Future-ready for orchestration/deployment: clear boundaries facilitate adding Prefect/Airflow or Docker

d. Technologies & Frameworks
- Python 3.x
- pandas, scikit-learn (or similar) for data processing & modeling
- parquet for data storage
- pytest (or unittest) for testing
- Conda/YAML for environment reproducibility

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer"
        RawData(("Raw Transaction Data")):::dataBlue
    end

    %% Processing Layer
    subgraph "Processing Layer"
        DataDownloadScript["data_download.py: Data Ingestion Script"]:::processingGreen
        DataPreprocessingModule["data_preprocessing.py: Preprocessing Module"]:::processingGreen
        UtilsModule["utils.py: Feature Engineering & Utility Functions"]:::processingGreen
    end

    %% Model Layer
    subgraph "Model Layer"
        TrainScript["train.py: Model Training Script"]:::processingGreen
        MainEntrypointTrain["main.py: Training Flow"]:::processingGreen
        ModelArtifact(("Trained Model Artifact")):::artifactOrange
        PredictScript["predict.py: Model Inference Script"]:::processingGreen
        MainEntrypointPredict["main.py: Prediction Flow"]:::processingGreen
        Predictions[/Predictions Output/]:::artifactOrange
    end

    %% Supporting Components
    subgraph "Supporting"
        ExploratoryNotebook[/sneaky-swipe-detect.ipynb: Exploratory Notebook/]:::supportGray
        ProjectReport[/End-to-end Project Plan.pdf: Project Plan Report/]:::supportGray
        ModelTests["test_models.py: Model Tests"]:::supportGray
        UtilTests["utils.py: Utility Tests"]:::supportGray
        EnvDoc["environment-setup.md: Environment Setup Doc"]:::supportGray
        CondaMac["fraud-service-mac.yml"]:::supportGray
        CondaWin["fraud-service-win.yml"]:::supportGray
        SetupConfig["setup.py: Package Configuration"]:::supportGray
        ReqList["requirements.txt: Dependency List"]:::supportGray
        CIJob["CI Job"]:::supportGray
    end

    %% Data Flow Arrows
    DataDownloadScript -->|writes Parquet| RawData
    RawData -->|loads DataFrame| DataPreprocessingModule
    DataPreprocessingModule -->|engineers Features| UtilsModule
    UtilsModule -->|feeds DataFrame| TrainScript
    TrainScript -->|calls| MainEntrypointTrain
    MainEntrypointTrain -->|outputs Model| ModelArtifact
    ModelArtifact -->|loaded by| MainEntrypointPredict
    PredictScript -->|calls| MainEntrypointPredict
    MainEntrypointPredict -->|produces| Predictions

    %% Notebook & Report Access
    RawData -->|reads| ExploratoryNotebook
    ModelArtifact -->|reads| ExploratoryNotebook
    ProjectReport

    %% Testing & CI
    CIJob -.->|triggers| ModelTests
    CIJob -.->|triggers| UtilTests
    ModelTests -.->|tests| MainEntrypointTrain
    UtilTests -.->|tests| UtilsModule

    %% Click Events
    click RawData "https://github.com/chuksoo/sneaky-swipe-detector/blob/main/data/raw/sweaky-swipe-transactions.parquet"
    click DataDownloadScript "https://github.com/chuksoo/sneaky-swipe-detector/blob/main/scripts/data_download.py"
    click DataPreprocessingModule "https://github.com/chuksoo/sneaky-swipe-detector/blob/main/src/fraud_detection/utils/data_preprocessing.py"
    click UtilsModule "https://github.com/chuksoo/sneaky-swipe-detector/blob/main/src/fraud_detection/utils/utils.py"
    click TrainScript "https://github.com/chuksoo/sneaky-swipe-detector/blob/main/scripts/train.py"
    click MainEntrypointTrain "https://github.com/chuksoo/sneaky-swipe-detector/blob/main/src/fraud_detection/main.py"
    click PredictScript "https://github.com/chuksoo/sneaky-swipe-detector/blob/main/scripts/predict.py"
    click MainEntrypointPredict "https://github.com/chuksoo/sneaky-swipe-detector/blob/main/src/fraud_detection/main.py"
    click ExploratoryNotebook "https://github.com/chuksoo/sneaky-swipe-detector/blob/main/notebooks/sneaky-swipe-detect.ipynb"
    click ProjectReport "https://github.com/chuksoo/sneaky-swipe-detector/blob/main/reports/End-to-end Project Plan.pdf"
    click ModelTests "https://github.com/chuksoo/sneaky-swipe-detector/blob/main/src/tests/test_models.py"
    click UtilTests "https://github.com/chuksoo/sneaky-swipe-detector/blob/main/src/tests/utils.py"
    click EnvDoc "https://github.com/chuksoo/sneaky-swipe-detector/blob/main/environment/environment-setup.md"
    click CondaMac "https://github.com/chuksoo/sneaky-swipe-detector/blob/main/environment/fraud-service-mac.yml"
    click CondaWin "https://github.com/chuksoo/sneaky-swipe-detector/blob/main/environment/fraud-service-win.yml"
    click SetupConfig "https://github.com/chuksoo/sneaky-swipe-detector/blob/main/setup.py"
    click ReqList "https://github.com/chuksoo/sneaky-swipe-detector/blob/main/requirements.txt"

    %% Styles
    classDef dataBlue fill:#B3CDE3,stroke:#03396C,color:#03396C;
    classDef processingGreen fill:#C7E9C0,stroke:#006400,color:#006400;
    classDef artifactOrange fill:#FDD0A2,stroke:#D94801,color:#D94801;
    classDef supportGray fill:#E0E0E0,stroke:#666666,color:#333333;
```
