# aryan-r-patel/hack-the-valley-x architecture

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

- Interactive diagram: https://gitdiagram.com/aryan-r-patel/hack-the-valley-x
- Repository: https://github.com/aryan-r-patel/hack-the-valley-x

## Overview

##### Project Type and Purpose
- This is a full-stack, real-time fraud detection and prevention platform with an AI-powered chatbot (voice & text) and an interactive dashboard.
- Frontend: React + Vite application for visualization (3D globe, transaction feed, metrics, workflow editor) and the AI Assistant UI.
- Backend: Node.js + Express + Socket.io services for transaction ingestion, fraud-detection workflow engine, AI chatbot integration, metrics, and real-time communication.
- External services: Google Gemini API (LLM), ElevenLabs Voice API (TTS), Firebase (authentication / storage).

##### File Structure Highlights
- Top-level “backend” and “frontend” directories with their own package.json, configuration, and build scripts.
- Backend/src sub-folders:
- chatbot (service.js, voiceService.js)
- data (generators, fetchers, simulators)
- workflow (executor.js + node implementations)
- suggestions (engine.js)
- metrics.js, server.js (Express + Socket.io setup)
- Frontend/src sub-folders:
- components (UI building blocks)
- hooks (useSocket)
- lib (firebase integration)
- pages (Dashboard, WorkflowPage, Admin, etc.)
- mvp (example Presenter/View)
- store (state management)
- Vite config + build output under dist.

##### Key Architectural Patterns
- Full-stack separation: frontend client ↔ backend API + WebSocket.
- Modular backend micro-services: ingestion, workflow engine, chatbot, suggestions, metrics.
- Event-driven / real-time data flow via WebSocket (Socket.io).
- External integrations for AI (LLM & TTS) and persistent storage/auth (Firebase).

##### Main Components & Their Relationships
a. Frontend Application (React/Vite)
- UI Modules: DashboardMetrics, GlobeView (react-globe), TransactionFeed, WorkflowEditor (React Flow), AI Assistant (chat + voice)
- Hooks: useSocket for WebSocket communication
- Firebase client for user auth & config
- Connects to Backend via:
- HTTP REST (Express endpoints if any)
- WebSocket (real-time transactions, metrics, chatbot responses)
b. Backend Services (Node.js/Express + Socket.io)
- API / WebSocket Server (server.js)
- Data Ingestion Layer (fetchTransactions, seedUserData, transactionGenerator, watchTransactions)
- Workflow Engine (executor + nodes for anomalyDetection, geoCheck, velocityCheck, geminiCheck, decisionNode, inputNode)
- Chatbot Service (service.js) & VoiceService (ElevenLabs TTS)
- Suggestions Engine (engine.js)
- Metrics Collector (metrics.js)
- Firebase integration (firebase.js) for persistent storage/auth
- Tests for each workflow node
c. External Services
- Google Gemini API — LLM calls from geminiCheck node & chatbot service
- ElevenLabs Voice API — text-to-speech in voiceService
- Firebase — user data store, transaction events, authentication

