# vicky4t/sih-183 architecture

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

- Interactive diagram: https://gitdiagram.com/vicky4t/sih-183
- Repository: https://github.com/vicky4t/sih-183

## Overview

SHADOWTRACE is a crypto-fraud investigation platform: an investigator submits a suspect wallet, the system traces related wallets and analyzes transactions for patterns, VASP links, clusters, and risk, then presents findings for investigation and reporting. The graph emphasizes this workflow and the documented dashboard, cases, alerts, and PDF reporting capabilities. Sampled source confirms the tracing and analysis internals and frontend calls; several API-to-service and persistence links are documented or suggested by module names but not visible in the excerpts, so those uncertain connections are omitted.

Main entry points: [`frontend/app/lib/api.ts`](https://github.com/vicky4t/sih-183/blob/master/frontend/app/lib/api.ts) (API Client), [`backend/app/services/analysis_pipeline.py`](https://github.com/vicky4t/sih-183/blob/master/backend/app/services/analysis_pipeline.py) (Analysis Pipeline), [`backend/app/main.py`](https://github.com/vicky4t/sih-183/blob/master/backend/app/main.py) (FastAPI App), [`frontend/app/investigate/page.tsx`](https://github.com/vicky4t/sih-183/blob/master/frontend/app/investigate/page.tsx) (Investigate)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Investigator UI"]
  node_investigate_page["Investigate<br/>[page.tsx]"]
  node_cases_page["Cases Dashboard<br/>[page.tsx]"]
  node_dashboard_page["Overview Dashboard<br/>[page.tsx]"]
  node_reports_page["Reports<br/>[page.tsx]"]
  node_frontend_api["API Client<br/>[api.ts]"]
  node_graph_builder["Graph Builder<br/>[graph.ts]"]
end

subgraph group_api["Backend API"]
  node_api_app["FastAPI App<br/>[main.py]"]
  node_cases_api["Case Routes<br/>[cases.py]"]
  node_analysis_api["Analysis Routes<br/>[analysis.py]"]
  node_reports_api["Report Routes<br/>[reports.py]"]
end

subgraph group_analysis["Intelligence Analysis"]
  node_trace_engine["Wallet Tracing<br/>[trace_engine.py]"]
  node_analysis_pipeline["Analysis Pipeline"]
  node_pattern_detectors["Pattern Detection"]
  node_cluster_builder["Wallet Clustering<br/>[wallet_cluster.py]"]
  node_vasp_matching["VASP Matching"]
  node_nearest_vasp["Nearest VASP<br/>[nearest_vasp.py]"]
  node_risk_scoring["Risk Scoring<br/>[risk_scoring.py]"]
  node_alert_generator["Alert Generation<br/>[alert_generator.py]"]
end

subgraph group_data["Data and Integrations"]
  node_blockchain_api["Etherscan API<br/>[etherscan.py]"]
  node_case_store[("Case Database<br/>[database.py]")]
  node_case_model["Case Model<br/>[case.py]"]
  node_pdf_reports["PDF Reports<br/>[pdf_report.py]"]
end

node_investigator(("Investigator"))

node_investigator -->|"submits wallet"| node_investigate_page
node_investigator -->|"reviews cases"| node_cases_page
node_investigator -->|"views overview"| node_dashboard_page
node_investigator -->|"requests reports"| node_reports_page
node_investigate_page -->|"calls case and analysis APIs"| node_frontend_api
node_cases_page -->|"loads cases"| node_frontend_api
node_dashboard_page -->|"loads cases"| node_frontend_api
node_reports_page -->|"loads and analyzes cases"| node_frontend_api
node_investigate_page -->|"builds display graph"| node_graph_builder
node_frontend_api -->|"REST requests"| node_cases_api
node_frontend_api -->|"REST requests"| node_analysis_api
node_frontend_api -->|"REST requests"| node_reports_api
node_api_app -->|"registers router"| node_cases_api
node_api_app -->|"registers router"| node_analysis_api
node_api_app -->|"registers router"| node_reports_api
node_trace_engine -->|"fetches transactions"| node_blockchain_api
node_analysis_pipeline -->|"detects patterns"| node_pattern_detectors
node_analysis_pipeline -->|"matches exchanges"| node_vasp_matching
node_analysis_pipeline -->|"finds nearby VASPs"| node_nearest_vasp
node_analysis_pipeline -->|"builds wallet cluster"| node_cluster_builder
node_analysis_pipeline -->|"calculates risk"| node_risk_scoring
node_analysis_pipeline -->|"generates alert"| node_alert_generator
node_reports_api -->|"generates reports"| node_pdf_reports

click node_investigate_page "https://github.com/vicky4t/sih-183/blob/master/frontend/app/investigate/page.tsx"
click node_cases_page "https://github.com/vicky4t/sih-183/blob/master/frontend/app/cases/page.tsx"
click node_dashboard_page "https://github.com/vicky4t/sih-183/blob/master/frontend/app/dashboard/page.tsx"
click node_reports_page "https://github.com/vicky4t/sih-183/blob/master/frontend/app/reports/page.tsx"
click node_frontend_api "https://github.com/vicky4t/sih-183/blob/master/frontend/app/lib/api.ts"
click node_graph_builder "https://github.com/vicky4t/sih-183/blob/master/frontend/app/lib/graph.ts"
click node_api_app "https://github.com/vicky4t/sih-183/blob/master/backend/app/main.py"
click node_cases_api "https://github.com/vicky4t/sih-183/blob/master/backend/app/api/cases.py"
click node_analysis_api "https://github.com/vicky4t/sih-183/blob/master/backend/app/api/analysis.py"
click node_reports_api "https://github.com/vicky4t/sih-183/blob/master/backend/app/api/reports.py"
click node_trace_engine "https://github.com/vicky4t/sih-183/blob/master/backend/app/services/tracing/trace_engine.py"
click node_analysis_pipeline "https://github.com/vicky4t/sih-183/blob/master/backend/app/services/analysis_pipeline.py"
click node_pattern_detectors "https://github.com/vicky4t/sih-183/tree/master/backend/app/services/patterns"
click node_cluster_builder "https://github.com/vicky4t/sih-183/blob/master/backend/app/services/clustering/wallet_cluster.py"
click node_vasp_matching "https://github.com/vicky4t/sih-183/blob/master/backend/app/services/exchange_matcher.py"
click node_nearest_vasp "https://github.com/vicky4t/sih-183/blob/master/backend/app/services/nearest_vasp.py"
click node_risk_scoring "https://github.com/vicky4t/sih-183/blob/master/backend/app/services/risk_scoring.py"
click node_alert_generator "https://github.com/vicky4t/sih-183/blob/master/backend/app/services/alert_generator.py"
click node_blockchain_api "https://github.com/vicky4t/sih-183/blob/master/backend/app/services/blockchain/etherscan.py"
click node_case_store "https://github.com/vicky4t/sih-183/blob/master/backend/app/database.py"
click node_case_model "https://github.com/vicky4t/sih-183/blob/master/backend/app/models/case.py"
click node_pdf_reports "https://github.com/vicky4t/sih-183/blob/master/backend/app/services/reporting/pdf_report.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_investigate_page,node_cases_page,node_dashboard_page,node_reports_page,node_frontend_api,node_graph_builder toneBlue
class node_api_app,node_cases_api,node_analysis_api,node_reports_api toneAmber
class node_trace_engine,node_analysis_pipeline,node_pattern_detectors,node_cluster_builder,node_vasp_matching,node_nearest_vasp,node_risk_scoring,node_alert_generator toneMint
class node_blockchain_api,node_case_store,node_case_model,node_pdf_reports toneRose
class node_investigator toneIndigo
```

## Components

### Investigator UI

- [Investigate](https://github.com/vicky4t/sih-183/blob/master/frontend/app/investigate/page.tsx): `frontend/app/investigate/page.tsx`
- [Cases Dashboard](https://github.com/vicky4t/sih-183/blob/master/frontend/app/cases/page.tsx): `frontend/app/cases/page.tsx`
- [Overview Dashboard](https://github.com/vicky4t/sih-183/blob/master/frontend/app/dashboard/page.tsx): `frontend/app/dashboard/page.tsx`
- [Reports](https://github.com/vicky4t/sih-183/blob/master/frontend/app/reports/page.tsx): `frontend/app/reports/page.tsx`
- [API Client](https://github.com/vicky4t/sih-183/blob/master/frontend/app/lib/api.ts): `frontend/app/lib/api.ts`
- [Graph Builder](https://github.com/vicky4t/sih-183/blob/master/frontend/app/lib/graph.ts): `frontend/app/lib/graph.ts`

### Backend API

- [FastAPI App](https://github.com/vicky4t/sih-183/blob/master/backend/app/main.py): `backend/app/main.py`
- [Case Routes](https://github.com/vicky4t/sih-183/blob/master/backend/app/api/cases.py): `backend/app/api/cases.py`
- [Analysis Routes](https://github.com/vicky4t/sih-183/blob/master/backend/app/api/analysis.py): `backend/app/api/analysis.py`
- [Report Routes](https://github.com/vicky4t/sih-183/blob/master/backend/app/api/reports.py): `backend/app/api/reports.py`

### Intelligence Analysis

- [Wallet Tracing](https://github.com/vicky4t/sih-183/blob/master/backend/app/services/tracing/trace_engine.py): `backend/app/services/tracing/trace_engine.py`
- [Analysis Pipeline](https://github.com/vicky4t/sih-183/blob/master/backend/app/services/analysis_pipeline.py): `backend/app/services/analysis_pipeline.py`
- [Pattern Detection](https://github.com/vicky4t/sih-183/tree/master/backend/app/services/patterns): `backend/app/services/patterns`
- [Wallet Clustering](https://github.com/vicky4t/sih-183/blob/master/backend/app/services/clustering/wallet_cluster.py): `backend/app/services/clustering/wallet_cluster.py`
- [VASP Matching](https://github.com/vicky4t/sih-183/blob/master/backend/app/services/exchange_matcher.py): `backend/app/services/exchange_matcher.py`
- [Nearest VASP](https://github.com/vicky4t/sih-183/blob/master/backend/app/services/nearest_vasp.py): `backend/app/services/nearest_vasp.py`
- [Risk Scoring](https://github.com/vicky4t/sih-183/blob/master/backend/app/services/risk_scoring.py): `backend/app/services/risk_scoring.py`
- [Alert Generation](https://github.com/vicky4t/sih-183/blob/master/backend/app/services/alert_generator.py): `backend/app/services/alert_generator.py`

### Data and Integrations

- [Etherscan API](https://github.com/vicky4t/sih-183/blob/master/backend/app/services/blockchain/etherscan.py): `backend/app/services/blockchain/etherscan.py`
- [Case Database](https://github.com/vicky4t/sih-183/blob/master/backend/app/database.py): `backend/app/database.py`
- [Case Model](https://github.com/vicky4t/sih-183/blob/master/backend/app/models/case.py): `backend/app/models/case.py`
- [PDF Reports](https://github.com/vicky4t/sih-183/blob/master/backend/app/services/reporting/pdf_report.py): `backend/app/services/reporting/pdf_report.py`

### Other components

- **Investigator**

## Connections

- Investigator → Investigate: submits wallet
- Investigator → Cases Dashboard: reviews cases
- Investigator → Overview Dashboard: views overview
- Investigator → Reports: requests reports
- Investigate → API Client: calls case and analysis APIs
- Cases Dashboard → API Client: loads cases
- Overview Dashboard → API Client: loads cases
- Reports → API Client: loads and analyzes cases
- Investigate → Graph Builder: builds display graph
- API Client → Case Routes: REST requests
- API Client → Analysis Routes: REST requests
- API Client → Report Routes: REST requests
- FastAPI App → Case Routes: registers router
- FastAPI App → Analysis Routes: registers router
- FastAPI App → Report Routes: registers router
- Wallet Tracing → Etherscan API: fetches transactions
- Analysis Pipeline → Pattern Detection: detects patterns
- Analysis Pipeline → VASP Matching: matches exchanges
- Analysis Pipeline → Nearest VASP: finds nearby VASPs
- Analysis Pipeline → Wallet Clustering: builds wallet cluster
- Analysis Pipeline → Risk Scoring: calculates risk
- Analysis Pipeline → Alert Generation: generates alert
- Report Routes → PDF Reports: generates reports