# shriya345/vasp-investigator architecture

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

- Interactive diagram: https://gitdiagram.com/shriya345/vasp-investigator
- Repository: https://github.com/shriya345/vasp-investigator

## Overview

Tracepoint is a local investigator dashboard for tracing supplied or synthetic blockchain evidence to evidence-supported VASP candidates—not identifying wallet owners. The workflow is: an investigator starts a demo or imports normalized evidence, the API validates it, obtains demo evidence when requested, analyzes fund flows and risk, then saves a case for dashboard review and report/evidence export. The README also documents interactive graph filtering, candidate-path highlighting, metrics, and case history. Some frontend request wiring and internal analysis stages were not shown, so those relationships are omitted or marked unverified.

Main entry points: [`backend/app/main.py`](https://github.com/shriya345/vasp-investigator/blob/main/backend/app/main.py) (Investigation API), [`backend/app/engine.py`](https://github.com/shriya345/vasp-investigator/blob/main/backend/app/engine.py) (Fund-flow tracing), [`frontend/app/page.tsx`](https://github.com/shriya345/vasp-investigator/blob/main/frontend/app/page.tsx) (Investigation dashboard), [`backend/app/models.py`](https://github.com/shriya345/vasp-investigator/blob/main/backend/app/models.py) (Evidence validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Investigation dashboard"]
  node_dashboard["Investigation dashboard<br/>[page.tsx]"]
  node_flowgraph["Interactive flow graph<br/>[FlowGraph.tsx]"]
  node_frontend_types["Dashboard data types<br/>[types.ts]"]
end

subgraph group_api["Evidence and API"]
  node_api_service["Investigation API<br/>[main.py]"]
  node_evidence_contracts["Evidence validation<br/>[models.py]"]
  node_demo_provider["Synthetic evidence provider<br/>[providers.py]"]
end

subgraph group_analysis["Tracing and assessment"]
  node_tracing["Fund-flow tracing<br/>[engine.py]"]
  node_attribution["VASP attribution<br/>[engine.py]"]
  node_risk_metrics["Risk and metrics<br/>[engine.py]"]
end

subgraph group_case["Case records and outputs"]
  node_case_store["Case persistence<br/>[storage.py]"]
  node_case_database[("SQLite or PostgreSQL")]
  node_report_renderer["Markdown report<br/>[report.py]"]
end

node_investigator(("Investigator"))
node_imported_evidence["Imported evidence"]

node_investigator -->|"starts investigation"| node_dashboard
node_dashboard -->|"renders graph"| node_flowgraph
node_dashboard -.->|"submits and retrieves cases"| node_api_service
node_imported_evidence -->|"supplies evidence"| node_api_service
node_api_service -->|"validates requests"| node_evidence_contracts
node_api_service -->|"fetches demo evidence"| node_demo_provider
node_demo_provider -->|"builds normalized records"| node_evidence_contracts
node_api_service -->|"runs analysis"| node_tracing
node_tracing -->|"consumes request schema"| node_evidence_contracts
node_api_service -->|"saves cases"| node_case_store
node_case_store -->|"reads and writes"| node_case_database
node_api_service -->|"renders report"| node_report_renderer
node_tracing -->|"scores candidates"| node_attribution
node_tracing -->|"computes risk and metrics"| node_risk_metrics
node_api_service -.->|"returns case results"| node_dashboard

click node_dashboard "https://github.com/shriya345/vasp-investigator/blob/main/frontend/app/page.tsx"
click node_flowgraph "https://github.com/shriya345/vasp-investigator/blob/main/frontend/components/FlowGraph.tsx"
click node_frontend_types "https://github.com/shriya345/vasp-investigator/blob/main/frontend/lib/types.ts"
click node_api_service "https://github.com/shriya345/vasp-investigator/blob/main/backend/app/main.py"
click node_evidence_contracts "https://github.com/shriya345/vasp-investigator/blob/main/backend/app/models.py"
click node_demo_provider "https://github.com/shriya345/vasp-investigator/blob/main/backend/app/providers.py"
click node_tracing "https://github.com/shriya345/vasp-investigator/blob/main/backend/app/engine.py"
click node_attribution "https://github.com/shriya345/vasp-investigator/blob/main/backend/app/engine.py"
click node_risk_metrics "https://github.com/shriya345/vasp-investigator/blob/main/backend/app/engine.py"
click node_case_store "https://github.com/shriya345/vasp-investigator/blob/main/backend/app/storage.py"
click node_report_renderer "https://github.com/shriya345/vasp-investigator/blob/main/backend/app/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_dashboard,node_flowgraph,node_frontend_types toneBlue
class node_api_service,node_evidence_contracts,node_demo_provider toneAmber
class node_tracing,node_attribution,node_risk_metrics toneMint
class node_case_store,node_case_database,node_report_renderer toneRose
class node_investigator,node_imported_evidence toneIndigo
```

## Components

### Investigation dashboard

- [Investigation dashboard](https://github.com/shriya345/vasp-investigator/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Interactive flow graph](https://github.com/shriya345/vasp-investigator/blob/main/frontend/components/FlowGraph.tsx): `frontend/components/FlowGraph.tsx`
- [Dashboard data types](https://github.com/shriya345/vasp-investigator/blob/main/frontend/lib/types.ts): `frontend/lib/types.ts`

### Evidence and API

- [Investigation API](https://github.com/shriya345/vasp-investigator/blob/main/backend/app/main.py): `backend/app/main.py`
- [Evidence validation](https://github.com/shriya345/vasp-investigator/blob/main/backend/app/models.py): `backend/app/models.py`
- [Synthetic evidence provider](https://github.com/shriya345/vasp-investigator/blob/main/backend/app/providers.py): `backend/app/providers.py`

### Tracing and assessment

- [Fund-flow tracing](https://github.com/shriya345/vasp-investigator/blob/main/backend/app/engine.py): `backend/app/engine.py`
- [VASP attribution](https://github.com/shriya345/vasp-investigator/blob/main/backend/app/engine.py): `backend/app/engine.py`
- [Risk and metrics](https://github.com/shriya345/vasp-investigator/blob/main/backend/app/engine.py): `backend/app/engine.py`

### Case records and outputs

- [Case persistence](https://github.com/shriya345/vasp-investigator/blob/main/backend/app/storage.py): `backend/app/storage.py`
- **SQLite or PostgreSQL**
- [Markdown report](https://github.com/shriya345/vasp-investigator/blob/main/backend/app/report.py): `backend/app/report.py`

### Other components

- **Investigator**
- **Imported evidence**

## Connections

- Investigator → Investigation dashboard: starts investigation (evidence: `README.md`)
- Investigation dashboard → Interactive flow graph: renders graph (evidence: `frontend/app/page.tsx`)
- Investigation dashboard → Investigation API: submits and retrieves cases
- Imported evidence → Investigation API: supplies evidence (evidence: `README.md`)
- Investigation API → Evidence validation: validates requests (evidence: `backend/app/main.py`)
- Investigation API → Synthetic evidence provider: fetches demo evidence (evidence: `backend/app/main.py`)
- Synthetic evidence provider → Evidence validation: builds normalized records (evidence: `backend/app/providers.py`)
- Investigation API → Fund-flow tracing: runs analysis (evidence: `backend/app/main.py`)
- Fund-flow tracing → Evidence validation: consumes request schema (evidence: `backend/app/engine.py`)
- Investigation API → Case persistence: saves cases (evidence: `backend/app/main.py`)
- Case persistence → SQLite or PostgreSQL: reads and writes (evidence: `backend/app/storage.py`)
- Investigation API → Markdown report: renders report (evidence: `backend/app/main.py`)
- Fund-flow tracing → VASP attribution: scores candidates (evidence: `README.md`)
- Fund-flow tracing → Risk and metrics: computes risk and metrics (evidence: `README.md`)
- Investigation API → Investigation dashboard: returns case results