- Use clear, descriptive labels on each component.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        DM["DashboardMetrics"]:::frontend
        GV["GlobeView"]:::frontend
        TF["TransactionFeed"]:::frontend
        WE["WorkflowEditor"]:::frontend
        AA["AI Assistant UI"]:::frontend
        AV["AudioVisualizer"]:::frontend
        VR["VoiceRecorder"]:::frontend
        VD["VoiceDemo"]:::frontend
        CN["Custom Flow Nodes"]:::frontend
        US["useSocket Hook"]:::frontend
        GS["Global Store"]:::frontend
        FF["Firebase Client"]:::frontend
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        WS["Web Server (Express + Socket.io)"]:::backend
        IS["Data Ingestion Service"]:::backend
        subgraph "Workflow Engine"
            direction TB
            WEc["Executor"]:::backend
            AD["Anomaly Detection Node"]:::backend
            GC["GeoCheck Node"]:::backend
            VC["VelocityCheck Node"]:::backend
            GM["GeminiCheck Node"]:::backend
            DN["Decision Node"]:::backend
            IN["Input Node"]:::backend
        end
        CS["Chatbot Service"]:::backend
        VS["Voice Service"]:::backend
        SE["Suggestions Engine"]:::backend
        MS["Metrics Service"]:::backend
        FBb["Firebase Integration"]:::backend
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        FDb["Firebase Database"]:::data
    end

    %% External Layer
    subgraph "External Layer"
        direction TB
        GEM["Google Gemini API"]:::external
        ELE["ElevenLabs Voice API"]:::external
    end

    %% Connections
    DM -->|HTTP/WS| WS
    GV -->|HTTP/WS| WS
    TF -->|WS transactions stream| WS
    WE -->|HTTP| WS
    AA -->|WS chat stream| WS
    AV -->|audio data| AA
    VR -->|voice input| AA
    VD -->|TTS preview| VS
    CN -->|custom nodes UI| WE
    US -->|WS connect| WS
    GS -->|state updates| WS
    FF -->|auth & config| WS

    WS -->|invoke| IS
    WS -->|invoke| WEc
    WS -->|invoke| CS
    WS -->|invoke| SE
    WS -->|invoke| MS
    WS -->|read/write| FBb

    IS -->|store/read| FDb
    FBb -->|auth & data| FDb

    WEc -->|process| AD
    WEc -->|process| GC
    WEc -->|process| VC
    WEc -->|process| GM
    WEc -->|process| DN
    WEc -->|process| IN

    GM -->|HTTP LLM call| GEM
    CS -->|HTTP chat request| GEM
    VS -->|HTTP TTS request| ELE

    MS -->|metrics stream| WS
    SE -->|suggestions| WS

    %% Click Events
    click DM "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/frontend/src/components/DashboardMetrics.jsx"
    click GV "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/frontend/src/components/GlobeView.jsx"
    click TF "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/frontend/src/components/TransactionFeed.jsx"
    click WE "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/frontend/src/components/WorkflowEditor.jsx"
    click AA "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/frontend/src/components/AIAssistant.jsx"
    click AV "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/frontend/src/components/AudioVisualizer.jsx"
    click VR "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/frontend/src/components/VoiceRecorder.jsx"
    click VD "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/frontend/src/components/VoiceDemo.jsx"
    click CN "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/frontend/src/components/CustomNodes.jsx"
    click US "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/frontend/src/hooks/useSocket.js"
    click GS "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/frontend/src/store/useGfdnStore.js"
    click FF "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/frontend/src/lib/firebase.js"
    click WS "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/backend/src/server.js"
    click FBb "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/backend/firebase.js"
    click IS "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/backend/src/data/fetchTransactions.js"
    click IS "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/backend/src/data/transactionGenerator.js"
    click IS "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/backend/src/data/seedUserData.js"
    click IS "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/backend/src/data/watchTransactions.js"
    click WEc "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/backend/src/workflow/executor.js"
    click AD "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/backend/src/workflow/nodes/anomalyDetection.js"
    click GC "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/backend/src/workflow/nodes/geoCheck.js"
    click VC "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/backend/src/workflow/nodes/velocityCheck.js"
    click GM "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/backend/src/workflow/nodes/geminiCheck.js"
    click DN "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/backend/src/workflow/nodes/decisionNode.js"
    click IN "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/backend/src/workflow/nodes/inputNode.js"
    click CS "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/backend/src/chatbot/service.js"
    click VS "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/backend/src/chatbot/voiceService.js"
    click SE "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/backend/src/suggestions/engine.js"
    click MS "https://github.com/aryan-r-patel/hack-the-valley-x/blob/main/backend/src/metrics.js"

    %% Styles
    classDef frontend fill:#E3F2FD,stroke:#2196F3,color:#0D47A1
    classDef backend fill:#FFF3E0,stroke:#FB8C00,color:#E65100
    classDef data fill:#E8F5E9,stroke:#43A047,color:#1B5E20
    classDef external fill:#F3E5F5,stroke:#8E24AA,color:#4A148C
```
