# aryan-r-patel/gfdn architecture

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

- Interactive diagram: https://gitdiagram.com/aryan-r-patel/gfdn
- Repository: https://github.com/aryan-r-patel/gfdn

## Overview

##### Project Type and Purpose
- This is a full-stack, real-time fraud detection and prevention platform (Global Fraud Defense Network).
- Backend: Node.js/Express service exposing HTTP endpoints, WebSocket (Socket.io) for live updates, AI-powered workflow engine, and data simulator.
- Frontend: React/Vite single-page application with real-time dashboards, 3D globe mapping, workflow editor, and AI voice chatbot interface.

##### Main Components
a. Frontend Application
- Modules:
- UI Components (DashboardMetrics, GlobeView, TransactionFeed, WorkflowEditor, AIAssistant, VoiceRecorder, AudioVisualizer)
- State Management (useGfdnStore)
- Socket Layer (useSocket hook)
- Firebase auth/integration (frontend/src/lib/firebase.js)
- MVP sub-layer (AppPresenter, AppView)
- Runtime: served by Vite dev server or static assets in /dist.

b. Backend Service
- HTTP/WebSocket Server (Express + Socket.io in src/server.js)
- Workflow Engine (src/workflow/executor.js + node definitions in nodes/)
- Chatbot Services (service.js, voiceService.js under src/chatbot)
- Data Layer (transaction simulator: fetchTransactions, watchTransactions, seedUserData, transactionGenerator)
- Suggestions Engine (src/suggestions/engine.js)
- Metrics Collector (src/metrics.js)
- Environment & Config (.env, setup-env.sh)
- Tests suite (backend/tests)

c. External Services
- Google Gemini AI (Gemini API calls from chatbot/service.js)
- ElevenLabs Voice API (voiceService.js)
- Firebase (authentication, optional data store)

d. Persistence & Simulation
- In-memory or external data store (could be Firebase real-time DB or placeholder in data scripts)
- Transaction generator simulating incoming events

##### Component Interactions and Data Flow
- User in Browser → React SPA →
- requests static assets (HTTP)
- opens WebSocket to backend for real-time transaction events and AI chat messages
- invokes REST API endpoints for workflow operations or suggestions
- interacts with UI to edit workflows (React Flow), which calls WebSocket or REST to save/update
- triggers AI assistant via Socket.io or REST → backend calls Gemini API → returns text → optionally passed to ElevenLabs for TTS → audio stream back to client
- Backend Data Simulator → pushes fake transactions over WebSocket → frontend visualizations update
- Workflow Engine processes events → may call anomalyDetection, geminiCheck, geoCheck, velocityCheck nodes → emits fraud alerts

