How aryan-r-patel/hack-the-valley-x works
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.