How avalanche2825/trust-gaurd-ai works
1. Overall shape
- This repo is a three-tier security platform split into:
- a React/TypeScript frontend for analyst/customer/operator workflows,
- a Node.js/Express backend for identity, audit, and policy APIs,
- a Python/Flask ML microservice for risk scoring and fraud detection.
- The design is centered on a dynamic trust score and adaptive enforcement rather than a one-time login check.
2. Frontend boundary
- Frontend/ is a Vite-powered React app written in TypeScript.
- It is a single-page console-style UI with modules for:
- login and landing flows,
- KYC onboarding,
- transaction entry,
- account recovery,
- active session monitoring,
- audit ledger review,
- insider threat monitoring,
- guardian/step-up intervention,
- identity analytics dashboards.
- The UI also includes chart widgets and a toast system, which suggests the frontend is primarily a real-time operational dashboard rather than a content site.
3. Frontend data role
- Frontend/src/utils/mockData.ts and the presence of many self-contained panels imply the UI can run in a demo/simulated mode, but it is structured to consume live risk and event data from the backend.
- types.ts centralizes shared shapes for risk/session/audit entities, which helps keep dashboard modules consistent.
- HackerDelayLayer, GuardianConsole, and similar components indicate the frontend also visualizes security states and step-up delays, not just normal business screens.
4. Backend API boundary
- backend/ is the system’s control plane: it exposes REST endpoints through src/routes/api.js and src/server.js.
- Controllers are separated by domain:
- authentication,
- customers and employees,
- transactions,
- KYC,
- recovery,
- tickets,
- audit logs,
- analytics,
- token/risk operations,
- hacker-delay orchestration,
- ML scoring hooks.
- middlewares/auth.js is the primary access boundary, protecting sensitive routes and enforcing identity checks before actions reach controllers.
5. Backend domain model
- Mongo-style models define the persistent business objects:
- User
- Transaction
- AuditLog
- EmployeeLog
- Guardian
- KYCApplication
- This tells us the backend is not just serving UI data; it is the authoritative store for identity lifecycle, transaction events, administrative actions, and auditability.
6. Backend storage abstraction
- config/db.js, utils/dbBridge.js, and utils/inMemoryDB.js show a storage abstraction layer.
- The repo supports a database-backed mode plus an in-memory fallback, which is useful for local development, hackathon demos, or resilience when the primary database is unavailable.
- In the architecture diagram, this should be shown as a persistence layer behind the Express API, with MongoDB as the intended durable store.
7. ML service boundary
- ml_service/ is a separate Flask application, independently deployable from the Node backend.
- It contains specialized engines for:
- behavioral biometrics,
- device trust scoring,
- insider threat detection,
- KYC graph/ring analysis,
- text-based risk analysis,
- unified aggregation/scoring.
- This service is the main analytics brain of the platform and should be diagrammed as a distinct microservice, not embedded in the backend.
8. Risk-scoring pipeline
- The README describes the ML service as combining multiple detectors into a unified risk score.
- The backend appears to call the ML service for predictions, then uses those results to drive policy decisions such as allow, OTP, hold, or block.
- So the main data flow is: client telemetry or event input → backend API → ML scoring → backend policy decision → UI feedback/audit logging.
9. Real-time and event-driven behavior
- The README references socket-based notifications, and the frontend includes dedicated monitoring and alert surfaces.
- That implies a second flow alongside request/response APIs: backend emits live status or alert events to the UI for session takeover, suspicious recovery, insider misuse, and audit updates.
- In diagram terms, this is the “real-time alert” path, separate from normal CRUD and scoring requests.
10. Operational modules reflected in the codebase
- The repository is organized around six security workflows:
- onboarding/KYC,
- continuous session monitoring,
- transaction risk,
- account recovery protection,
- insider oversight,
- immutable audit review.
- Each workflow has a corresponding frontend surface and backend controller, with ML scoring feeding policy decisions where needed.
- This is important for architecture because it is a security workflow platform with multiple control points, not a generic banking app.
11. Deployment topology
- The repo is split for separate deployment targets:
- Frontend/vercel.json for Vercel hosting,
- backend/vercel.json and render.yaml for backend deployment,
- ml_service/vercel.json and start_ml.bat for the ML service/runtime setup.
- The README also references production URLs on Vercel and Render, confirming the three parts are intended to run as independent services.
12. What to show in an architecture diagram
- The clearest diagram would have four boxes:
- React console UI
- Express API / policy engine
- Flask ML scoring service
- Persistent store
- Then draw two major paths:
- synchronous API calls for authentication, KYC, transactions, recovery, employee actions, and audit retrieval,
- asynchronous or near-real-time alert delivery back to the UI.
- The key architectural idea is that the backend orchestrates policy, the ML service scores risk, and the frontend presents security state continuously.
Main entry points: api.js API Routes · mlController.js ML Hook · controllers Policy Engine · dbBridge.js DB Bridge
Components 21
Frontend
React/Vite analyst and operator console
- Security Console · Main analyst and operator interface for security workflows
Frontend/src/App.tsx - Login · Entry and landing flow for the console
Frontend/src/components/LoginPage.tsx - KYC Onboarding · Customer identity onboarding and review surface
Frontend/src/components/KYCOnboarding.tsx - Transaction Form · Transaction entry and risk-aware submission surface
Frontend/src/components/TransactionForm.tsx - Session Monitor · Active session and live trust monitoring surface
Frontend/src/components/ActiveSessionMonitor.tsx - Recovery Panel · Account recovery and step-up intervention surface
Frontend/src/components/AccountRecoveryPanel.tsx - Audit Viewer · Audit ledger and immutable event review surface
Frontend/src/components/AuditLedgerViewer.tsx - Insider Watch · Employee and insider threat monitoring surface
Frontend/src/components/InsiderOverwatch.tsx - Guardian Console · Step-up and protective intervention console
Frontend/src/components/GuardianConsole.tsx
Backend
Express control plane and API orchestration
- Express API · Backend REST API and policy orchestration layer
backend/src/server.js - API Routes · Central request routing for domain endpoints
backend/src/routes/api.js - Auth Guard · Primary access-control boundary for sensitive actions
backend/src/middlewares/auth.js - Policy Engine · Authentication, recovery, token, and hacker-delay control flow
backend/src/controllers - Domain APIs · Customer, employee, transaction, KYC, audit, analytics, and ticket operations
backend/src/controllers - ML Hook · Backend bridge to external risk scoring and prediction service
backend/src/controllers/mlController.js - DB Bridge · Database abstraction with persistent and in-memory modes
backend/src/utils/dbBridge.js
ML Service
Flask risk scoring and detection service
- Flask Scorer · Independent risk-scoring and fraud-detection microservice
ml_service/app.py - Detectors · Behavioral, device, insider, KYC graph, and text risk models
ml_service/models - Unified Score · Combines detector outputs into a single trust or risk score
ml_service/models/unified_scorer.py
Persistence
Primary domain data and fallback storage
- Data Store · Durable application data for users, transactions, audits, guardians, and KYC
backend/src/models/User.js - Memory Fallback · In-memory persistence for local or degraded runtime mode
backend/src/utils/inMemoryDB.js
Connections 22
- Security Console → API Routes: API calls · Console actions flow to backend endpoints
- Login → Auth Guard: sign-in · Authentication requests enter the access boundary
- KYC Onboarding → API Routes: KYC ops · Onboarding and verification requests go to the API
- Transaction Form → API Routes: transaction ops · Transaction submission and review requests go to the API
- Session Monitor → API Routes: session data · Monitoring screens retrieve current trust and session state
- Recovery Panel → API Routes: recovery ops · Account recovery and step-up actions go through the API
- Audit Viewer → API Routes: audit fetch · Ledger review requests are served by backend routes
- Insider Watch → API Routes: oversight · Insider monitoring views query employee and alert data
- Guardian Console → API Routes: interventions · Guardian actions trigger backend control flows
- API Routes → Auth Guard: protect · Sensitive endpoints are gated before controller execution
- API Routes → Policy Engine: orchestrate · Core security workflows are coordinated by policy controllers
- API Routes → Domain APIs: domain ops · Business and audit endpoints are dispatched to domain controllers
- API Routes → ML Hook: risk check · Requests needing prediction are forwarded to the scoring bridge
- Policy Engine → ML Hook: score request · Policy decisions can invoke ML scoring for trust evaluation
- ML Hook → Flask Scorer: predict · Backend sends features to the external Flask service
- Flask Scorer → Detectors: run detectors · The scoring service executes specialized detection engines
- Detectors → Unified Score: aggregate · Detector outputs are fused into a unified score
- Unified Score → ML Hook: result · Unified risk output is returned to the backend
- Policy Engine → Security Console: alerts · Policy decisions and step-up events can be surfaced back to the console
- Domain APIs → DB Bridge: persist · Controllers read and write through the storage abstraction
- DB Bridge → Data Store: primary · Default durable persistence target
- DB Bridge → Memory Fallback: fallback · In-memory mode when durable storage is unavailable