# vijayaramanujam/hack-with-adithya architecture

> Architecture diagram of the GitHub repository vijayaramanujam/hack-with-adithya, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vijayaramanujam/hack-with-adithya
- Repository: https://github.com/vijayaramanujam/hack-with-adithya

## Overview

This repository detects suspected money-mule accounts, combines ML and rule signals into account risk scores, and identifies connected fraud rings. The principal workflow is CSV loading, validation, preprocessing, graph and behavioral feature generation, classification and rule detection, risk fusion, then ring analysis. The batch CLI orchestrates training and inference; a FastAPI layer serves predictions and saved analysis outputs. The graph preserves README-described stages and API capabilities. Some relationships rely on the shown pipeline references or README rather than complete source excerpts; unshown implementation details are not inferred.

Main entry points: [`train.py`](https://github.com/vijayaramanujam/hack-with-adithya/blob/main/train.py) (Training workflow), [`predict.py`](https://github.com/vijayaramanujam/hack-with-adithya/blob/main/predict.py) (Scoring workflow), [`src/preprocessing.py`](https://github.com/vijayaramanujam/hack-with-adithya/blob/main/src/preprocessing.py) (Preprocessing), [`src/inference.py`](https://github.com/vijayaramanujam/hack-with-adithya/blob/main/src/inference.py) (Model inference)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_loader["Dataset loader<br/>[data_loader.py]"]
  node_validation["Data validation<br/>[data_validation.py]"]
  node_preprocessing["Preprocessing<br/>[preprocessing.py]"]
end

subgraph group_analysis["Detection analysis"]
  node_graph["Transaction graph<br/>[graph_builder.py]"]
  node_features["Account features"]
  node_rules["Rule detectors<br/>[rule_detectors.py]"]
  node_risk["Risk fusion<br/>[risk_scoring.py]"]
  node_rings["Fraud ring detection<br/>[ring_detection.py]"]
end

subgraph group_learning["Model training"]
  node_model["Mule classifier<br/>[train_model.py]"]
  node_evaluation["Model evaluation"]
  node_cli_train["Training workflow<br/>[train.py]"]
end

subgraph group_serving["Inference and API"]
  node_inference["Model inference<br/>[inference.py]"]
  node_cli_predict["Scoring workflow<br/>[predict.py]"]
  node_api["FastAPI service<br/>[main.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
end

subgraph group_config["Configuration and artifacts"]
  node_config["Pipeline configuration<br/>[config.py]"]
  node_artifacts["Model artifacts"]
end

node_operator(("Analyst / operator"))
node_csv["Financial CSV data"]
node_api_client(("API client"))

node_csv -->|"loads"| node_loader
node_loader -->|"validates"| node_validation
node_validation -->|"cleans"| node_preprocessing
node_preprocessing -->|"builds topology"| node_graph
node_preprocessing -->|"derives features"| node_features
node_graph -->|"adds graph metrics"| node_features
node_preprocessing -->|"checks transactions"| node_rules
node_features -->|"trains on features"| node_model
node_rules -->|"adds rule signals"| node_model
node_model -->|"evaluates"| node_evaluation
node_features -->|"scores features"| node_inference
node_rules -->|"supplies rule scores"| node_risk
node_inference -->|"supplies probabilities"| node_risk
node_preprocessing -->|"supplies transactions"| node_risk
node_risk -->|"ranks suspicious accounts"| node_rings
node_cli_train -->|"loads data"| node_loader
node_cli_train -->|"validates data"| node_validation
node_cli_train -->|"preprocesses data"| node_preprocessing
node_cli_train -->|"builds graph"| node_graph
node_cli_train -->|"builds features"| node_features
node_cli_train -->|"runs detectors"| node_rules
node_cli_train -->|"trains model"| node_model
node_cli_train -->|"evaluates model"| node_evaluation
node_cli_train -->|"computes risk"| node_risk
node_cli_train -->|"detects rings"| node_rings
node_cli_train -->|"uses inference"| node_inference
node_cli_predict -->|"loads data"| node_loader
node_cli_predict -->|"preprocesses data"| node_preprocessing
node_cli_predict -->|"builds graph"| node_graph
node_cli_predict -->|"builds features"| node_features
node_cli_predict -->|"runs detectors"| node_rules
node_cli_predict -->|"predicts probabilities"| node_inference
node_cli_predict -->|"computes risk"| node_risk
node_cli_predict -->|"detects rings"| node_rings
node_api_client -->|"requests endpoints"| node_api
node_api -->|"uses response models"| node_schemas
node_api -->|"predicts"| node_inference
node_config -->|"sets data paths"| node_loader
node_config -->|"sets output paths"| node_preprocessing
node_config -->|"locates artifacts"| node_inference
node_inference -->|"loads model metadata"| node_artifacts

click node_loader "https://github.com/vijayaramanujam/hack-with-adithya/blob/main/src/data_loader.py"
click node_validation "https://github.com/vijayaramanujam/hack-with-adithya/blob/main/src/data_validation.py"
click node_preprocessing "https://github.com/vijayaramanujam/hack-with-adithya/blob/main/src/preprocessing.py"
click node_graph "https://github.com/vijayaramanujam/hack-with-adithya/blob/main/src/graph_builder.py"
click node_features "https://github.com/vijayaramanujam/hack-with-adithya/blob/main/src/feature_engineering.py"
click node_rules "https://github.com/vijayaramanujam/hack-with-adithya/blob/main/src/rule_detectors.py"
click node_model "https://github.com/vijayaramanujam/hack-with-adithya/blob/main/src/train_model.py"
click node_evaluation "https://github.com/vijayaramanujam/hack-with-adithya/blob/main/src/model_evaluation.py"
click node_inference "https://github.com/vijayaramanujam/hack-with-adithya/blob/main/src/inference.py"
click node_risk "https://github.com/vijayaramanujam/hack-with-adithya/blob/main/src/risk_scoring.py"
click node_rings "https://github.com/vijayaramanujam/hack-with-adithya/blob/main/src/ring_detection.py"
click node_cli_train "https://github.com/vijayaramanujam/hack-with-adithya/blob/main/train.py"
click node_cli_predict "https://github.com/vijayaramanujam/hack-with-adithya/blob/main/predict.py"
click node_api "https://github.com/vijayaramanujam/hack-with-adithya/blob/main/api/main.py"
click node_schemas "https://github.com/vijayaramanujam/hack-with-adithya/blob/main/api/schemas.py"
click node_config "https://github.com/vijayaramanujam/hack-with-adithya/blob/main/src/config.py"
click node_artifacts "https://github.com/vijayaramanujam/hack-with-adithya/tree/main/models"

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_loader,node_validation,node_preprocessing,node_api_client toneBlue
class node_graph,node_features,node_rules,node_risk,node_rings toneAmber
class node_model,node_evaluation,node_cli_train toneMint
class node_inference,node_cli_predict,node_api,node_schemas toneRose
class node_config,node_artifacts,node_operator,node_csv toneIndigo
```

## Components

### Data preparation

- [Dataset loader](https://github.com/vijayaramanujam/hack-with-adithya/blob/main/src/data_loader.py): `src/data_loader.py`
- [Data validation](https://github.com/vijayaramanujam/hack-with-adithya/blob/main/src/data_validation.py): `src/data_validation.py`
- [Preprocessing](https://github.com/vijayaramanujam/hack-with-adithya/blob/main/src/preprocessing.py): `src/preprocessing.py`

### Detection analysis

- [Transaction graph](https://github.com/vijayaramanujam/hack-with-adithya/blob/main/src/graph_builder.py): `src/graph_builder.py`
- [Account features](https://github.com/vijayaramanujam/hack-with-adithya/blob/main/src/feature_engineering.py): `src/feature_engineering.py`
- [Rule detectors](https://github.com/vijayaramanujam/hack-with-adithya/blob/main/src/rule_detectors.py): `src/rule_detectors.py`
- [Risk fusion](https://github.com/vijayaramanujam/hack-with-adithya/blob/main/src/risk_scoring.py): `src/risk_scoring.py`
- [Fraud ring detection](https://github.com/vijayaramanujam/hack-with-adithya/blob/main/src/ring_detection.py): `src/ring_detection.py`

### Model training

- [Mule classifier](https://github.com/vijayaramanujam/hack-with-adithya/blob/main/src/train_model.py): `src/train_model.py`
- [Model evaluation](https://github.com/vijayaramanujam/hack-with-adithya/blob/main/src/model_evaluation.py): `src/model_evaluation.py`
- [Training workflow](https://github.com/vijayaramanujam/hack-with-adithya/blob/main/train.py): `train.py`

### Inference and API

- [Model inference](https://github.com/vijayaramanujam/hack-with-adithya/blob/main/src/inference.py): `src/inference.py`
- [Scoring workflow](https://github.com/vijayaramanujam/hack-with-adithya/blob/main/predict.py): `predict.py`
- [FastAPI service](https://github.com/vijayaramanujam/hack-with-adithya/blob/main/api/main.py): `api/main.py`
- [API schemas](https://github.com/vijayaramanujam/hack-with-adithya/blob/main/api/schemas.py): `api/schemas.py`

### Configuration and artifacts

- [Pipeline configuration](https://github.com/vijayaramanujam/hack-with-adithya/blob/main/src/config.py): `src/config.py`
- [Model artifacts](https://github.com/vijayaramanujam/hack-with-adithya/tree/main/models): `models`

### Other components

- **Analyst / operator**
- **Financial CSV data**
- **API client**

## Connections

- Financial CSV data → Dataset loader: loads (evidence: `README.md`)
- Dataset loader → Data validation: validates (evidence: `train.py`)
- Data validation → Preprocessing: cleans (evidence: `train.py`)
- Preprocessing → Transaction graph: builds topology (evidence: `README.md`)
- Preprocessing → Account features: derives features (evidence: `README.md`)
- Transaction graph → Account features: adds graph metrics (evidence: `README.md`)
- Preprocessing → Rule detectors: checks transactions (evidence: `predict.py`)
- Account features → Mule classifier: trains on features (evidence: `train.py`)
- Rule detectors → Mule classifier: adds rule signals (evidence: `train.py`)
- Mule classifier → Model evaluation: evaluates (evidence: `train.py`)
- Account features → Model inference: scores features (evidence: `predict.py`)
- Rule detectors → Risk fusion: supplies rule scores (evidence: `predict.py`)
- Model inference → Risk fusion: supplies probabilities (evidence: `predict.py`)
- Preprocessing → Risk fusion: supplies transactions (evidence: `predict.py`)
- Risk fusion → Fraud ring detection: ranks suspicious accounts (evidence: `predict.py`)
- Training workflow → Dataset loader: loads data (evidence: `train.py`)
- Training workflow → Data validation: validates data (evidence: `train.py`)
- Training workflow → Preprocessing: preprocesses data (evidence: `train.py`)
- Training workflow → Transaction graph: builds graph (evidence: `train.py`)
- Training workflow → Account features: builds features (evidence: `train.py`)
- Training workflow → Rule detectors: runs detectors (evidence: `train.py`)
- Training workflow → Mule classifier: trains model (evidence: `train.py`)
- Training workflow → Model evaluation: evaluates model (evidence: `train.py`)
- Training workflow → Risk fusion: computes risk (evidence: `train.py`)
- Training workflow → Fraud ring detection: detects rings (evidence: `train.py`)
- Training workflow → Model inference: uses inference (evidence: `train.py`)
- Scoring workflow → Dataset loader: loads data (evidence: `predict.py`)
- Scoring workflow → Preprocessing: preprocesses data (evidence: `predict.py`)
- Scoring workflow → Transaction graph: builds graph (evidence: `predict.py`)
- Scoring workflow → Account features: builds features (evidence: `predict.py`)
- Scoring workflow → Rule detectors: runs detectors (evidence: `predict.py`)
- Scoring workflow → Model inference: predicts probabilities (evidence: `predict.py`)
- Scoring workflow → Risk fusion: computes risk (evidence: `predict.py`)
- Scoring workflow → Fraud ring detection: detects rings (evidence: `predict.py`)
- API client → FastAPI service: requests endpoints (evidence: `api/main.py`)
- FastAPI service → API schemas: uses response models (evidence: `api/main.py`)
- FastAPI service → Model inference: predicts (evidence: `api/main.py`)
- Pipeline configuration → Dataset loader: sets data paths (evidence: `src/data_loader.py`)
- Pipeline configuration → Preprocessing: sets output paths (evidence: `src/preprocessing.py`)
- Pipeline configuration → Model inference: locates artifacts (evidence: `src/inference.py`)
- Model inference → Model artifacts: loads model metadata (evidence: `src/inference.py`)
