# mwasifanwar/finrisk-predictor architecture

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

- Interactive diagram: https://gitdiagram.com/mwasifanwar/finrisk-predictor
- Repository: https://github.com/mwasifanwar/finrisk-predictor

## Overview

##### Project type and purpose
- This is a backend‐focused, real-time anomaly detection system for financial transactions. It exposes both REST endpoints and WebSocket streams (via FastAPI) and embeds multiple ML stages (graph neural networks, LSTMs, ensembles, time‐series analysis) to flag fraud, money laundering, and market manipulation.

##### File structure
- Top-level files
- main.py / inference.py / train.py – entry points for serving, inference, and training.
- requirements.txt – Python dependencies.
- api/
- fastapi_server.py – initializes API server.
- endpoints.py – REST routes.
- websocket_handler.py – real-time push to clients.
- core/
- transaction_processor.py – orchestrates per-transaction workflow.
- feature_engineer.py (actually under data/) and time_series_analyzer.py – extract features/time patterns.
- graph_neural_network.py, anomaly_detector.py, risk_scorer.py – model-driven scoring logic.
- data/
- data_loader.py – pulls or streams raw data.
- feature_engineer.py – feature creation.
- synthetic_data.py – simulates data for training.
- models/
- gnn_models.py, lstm_models.py, ensemble_models.py – ML model definitions and loading.
- monitoring/
- performance_tracker.py, drift_detector.py, model_updater.py – runtime health, data drift, auto-retraining.
- utils/
- config_loader.py, alert_system.py, metrics_calculator.py, visualization.py – cross-cutting helpers.
- tests/ – unit tests for each component.

##### README
- Confirms goal: “Advanced anomaly detection system using graph neural networks and time series analysis to identify fraudulent transactions… in real-time data streams.”

a. Main components
1. External Data Sources (financial feeds, transaction logs)
2. Data Ingestion Layer (data_loader.py)
3. API Gateway (FastAPI REST & WebSocket)
4. Core Processing Engine
- Transaction Processor
- Feature Engineering & Time-Series Analyzer
- GNN / LSTM / Ensemble Models
- Anomaly Detector & Risk Scorer
5. Model Repository / Storage (serialized model files, metrics DB, time-series DB)
6. Monitoring & Alerting
- Drift Detector, Performance Tracker, Model Updater, Alert System
7. Training Pipeline (train.py + synthetic_data) for offline retraining
b. Relationships & interactions
- Data flow: External Sources → Ingestion → Core Processing → API responses & WebSocket pushes to clients.
- Monitoring taps into metrics emitted by Core Processing and Data Ingestion.
- Model Updater writes new model artifacts back to the Model Repository, which Core Processing loads at runtime.
- Training Pipeline reads historical/synthetic data, writes trained models to the repository.
c. Architectural patterns
- Layered separation: ingestion, API, business logic, storage, monitoring.
- Dependency inversion between core logic and data sources (via config_loader).
- ML pipelines broken into discrete stages (feature extraction → model inference → scoring).
d. Key technologies & frameworks
- Python 3.x, FastAPI, WebSockets
- PyTorch/TensorFlow (implied for GNN/LSTM)
- Time-series libraries (e.g., pandas, numpy)
- Monitoring: custom drift-detector, performance APIs
- Storage: any relational/NoSQL DB for metrics and models

