# avalanche2825/trust-gaurd-ai architecture

> Architecture diagram of the GitHub repository avalanche2825/trust-gaurd-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/avalanche2825/trust-gaurd-ai
- Repository: https://github.com/avalanche2825/trust-gaurd-ai

## Overview

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: [`backend/src/routes/api.js`](https://github.com/avalanche2825/trust-gaurd-ai/blob/main/backend/src/routes/api.js) (API Routes), [`backend/src/controllers/mlController.js`](https://github.com/avalanche2825/trust-gaurd-ai/blob/main/backend/src/controllers/mlController.js) (ML Hook), [`backend/src/controllers`](https://github.com/avalanche2825/trust-gaurd-ai/tree/main/backend/src/controllers) (Policy Engine), [`backend/src/utils/dbBridge.js`](https://github.com/avalanche2825/trust-gaurd-ai/blob/main/backend/src/utils/dbBridge.js) (DB Bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_ui["Security Console<br/>React SPA<br/>[App.tsx]"]
  node_login["Login<br/>auth screen<br/>[LoginPage.tsx]"]
  node_kyc_ui["KYC Onboarding<br/>workflow panel<br/>[KYCOnboarding.tsx]"]
  node_txn_ui["Transaction Form<br/>workflow panel"]
  node_monitor_ui["Session Monitor<br/>monitoring panel"]
  node_recovery_ui["Recovery Panel<br/>workflow panel"]
  node_audit_ui["Audit Viewer<br/>review panel"]
  node_insider_ui["Insider Watch<br/>monitoring panel"]
  node_guardian_ui["Guardian Console<br/>control panel"]
end

subgraph group_backend["Backend"]
  node_api["Express API<br/>Node service<br/>[server.js]"]
  node_routes["API Routes<br/>routing<br/>[api.js]"]
  node_auth_mw{{"Auth Guard<br/>middleware<br/>[auth.js]"}}
  node_policy["Policy Engine<br/>controllers"]
  node_domain["Domain APIs<br/>controllers"]
  node_score_hook["ML Hook<br/>controller<br/>[mlController.js]"]
  node_db_bridge["DB Bridge<br/>storage adapter<br/>[dbBridge.js]"]
end

subgraph group_ml["ML Service"]
  node_ml_app["Flask Scorer<br/>Python service<br/>[app.py]"]
  node_engines["Detectors<br/>risk engines"]
  node_scorer{{"Unified Score<br/>aggregator<br/>[unified_scorer.py]"}}
end

subgraph group_data["Persistence"]
  node_store[("Data Store<br/>persistent store<br/>[User.js]")]
  node_fallback[("Memory Fallback<br/>volatile store<br/>[inMemoryDB.js]")]
end

node_ui -->|"API calls"| node_routes
node_login -->|"sign-in"| node_auth_mw
node_kyc_ui -->|"KYC ops"| node_routes
node_txn_ui -->|"transaction ops"| node_routes
node_monitor_ui -->|"session data"| node_routes
node_recovery_ui -->|"recovery ops"| node_routes
node_audit_ui -->|"audit fetch"| node_routes
node_insider_ui -->|"oversight"| node_routes
node_guardian_ui -->|"interventions"| node_routes
node_routes -->|"protect"| node_auth_mw
node_routes -->|"orchestrate"| node_policy
node_routes -->|"domain ops"| node_domain
node_routes -->|"risk check"| node_score_hook
node_policy -->|"score request"| node_score_hook
node_score_hook -->|"predict"| node_ml_app
node_ml_app -->|"run detectors"| node_engines
node_engines -->|"aggregate"| node_scorer
node_scorer -->|"result"| node_score_hook
node_policy -->|"alerts"| node_ui
node_domain -->|"persist"| node_db_bridge
node_db_bridge -->|"primary"| node_store
node_db_bridge -->|"fallback"| node_fallback

click node_ui "https://github.com/avalanche2825/trust-gaurd-ai/blob/main/Frontend/src/App.tsx"
click node_login "https://github.com/avalanche2825/trust-gaurd-ai/blob/main/Frontend/src/components/LoginPage.tsx"
click node_kyc_ui "https://github.com/avalanche2825/trust-gaurd-ai/blob/main/Frontend/src/components/KYCOnboarding.tsx"
click node_txn_ui "https://github.com/avalanche2825/trust-gaurd-ai/blob/main/Frontend/src/components/TransactionForm.tsx"
click node_monitor_ui "https://github.com/avalanche2825/trust-gaurd-ai/blob/main/Frontend/src/components/ActiveSessionMonitor.tsx"
click node_recovery_ui "https://github.com/avalanche2825/trust-gaurd-ai/blob/main/Frontend/src/components/AccountRecoveryPanel.tsx"
click node_audit_ui "https://github.com/avalanche2825/trust-gaurd-ai/blob/main/Frontend/src/components/AuditLedgerViewer.tsx"
click node_insider_ui "https://github.com/avalanche2825/trust-gaurd-ai/blob/main/Frontend/src/components/InsiderOverwatch.tsx"
click node_guardian_ui "https://github.com/avalanche2825/trust-gaurd-ai/blob/main/Frontend/src/components/GuardianConsole.tsx"
click node_api "https://github.com/avalanche2825/trust-gaurd-ai/blob/main/backend/src/server.js"
click node_routes "https://github.com/avalanche2825/trust-gaurd-ai/blob/main/backend/src/routes/api.js"
click node_auth_mw "https://github.com/avalanche2825/trust-gaurd-ai/blob/main/backend/src/middlewares/auth.js"
click node_policy "https://github.com/avalanche2825/trust-gaurd-ai/tree/main/backend/src/controllers"
click node_domain "https://github.com/avalanche2825/trust-gaurd-ai/tree/main/backend/src/controllers"
click node_score_hook "https://github.com/avalanche2825/trust-gaurd-ai/blob/main/backend/src/controllers/mlController.js"
click node_db_bridge "https://github.com/avalanche2825/trust-gaurd-ai/blob/main/backend/src/utils/dbBridge.js"
click node_store "https://github.com/avalanche2825/trust-gaurd-ai/blob/main/backend/src/models/User.js"
click node_fallback "https://github.com/avalanche2825/trust-gaurd-ai/blob/main/backend/src/utils/inMemoryDB.js"
click node_ml_app "https://github.com/avalanche2825/trust-gaurd-ai/blob/main/ml_service/app.py"
click node_engines "https://github.com/avalanche2825/trust-gaurd-ai/tree/main/ml_service/models"
click node_scorer "https://github.com/avalanche2825/trust-gaurd-ai/blob/main/ml_service/models/unified_scorer.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ui,node_login,node_kyc_ui,node_txn_ui,node_monitor_ui,node_recovery_ui,node_audit_ui,node_insider_ui,node_guardian_ui toneBlue
class node_api,node_routes,node_auth_mw,node_policy,node_domain,node_score_hook,node_db_bridge toneAmber
class node_ml_app,node_engines,node_scorer toneMint
class node_store,node_fallback toneRose
```

## Components

### Frontend

React/Vite analyst and operator console

- [Security Console](https://github.com/avalanche2825/trust-gaurd-ai/blob/main/Frontend/src/App.tsx): React SPA · Main analyst and operator interface for security workflows · `Frontend/src/App.tsx`
- [Login](https://github.com/avalanche2825/trust-gaurd-ai/blob/main/Frontend/src/components/LoginPage.tsx): auth screen · Entry and landing flow for the console · `Frontend/src/components/LoginPage.tsx`
- [KYC Onboarding](https://github.com/avalanche2825/trust-gaurd-ai/blob/main/Frontend/src/components/KYCOnboarding.tsx): workflow panel · Customer identity onboarding and review surface · `Frontend/src/components/KYCOnboarding.tsx`
- [Transaction Form](https://github.com/avalanche2825/trust-gaurd-ai/blob/main/Frontend/src/components/TransactionForm.tsx): workflow panel · Transaction entry and risk-aware submission surface · `Frontend/src/components/TransactionForm.tsx`
- [Session Monitor](https://github.com/avalanche2825/trust-gaurd-ai/blob/main/Frontend/src/components/ActiveSessionMonitor.tsx): monitoring panel · Active session and live trust monitoring surface · `Frontend/src/components/ActiveSessionMonitor.tsx`
- [Recovery Panel](https://github.com/avalanche2825/trust-gaurd-ai/blob/main/Frontend/src/components/AccountRecoveryPanel.tsx): workflow panel · Account recovery and step-up intervention surface · `Frontend/src/components/AccountRecoveryPanel.tsx`
- [Audit Viewer](https://github.com/avalanche2825/trust-gaurd-ai/blob/main/Frontend/src/components/AuditLedgerViewer.tsx): review panel · Audit ledger and immutable event review surface · `Frontend/src/components/AuditLedgerViewer.tsx`
- [Insider Watch](https://github.com/avalanche2825/trust-gaurd-ai/blob/main/Frontend/src/components/InsiderOverwatch.tsx): monitoring panel · Employee and insider threat monitoring surface · `Frontend/src/components/InsiderOverwatch.tsx`
- [Guardian Console](https://github.com/avalanche2825/trust-gaurd-ai/blob/main/Frontend/src/components/GuardianConsole.tsx): control panel · Step-up and protective intervention console · `Frontend/src/components/GuardianConsole.tsx`

### Backend

Express control plane and API orchestration

- [Express API](https://github.com/avalanche2825/trust-gaurd-ai/blob/main/backend/src/server.js): Node service · Backend REST API and policy orchestration layer · `backend/src/server.js`
- [API Routes](https://github.com/avalanche2825/trust-gaurd-ai/blob/main/backend/src/routes/api.js): routing · Central request routing for domain endpoints · `backend/src/routes/api.js`
- [Auth Guard](https://github.com/avalanche2825/trust-gaurd-ai/blob/main/backend/src/middlewares/auth.js): middleware · Primary access-control boundary for sensitive actions · `backend/src/middlewares/auth.js`
- [Policy Engine](https://github.com/avalanche2825/trust-gaurd-ai/tree/main/backend/src/controllers): controllers · Authentication, recovery, token, and hacker-delay control flow · `backend/src/controllers`
- [Domain APIs](https://github.com/avalanche2825/trust-gaurd-ai/tree/main/backend/src/controllers): controllers · Customer, employee, transaction, KYC, audit, analytics, and ticket operations · `backend/src/controllers`
- [ML Hook](https://github.com/avalanche2825/trust-gaurd-ai/blob/main/backend/src/controllers/mlController.js): controller · Backend bridge to external risk scoring and prediction service · `backend/src/controllers/mlController.js`
- [DB Bridge](https://github.com/avalanche2825/trust-gaurd-ai/blob/main/backend/src/utils/dbBridge.js): storage adapter · Database abstraction with persistent and in-memory modes · `backend/src/utils/dbBridge.js`

### ML Service

Flask risk scoring and detection service

- [Flask Scorer](https://github.com/avalanche2825/trust-gaurd-ai/blob/main/ml_service/app.py): Python service · Independent risk-scoring and fraud-detection microservice · `ml_service/app.py`
- [Detectors](https://github.com/avalanche2825/trust-gaurd-ai/tree/main/ml_service/models): risk engines · Behavioral, device, insider, KYC graph, and text risk models · `ml_service/models`
- [Unified Score](https://github.com/avalanche2825/trust-gaurd-ai/blob/main/ml_service/models/unified_scorer.py): aggregator · 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](https://github.com/avalanche2825/trust-gaurd-ai/blob/main/backend/src/models/User.js): persistent store · Durable application data for users, transactions, audits, guardians, and KYC · `backend/src/models/User.js`
- [Memory Fallback](https://github.com/avalanche2825/trust-gaurd-ai/blob/main/backend/src/utils/inMemoryDB.js): volatile store · In-memory persistence for local or degraded runtime mode · `backend/src/utils/inMemoryDB.js`

## Connections

- 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