##### Architectural Patterns & Design Principles
- Frontend: component-based UI, unidirectional data flow (hooks + store), MVP for App container
- Backend: modular service layers (chatbot, workflow, data, suggestions), pluggable workflow nodes, test-driven design
- Real-time communications: WebSocket pub/sub via Socket.io
- API Layer: REST endpoints and WebSocket channels
- Extensibility: separate node definitions under workflow/nodes for new fraud rules

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User & Browser
    User["User Browser"]:::external

    %% Frontend Application
    subgraph "Frontend SPA" 
        direction LR
        App["App (App.jsx)"]:::frontend
        Main["Main (main.jsx)"]:::frontend

        subgraph "UI Components"
            direction TB
            DM["DashboardMetrics"]:::frontend
            GV["GlobeView"]:::frontend
            TF["TransactionFeed"]:::frontend
            WE["WorkflowEditor"]:::frontend
            AA["AIAssistant"]:::frontend
            VR["VoiceRecorder"]:::frontend
            AV["AudioVisualizer"]:::frontend
        end

        SMS["useGfdnStore"]:::frontend
        SSH["useSocket"]:::frontend
        FB["Firebase Integration"]:::frontend

        subgraph "MVP Layer"
            AP["AppPresenter"]:::frontend
            AVw["AppView"]:::frontend
        end
    end

    %% Backend Microservices
    subgraph "Backend Service" 
        direction TB
        Server["HTTP/WebSocket Server"]:::backend
        subgraph "Workflow Engine"
            direction TB
            Executor["Executor"]:::backend
            subgraph "Nodes"
                ADet["anomalyDetection"]:::backend
                GCh["geoCheck"]:::backend
                VCh["velocityCheck"]:::backend
                GmCh["geminiCheck"]:::backend
                DNd["decisionNode"]:::backend
                INd["inputNode"]:::backend
            end
        end
        subgraph "Chatbot Services"
            CSvc["Chatbot Service"]:::backend
            VSvc["Voice Service"]:::backend
        end
        subgraph "Data Simulator"
            direction TB
            FT["fetchTransactions"]:::backend
            WT["watchTransactions"]:::backend
            SU["seedUserData"]:::backend
            TG["transactionGenerator"]:::backend
        end
        Suggest["Suggestions Engine"]:::backend
        Metrics["Metrics Collector"]:::backend
        Config["Env & Config"]:::backend
    end

    %% External Services & Data Stores
    subgraph "External Services & DB"
        direction TB
        Gemini["Google Gemini AI"]:::external
        Eleven["ElevenLabs Voice API"]:::external
        FirebaseDB["Firebase Realtime DB"]:::datastore
    end

    %% Connections
    User -->|"HTTP GET static"| App
    User -->|"WS connect"| SSH
    App -->|uses| Main
    Main -->|renders| DM & GV & TF & WE & AA & VR & AV
    Main -->|uses| SMS
    Main -->|uses| SSH
    Main -->|auth| FB

    AA -->|"start chat"| SSH
    SSH -->|"WS msg"| Server
    TF -->|"subscribe events"| SSH

    Server -->|"call REST"| Suggest
    Server -->|"emit WS"| TF & DM & GV
    Server -->|"invoke workflow"| Executor
    Executor -->|uses| ADet & GCh & VCh & GmCh & DNd & INd
    CSvc -->|"Gemini API"| Gemini
    VSvc -->|"TTS API"| Eleven

    Server -->|reads| FT & WT & SU & TG
    Server -->|collect| Metrics

    %% Dev & Config
    Config -->|loads| Server

    %% External DB
    Server -->|optionally stores| FirebaseDB

    %% Click Events - Frontend
    click DM "https://github.com/aryan-r-patel/gfdn/blob/main/frontend/src/components/DashboardMetrics.jsx"
    click GV "https://github.com/aryan-r-patel/gfdn/blob/main/frontend/src/components/GlobeView.jsx"
    click TF "https://github.com/aryan-r-patel/gfdn/blob/main/frontend/src/components/TransactionFeed.jsx"
    click WE "https://github.com/aryan-r-patel/gfdn/blob/main/frontend/src/components/WorkflowEditor.jsx"
    click AA "https://github.com/aryan-r-patel/gfdn/blob/main/frontend/src/components/AIAssistant.jsx"
    click VR "https://github.com/aryan-r-patel/gfdn/blob/main/frontend/src/components/VoiceRecorder.jsx"
    click AV "https://github.com/aryan-r-patel/gfdn/blob/main/frontend/src/components/AudioVisualizer.jsx"
    click SMS "https://github.com/aryan-r-patel/gfdn/blob/main/frontend/src/store/useGfdnStore.js"
    click SSH "https://github.com/aryan-r-patel/gfdn/blob/main/frontend/src/hooks/useSocket.js"
    click FB "https://github.com/aryan-r-patel/gfdn/blob/main/frontend/src/lib/firebase.js"
    click AP "https://github.com/aryan-r-patel/gfdn/blob/main/frontend/src/mvp/presenters/AppPresenter.jsx"
    click AVw "https://github.com/aryan-r-patel/gfdn/blob/main/frontend/src/mvp/views/AppView.jsx"
    click App "https://github.com/aryan-r-patel/gfdn/blob/main/frontend/src/App.jsx"
    click Main "https://github.com/aryan-r-patel/gfdn/blob/main/frontend/src/main.jsx"
    click DM "https://github.com/aryan-r-patel/gfdn/tree/main/frontend/src/components"
    click GV "https://github.com/aryan-r-patel/gfdn/tree/main/frontend/src/components"
    click TF "https://github.com/aryan-r-patel/gfdn/tree/main/frontend/src/components"
    click WE "https://github.com/aryan-r-patel/gfdn/tree/main/frontend/src/components"
    click AA "https://github.com/aryan-r-patel/gfdn/tree/main/frontend/src/components"
    click VR "https://github.com/aryan-r-patel/gfdn/tree/main/frontend/src/components"
    click AV "https://github.com/aryan-r-patel/gfdn/tree/main/frontend/src/components"

    %% Click Events - Backend
    click Server "https://github.com/aryan-r-patel/gfdn/blob/main/backend/src/server.js"
    click Executor "https://github.com/aryan-r-patel/gfdn/blob/main/backend/src/workflow/executor.js"
    click ADet "https://github.com/aryan-r-patel/gfdn/blob/main/backend/src/workflow/nodes/anomalyDetection.js"
    click GCh "https://github.com/aryan-r-patel/gfdn/blob/main/backend/src/workflow/nodes/geoCheck.js"
    click VCh "https://github.com/aryan-r-patel/gfdn/blob/main/backend/src/workflow/nodes/velocityCheck.js"
    click GmCh "https://github.com/aryan-r-patel/gfdn/blob/main/backend/src/workflow/nodes/geminiCheck.js"
    click DNd "https://github.com/aryan-r-patel/gfdn/blob/main/backend/src/workflow/nodes/decisionNode.js"
    click INd "https://github.com/aryan-r-patel/gfdn/blob/main/backend/src/workflow/nodes/inputNode.js"
    click CSvc "https://github.com/aryan-r-patel/gfdn/blob/main/backend/src/chatbot/service.js"
    click VSvc "https://github.com/aryan-r-patel/gfdn/blob/main/backend/src/chatbot/voiceService.js"
    click FT "https://github.com/aryan-r-patel/gfdn/blob/main/backend/src/data/fetchTransactions.js"
    click WT "https://github.com/aryan-r-patel/gfdn/blob/main/backend/src/data/watchTransactions.js"
    click SU "https://github.com/aryan-r-patel/gfdn/blob/main/backend/src/data/seedUserData.js"
    click TG "https://github.com/aryan-r-patel/gfdn/blob/main/backend/src/data/transactionGenerator.js"
    click Suggest "https://github.com/aryan-r-patel/gfdn/blob/main/backend/src/suggestions/engine.js"
    click Metrics "https://github.com/aryan-r-patel/gfdn/blob/main/backend/src/metrics.js"
    click Config "https://github.com/aryan-r-patel/gfdn/blob/main/backend/setup-env.sh"
    click Config "https://github.com/aryan-r-patel/gfdn/blob/main/backend/.env"
    click Config "https://github.com/aryan-r-patel/gfdn/blob/main/backend/.env.example"
    classDef frontend fill:#E3F2FD,stroke:#90CAF9,stroke-width:1px
    classDef backend fill:#E8F5E9,stroke:#66BB6A,stroke-width:1px
    classDef external fill:#FFF3E0,stroke:#FFA726,stroke-width:1px
    classDef datastore fill:#E0F7FA,stroke:#00ACC1,stroke-width:1px
```
