# samirthakre28/hydrotrace architecture

> Architecture diagram of the GitHub repository samirthakre28/hydrotrace, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samirthakre28/hydrotrace
- Repository: https://github.com/samirthakre28/hydrotrace

## Overview

HydroTrace is an investigative decision-support application for tracing suspicious TRON transfers and presenting evidence-based VASP candidates, conflicts, and exportable reports. Investigators submit bounded trace parameters, inspect transaction paths, evaluate attribution evidence, and generate case documentation. The graph preserves the major UI, tracing, attribution, and reporting stages. Source excerpts confirm the central engine calls; some client-to-server and unsampled UI details are shown only where the index or README supports them.

Main entry points: [`client/src/App.tsx`](https://github.com/samirthakre28/hydrotrace/blob/main/client/src/App.tsx) (App Router), [`client/src/pages/InvestigationDetailsPage.tsx`](https://github.com/samirthakre28/hydrotrace/blob/main/client/src/pages/InvestigationDetailsPage.tsx) (Investigation Details), [`server/src/controllers/investigation.controller.ts`](https://github.com/samirthakre28/hydrotrace/blob/main/server/src/controllers/investigation.controller.ts) (Investigation Controller), [`server/src/services/graph/GraphEngine.ts`](https://github.com/samirthakre28/hydrotrace/blob/main/server/src/services/graph/GraphEngine.ts) (Graph Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Investigator UI"]
  node_app["App Router<br/>[App.tsx]"]
  node_dashboard["Dashboard<br/>[DashboardPage.tsx]"]
  node_newcase["New Investigation"]
  node_details["Investigation Details"]
  node_attributionview["Evidence View"]
  node_graphview["Forensic Graph"]
  node_pathview["Path Inspector<br/>[PathInspector.tsx]"]
  node_scorecard["VASP Scorecard"]
  node_transactions["Transfer Table"]
end

subgraph group_api["API Layer"]
  node_clientapi["Client API<br/>[api.ts]"]
  node_routes["API Routes<br/>[index.ts]"]
  node_investigationroutes["Investigation Routes"]
  node_controller["Investigation Controller"]
end

subgraph group_trace["Blockchain Tracing"]
  node_graphengine["Graph Engine<br/>[GraphEngine.ts]"]
  node_traversal["Bounded Traversal<br/>[graphTraversal.ts]"]
  node_tron["TRON Provider<br/>[TronProvider.ts]"]
end

subgraph group_evidence["Attribution Evidence"]
  node_vaspengine["VASP Evaluation"]
  node_registry[("VASP Registry<br/>[vaspLabels.ts]")]
  node_bundle["Evidence Bundle"]
end

subgraph group_shared["Shared Contracts"]
  node_contracts["Shared Types<br/>[index.ts]"]
end

node_investigator(("Investigator"))
node_trongrid["TronGrid API"]

node_investigator -->|"uses"| node_app
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_newcase
node_app -->|"routes to"| node_details
node_app -->|"routes to"| node_attributionview
node_dashboard -->|"requests data"| node_clientapi
node_newcase -->|"submits trace"| node_clientapi
node_details -->|"requests results"| node_clientapi
node_details -->|"renders"| node_graphview
node_details -->|"renders"| node_pathview
node_details -->|"renders"| node_scorecard
node_newcase -->|"renders"| node_transactions
node_clientapi -.->|"calls HTTP API"| node_investigationroutes
node_routes -->|"mounts"| node_investigationroutes
node_investigationroutes -->|"dispatches"| node_controller
node_controller -->|"traces graph"| node_graphengine
node_controller -->|"evaluates attribution"| node_vaspengine
node_controller -->|"generates report"| node_bundle
node_graphengine -->|"traverses"| node_traversal
node_graphengine -->|"registers provider"| node_tron
node_tron -->|"fetches transfers"| node_trongrid
node_vaspengine -->|"looks up labels"| node_registry
node_vaspengine -->|"uses types"| node_contracts
node_graphengine -->|"returns trace data"| node_contracts
node_bundle -->|"uses types"| node_contracts

click node_app "https://github.com/samirthakre28/hydrotrace/blob/main/client/src/App.tsx"
click node_dashboard "https://github.com/samirthakre28/hydrotrace/blob/main/client/src/pages/DashboardPage.tsx"
click node_newcase "https://github.com/samirthakre28/hydrotrace/blob/main/client/src/pages/NewInvestigationPage.tsx"
click node_details "https://github.com/samirthakre28/hydrotrace/blob/main/client/src/pages/InvestigationDetailsPage.tsx"
click node_attributionview "https://github.com/samirthakre28/hydrotrace/blob/main/client/src/pages/EvidenceAttributionPage.tsx"
click node_graphview "https://github.com/samirthakre28/hydrotrace/blob/main/client/src/components/ForensicGraphView.tsx"
click node_pathview "https://github.com/samirthakre28/hydrotrace/blob/main/client/src/components/PathInspector.tsx"
click node_scorecard "https://github.com/samirthakre28/hydrotrace/blob/main/client/src/components/VaspCandidateScorecard.tsx"
click node_transactions "https://github.com/samirthakre28/hydrotrace/blob/main/client/src/components/TransactionTable.tsx"
click node_clientapi "https://github.com/samirthakre28/hydrotrace/blob/main/client/src/services/api.ts"
click node_routes "https://github.com/samirthakre28/hydrotrace/blob/main/server/src/routes/index.ts"
click node_investigationroutes "https://github.com/samirthakre28/hydrotrace/blob/main/server/src/routes/investigation.routes.ts"
click node_controller "https://github.com/samirthakre28/hydrotrace/blob/main/server/src/controllers/investigation.controller.ts"
click node_graphengine "https://github.com/samirthakre28/hydrotrace/blob/main/server/src/services/graph/GraphEngine.ts"
click node_traversal "https://github.com/samirthakre28/hydrotrace/blob/main/server/src/services/graph/graphTraversal.ts"
click node_tron "https://github.com/samirthakre28/hydrotrace/blob/main/server/src/services/blockchain/TronProvider.ts"
click node_vaspengine "https://github.com/samirthakre28/hydrotrace/blob/main/server/src/services/attribution/VaspCandidateEngine.ts"
click node_registry "https://github.com/samirthakre28/hydrotrace/blob/main/server/src/data/vaspLabels.ts"
click node_bundle "https://github.com/samirthakre28/hydrotrace/blob/main/server/src/services/report/EvidenceBundleService.ts"
click node_contracts "https://github.com/samirthakre28/hydrotrace/blob/main/shared/types/index.ts"

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_app,node_dashboard,node_newcase,node_details,node_attributionview,node_graphview,node_pathview,node_scorecard,node_transactions toneBlue
class node_clientapi,node_routes,node_investigationroutes,node_controller toneAmber
class node_graphengine,node_traversal,node_tron,node_trongrid toneMint
class node_vaspengine,node_registry,node_bundle toneRose
class node_contracts,node_investigator toneIndigo
```

## Components

### Investigator UI

- [App Router](https://github.com/samirthakre28/hydrotrace/blob/main/client/src/App.tsx): `client/src/App.tsx`
- [Dashboard](https://github.com/samirthakre28/hydrotrace/blob/main/client/src/pages/DashboardPage.tsx): `client/src/pages/DashboardPage.tsx`
- [New Investigation](https://github.com/samirthakre28/hydrotrace/blob/main/client/src/pages/NewInvestigationPage.tsx): `client/src/pages/NewInvestigationPage.tsx`
- [Investigation Details](https://github.com/samirthakre28/hydrotrace/blob/main/client/src/pages/InvestigationDetailsPage.tsx): `client/src/pages/InvestigationDetailsPage.tsx`
- [Evidence View](https://github.com/samirthakre28/hydrotrace/blob/main/client/src/pages/EvidenceAttributionPage.tsx): `client/src/pages/EvidenceAttributionPage.tsx`
- [Forensic Graph](https://github.com/samirthakre28/hydrotrace/blob/main/client/src/components/ForensicGraphView.tsx): `client/src/components/ForensicGraphView.tsx`
- [Path Inspector](https://github.com/samirthakre28/hydrotrace/blob/main/client/src/components/PathInspector.tsx): `client/src/components/PathInspector.tsx`
- [VASP Scorecard](https://github.com/samirthakre28/hydrotrace/blob/main/client/src/components/VaspCandidateScorecard.tsx): `client/src/components/VaspCandidateScorecard.tsx`
- [Transfer Table](https://github.com/samirthakre28/hydrotrace/blob/main/client/src/components/TransactionTable.tsx): `client/src/components/TransactionTable.tsx`

### API Layer

- [Client API](https://github.com/samirthakre28/hydrotrace/blob/main/client/src/services/api.ts): `client/src/services/api.ts`
- [API Routes](https://github.com/samirthakre28/hydrotrace/blob/main/server/src/routes/index.ts): `server/src/routes/index.ts`
- [Investigation Routes](https://github.com/samirthakre28/hydrotrace/blob/main/server/src/routes/investigation.routes.ts): `server/src/routes/investigation.routes.ts`
- [Investigation Controller](https://github.com/samirthakre28/hydrotrace/blob/main/server/src/controllers/investigation.controller.ts): `server/src/controllers/investigation.controller.ts`

### Blockchain Tracing

- [Graph Engine](https://github.com/samirthakre28/hydrotrace/blob/main/server/src/services/graph/GraphEngine.ts): `server/src/services/graph/GraphEngine.ts`
- [Bounded Traversal](https://github.com/samirthakre28/hydrotrace/blob/main/server/src/services/graph/graphTraversal.ts): `server/src/services/graph/graphTraversal.ts`
- [TRON Provider](https://github.com/samirthakre28/hydrotrace/blob/main/server/src/services/blockchain/TronProvider.ts): `server/src/services/blockchain/TronProvider.ts`

### Attribution Evidence

- [VASP Evaluation](https://github.com/samirthakre28/hydrotrace/blob/main/server/src/services/attribution/VaspCandidateEngine.ts): `server/src/services/attribution/VaspCandidateEngine.ts`
- [VASP Registry](https://github.com/samirthakre28/hydrotrace/blob/main/server/src/data/vaspLabels.ts): `server/src/data/vaspLabels.ts`
- [Evidence Bundle](https://github.com/samirthakre28/hydrotrace/blob/main/server/src/services/report/EvidenceBundleService.ts): `server/src/services/report/EvidenceBundleService.ts`

### Shared Contracts

- [Shared Types](https://github.com/samirthakre28/hydrotrace/blob/main/shared/types/index.ts): `shared/types/index.ts`

### Other components

- **Investigator**
- **TronGrid API**

## Connections

- Investigator → App Router: uses (evidence: `client/src/App.tsx`)
- App Router → Dashboard: routes to (evidence: `client/src/App.tsx`)
- App Router → New Investigation: routes to (evidence: `client/src/App.tsx`)
- App Router → Investigation Details: routes to (evidence: `client/src/App.tsx`)
- App Router → Evidence View: routes to (evidence: `client/src/App.tsx`)
- Dashboard → Client API: requests data (evidence: `client/src/pages/DashboardPage.tsx`)
- New Investigation → Client API: submits trace (evidence: `client/src/pages/NewInvestigationPage.tsx`)
- Investigation Details → Client API: requests results (evidence: `client/src/pages/InvestigationDetailsPage.tsx`)
- Investigation Details → Forensic Graph: renders (evidence: `client/src/pages/InvestigationDetailsPage.tsx`)
- Investigation Details → Path Inspector: renders (evidence: `client/src/pages/InvestigationDetailsPage.tsx`)
- Investigation Details → VASP Scorecard: renders (evidence: `client/src/pages/InvestigationDetailsPage.tsx`)
- New Investigation → Transfer Table: renders (evidence: `client/src/pages/NewInvestigationPage.tsx`)
- Client API → Investigation Routes: calls HTTP API
- API Routes → Investigation Routes: mounts (evidence: `server/src/routes/index.ts`)
- Investigation Routes → Investigation Controller: dispatches (evidence: `server/src/routes/investigation.routes.ts`)
- Investigation Controller → Graph Engine: traces graph (evidence: `server/src/controllers/investigation.controller.ts`)
- Investigation Controller → VASP Evaluation: evaluates attribution (evidence: `server/src/controllers/investigation.controller.ts`)
- Investigation Controller → Evidence Bundle: generates report (evidence: `server/src/controllers/investigation.controller.ts`)
- Graph Engine → Bounded Traversal: traverses (evidence: `server/src/services/graph/GraphEngine.ts`)
- Graph Engine → TRON Provider: registers provider (evidence: `server/src/services/graph/GraphEngine.ts`)
- TRON Provider → TronGrid API: fetches transfers (evidence: `server/src/services/blockchain/TronProvider.ts`)
- VASP Evaluation → VASP Registry: looks up labels (evidence: `server/src/services/attribution/VaspCandidateEngine.ts`)
- VASP Evaluation → Shared Types: uses types (evidence: `server/src/services/attribution/VaspCandidateEngine.ts`)
- Graph Engine → Shared Types: returns trace data (evidence: `server/src/services/graph/GraphEngine.ts`)
- Evidence Bundle → Shared Types: uses types (evidence: `server/src/services/report/EvidenceBundleService.ts`)