##### Detail
- Config Loader and Alert System as utility blocks that interface across layers.
- Both synchronous (REST) and asynchronous (WebSocket, streaming) interactions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        DS["External Data Sources"]:::external
        DL["Data Ingestion Layer"]:::storage
    end
    DS -->|"raw transactions"| DL
    click DL "https://github.com/mwasifanwar/finrisk-predictor/blob/main/data/data_loader.py"

    %% API Layer
    subgraph "API Layer"
        FS["FastAPI Server"]:::api
        EP["REST Endpoints"]:::api
        WS["WebSocket Handler"]:::api
    end
    click FS "https://github.com/mwasifanwar/finrisk-predictor/blob/main/api/fastapi_server.py"
    click EP "https://github.com/mwasifanwar/finrisk-predictor/blob/main/api/endpoints.py"
    click WS "https://github.com/mwasifanwar/finrisk-predictor/blob/main/api/websocket_handler.py"

    %% Core Processing Layer
    subgraph "Core Processing Engine"
        TP["Transaction Processor"]:::core
        FE["Feature Engineering"]:::core
        TS["Time-Series Analyzer"]:::core
        GNNLogic["Graph Neural Network Logic"]:::core
        LSTM["LSTM Models"]:::core
        Ensemble["Ensemble Models"]:::core
        Anomaly["Anomaly Detector"]:::core
        Risk["Risk Scorer"]:::core
    end
    click TP "https://github.com/mwasifanwar/finrisk-predictor/blob/main/core/transaction_processor.py"
    click FE "https://github.com/mwasifanwar/finrisk-predictor/blob/main/data/feature_engineer.py"
    click TS "https://github.com/mwasifanwar/finrisk-predictor/blob/main/core/time_series_analyzer.py"
    click GNNLogic "https://github.com/mwasifanwar/finrisk-predictor/blob/main/core/graph_neural_network.py"
    click LSTM "https://github.com/mwasifanwar/finrisk-predictor/blob/main/models/lstm_models.py"
    click Ensemble "https://github.com/mwasifanwar/finrisk-predictor/blob/main/models/ensemble_models.py"
    click Anomaly "https://github.com/mwasifanwar/finrisk-predictor/blob/main/core/anomaly_detector.py"
    click Risk "https://github.com/mwasifanwar/finrisk-predictor/blob/main/core/risk_scorer.py"

    %% Storage Layer
    subgraph "Storage"
        ModelRepo["Model Repository (/models/*.pt)"]:::storage
        MetricsDB["Metrics DB"]:::storage
        TSDB["Time-Series DB"]:::storage
    end

    %% Monitoring & Alerting
    subgraph "Monitoring & Alerting"
        Drift["Drift Detector"]:::monitoring
        Perf["Performance Tracker"]:::monitoring
        ModelUpd["Model Updater"]:::monitoring
        AlertSys["Alert System"]:::monitoring
    end
    click Drift "https://github.com/mwasifanwar/finrisk-predictor/blob/main/monitoring/drift_detector.py"
    click Perf "https://github.com/mwasifanwar/finrisk-predictor/blob/main/monitoring/performance_tracker.py"
    click ModelUpd "https://github.com/mwasifanwar/finrisk-predictor/blob/main/monitoring/model_updater.py"
    click AlertSys "https://github.com/mwasifanwar/finrisk-predictor/blob/main/utils/alert_system.py"

    %% Training Pipeline
    subgraph "Training Pipeline"
        Train["train.py"]:::training
        Synth["Synthetic Data Generator"]:::training
    end
    click Train "https://github.com/mwasifanwar/finrisk-predictor/blob/main/train.py"
    click Synth "https://github.com/mwasifanwar/finrisk-predictor/blob/main/data/synthetic_data.py"

    %% Utilities
    subgraph "Utilities"
        Config["Config Loader"]:::utils
        MetricsCalc["Metrics Calculator"]:::utils
        Viz["Visualization Utilities"]:::utils
    end
    click Config "https://github.com/mwasifanwar/finrisk-predictor/blob/main/utils/config_loader.py"

    %% Clients
    Client["Clients"]:::external

    %% Data flow
    DL -->|"transactions"| TP
    TP -->|"raw features"| FE
    FE -->|"feature vectors"| TS
    TS -->|"time features"| GNNLogic
    TS -->|"time features"| LSTM
    GNNLogic -->|"gnn outputs"| Ensemble
    LSTM -->|"lstm outputs"| Ensemble
    Ensemble -->|"combined scores"| Anomaly
    Anomaly -->|"anomaly flags"| Risk
    Risk -->|"risk scores"| EP
    Risk -->|"risk scores"| WS
    EP -->|"REST response"| Client
    WS -->|"WebSocket push"| Client

    %% Model loading and updates
    ModelRepo -->|"loads models"| GNNLogic
    ModelRepo -->|"loads models"| LSTM
    ModelRepo -->|"loads models"| Ensemble
    ModelUpd -.->|"updates models"| ModelRepo

    %% Training flow
    Synth -->|"synthetic data"| Train
    TSDB -->|"historical data"| Train
    Train -->|"trained models"| ModelRepo

    %% Monitoring flows
    DL -->|"ingestion metrics"| Perf
    TP -->|"processing metrics"| Perf
    Perf -.->|"performance alerts"| AlertSys
    Drift -->|"drift alerts"| AlertSys
    AlertSys -->|"alerts"| Client

    %% Utilities interactions
    Config --> DL
    Config --> FS
    Config --> TP

    %% Click events for utilities
    click Config "https://github.com/mwasifanwar/finrisk-predictor/blob/main/utils/config_loader.py"

    %% Styling
    classDef api fill:#add8e6,stroke:#000;
    classDef core fill:#90ee90,stroke:#000;
    classDef storage fill:#ffcc99,stroke:#000;
    classDef monitoring fill:#ff9999,stroke:#000;
    classDef training fill:#cda4de,stroke:#000;
    classDef utils fill:#d3d3d3,stroke:#000;
    classDef external fill:#ffffff,stroke:#000,stroke-dasharray: 2 2;
```
