# luno141/tigergraph architecture

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

- Interactive diagram: https://gitdiagram.com/luno141/tigergraph
- Repository: https://github.com/luno141/tigergraph

## Overview

1. GraphGuard AI is a three-tier fraud investigation system centered on TigerGraph. The graph database is the source of truth for entities and relationships; a Python FastAPI backend turns graph analytics into API responses; a React/Vite frontend renders the investigation workspace.

2. The core domain model is graph-native, not relational. The repository’s README and GSQL files show the schema built around `User`, `Phone`, `BankAccount`, and `Device` vertices, with edges like `HAS_PHONE`, `OWNS_ACCOUNT`, `USES_DEVICE`, and `SENT_TO`. This is the main architectural boundary: fraud logic lives in graph traversal and pattern matching, not in the UI.

3. TigerGraph is the analytical engine. The `.gsql` files (`schema_only.gsql`, `queries_only.gsql`, `tigergraph_queries.gsql`, `tigergraph_setup.gsql`, `fix_two.gsql`) define and install the schema plus query procedures such as connection discovery, circular money-flow detection, and shared-device analysis. These queries are meant to run inside TigerGraph for low-latency traversal.

4. The backend folder is an API adapter layer. `backend/main.py` is the FastAPI entrypoint, while `backend/models.py` likely defines request/response shapes for search results, risk scores, and graph payloads. The backend’s role is to expose a stable HTTP API while isolating the frontend from TigerGraph-specific details.

5. `backend/tigergraph_client.py` is the database integration boundary. It likely wraps `pyTigerGraph` calls to TigerGraph’s REST++ endpoints, translating backend requests into query executions and normalizing the returned graph data for the API layer.

6. `backend/risk_scorer.py` provides the fraud decision layer. Based on the README, risk is derived from graph proximity to known bad actors, shared infrastructure, and suspicious network motifs. This is where graph analytics becomes a user-facing score or severity signal.

7. `backend/data_loader.py` and the TigerGraph setup scripts form the bootstrap pipeline. `setup_tigergraph.py` and `setup_tigergraph_v2.py` automate schema creation, query installation, and mock data loading into TigerGraph. This means the database is not just a passive store; it is provisioned and seeded as part of the repository workflow.

8. `backend/fix_queries.py` suggests query maintenance/patching support. Combined with the multiple GSQL files, it indicates that graph query definitions are treated as first-class artifacts and may be iterated independently of the application code.

9. The frontend is a single-page investigation dashboard built with React and Vite. `frontend/src/App.jsx` composes the page, and the component set shows the UI’s main panels: search, stats, graph visualization, risk summary, and explanation output. The frontend appears to be presentation-only, with no direct database access.

10. `GraphView.jsx` is the main visualization surface, and the README’s mention of `react-cytoscapejs` suggests the graph is rendered interactively as nodes and edges. `SearchBar.jsx` likely drives investigation queries, while `RiskMeter.jsx`, `StatsCards.jsx`, and `ExplanationPanel.jsx` present the backend’s analytical output in a digestible way.

11. The primary runtime data flow is: user searches in the frontend → frontend calls the FastAPI backend → backend executes TigerGraph queries through the client wrapper → TigerGraph returns matching subgraphs, patterns, and scores → backend formats the response → frontend renders the graph and supporting panels. This keeps query execution and graph traversal off the browser and inside the database engine.

12. Deployment is intended to be local and developer-managed: TigerGraph runs in Docker, the backend runs with Uvicorn on port 8000, and the frontend runs on Vite dev server port 5173. That implies a clear separation between the database container, API service, and UI process, with the backend acting as the only integration point to TigerGraph.

Main entry points: [`backend/main.py`](https://github.com/luno141/tigergraph/blob/main/backend/main.py) (API entrypoint), [`frontend/src/App.jsx`](https://github.com/luno141/tigergraph/blob/main/frontend/src/App.jsx) (App shell), [`queries_only.gsql`](https://github.com/luno141/tigergraph/blob/main/queries_only.gsql) (Analytics queries), [`tigergraph_setup.gsql`](https://github.com/luno141/tigergraph/blob/main/tigergraph_setup.gsql) (DB setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_graphdb["TigerGraph layer"]
  node_schema["Graph schema<br/>[schema_only.gsql]"]
  node_queries["Analytics queries<br/>GSQL queries<br/>[queries_only.gsql]"]
  node_tg_queries["Query bundle<br/>GSQL package"]
  node_tg_setup["DB setup<br/>TigerGraph install"]
  node_fix_two["Query patch<br/>GSQL fix<br/>[fix_two.gsql]"]
end

subgraph group_backend["API layer"]
  node_main_api["API entrypoint<br/>FastAPI app<br/>[main.py]"]
  node_api_models["API models<br/>Pydantic shapes<br/>[models.py]"]
  node_tg_client["Graph client<br/>TigerGraph adapter"]
  node_risk_scorer["Risk scorer<br/>Fraud logic<br/>[risk_scorer.py]"]
  node_data_loader["Data loader<br/>Seed pipeline<br/>[data_loader.py]"]
end

subgraph group_frontend["Investigation UI"]
  node_app["App shell<br/>React entry<br/>[App.jsx]"]
  node_search_bar["Search bar<br/>UI control<br/>[SearchBar.jsx]"]
  node_graph_view["Graph view<br/>Cytoscape view<br/>[GraphView.jsx]"]
  node_risk_meter["Risk meter<br/>UI summary<br/>[RiskMeter.jsx]"]
  node_stats_cards["Stats cards<br/>UI summary<br/>[StatsCards.jsx]"]
  node_explanation_panel["Explanation panel<br/>UI narrative"]
  node_header["Header<br/>UI chrome<br/>[Header.jsx]"]
end

subgraph group_ops["Bootstrap scripts"]
  node_setup_v1["Setup script<br/>Provisioning script"]
  node_setup_v2["Setup v2<br/>Provisioning script"]
  node_fix_queries["Query maintainer<br/>Maintenance script<br/>[fix_queries.py]"]
end

node_tg_setup -->|"installs"| node_schema
node_tg_setup -->|"loads"| node_queries
node_tg_queries -->|"packages"| node_queries
node_fix_two -->|"patches"| node_queries
node_setup_v1 -->|"orchestrates"| node_tg_setup
node_setup_v2 -->|"orchestrates"| node_tg_setup
node_setup_v1 -->|"seeds"| node_data_loader
node_data_loader -->|"populates"| node_schema
node_fix_queries -->|"maintains"| node_queries
node_main_api -->|"uses"| node_tg_client
node_main_api -->|"scores"| node_risk_scorer
node_main_api -->|"shapes"| node_api_models
node_tg_client -->|"executes"| node_queries
node_tg_client -->|"reads"| node_schema
node_risk_scorer -->|"interprets"| node_queries
node_app -->|"composes"| node_search_bar
node_app -->|"composes"| node_graph_view
node_app -->|"composes"| node_risk_meter
node_app -->|"composes"| node_stats_cards
node_app -->|"composes"| node_explanation_panel
node_app -->|"composes"| node_header
node_search_bar -->|"queries"| node_main_api
node_graph_view -->|"renders"| node_main_api
node_risk_meter -->|"displays"| node_main_api
node_stats_cards -->|"displays"| node_main_api
node_explanation_panel -->|"explains"| node_main_api

click node_schema "https://github.com/luno141/tigergraph/blob/main/schema_only.gsql"
click node_queries "https://github.com/luno141/tigergraph/blob/main/queries_only.gsql"
click node_tg_queries "https://github.com/luno141/tigergraph/blob/main/tigergraph_queries.gsql"
click node_tg_setup "https://github.com/luno141/tigergraph/blob/main/tigergraph_setup.gsql"
click node_fix_two "https://github.com/luno141/tigergraph/blob/main/fix_two.gsql"
click node_main_api "https://github.com/luno141/tigergraph/blob/main/backend/main.py"
click node_api_models "https://github.com/luno141/tigergraph/blob/main/backend/models.py"
click node_tg_client "https://github.com/luno141/tigergraph/blob/main/backend/tigergraph_client.py"
click node_risk_scorer "https://github.com/luno141/tigergraph/blob/main/backend/risk_scorer.py"
click node_data_loader "https://github.com/luno141/tigergraph/blob/main/backend/data_loader.py"
click node_setup_v1 "https://github.com/luno141/tigergraph/blob/main/backend/setup_tigergraph.py"
click node_setup_v2 "https://github.com/luno141/tigergraph/blob/main/backend/setup_tigergraph_v2.py"
click node_fix_queries "https://github.com/luno141/tigergraph/blob/main/backend/fix_queries.py"
click node_app "https://github.com/luno141/tigergraph/blob/main/frontend/src/App.jsx"
click node_search_bar "https://github.com/luno141/tigergraph/blob/main/frontend/src/components/SearchBar.jsx"
click node_graph_view "https://github.com/luno141/tigergraph/blob/main/frontend/src/components/GraphView.jsx"
click node_risk_meter "https://github.com/luno141/tigergraph/blob/main/frontend/src/components/RiskMeter.jsx"
click node_stats_cards "https://github.com/luno141/tigergraph/blob/main/frontend/src/components/StatsCards.jsx"
click node_explanation_panel "https://github.com/luno141/tigergraph/blob/main/frontend/src/components/ExplanationPanel.jsx"
click node_header "https://github.com/luno141/tigergraph/blob/main/frontend/src/components/Header.jsx"

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_schema,node_queries,node_tg_queries,node_tg_setup,node_fix_two toneBlue
class node_main_api,node_api_models,node_tg_client,node_risk_scorer,node_data_loader toneAmber
class node_app,node_search_bar,node_graph_view,node_risk_meter,node_stats_cards,node_explanation_panel,node_header toneMint
class node_setup_v1,node_setup_v2,node_fix_queries toneRose
```

## Components

### TigerGraph layer

Graph database schema, queries, and setup artifacts that hold the fraud investigation model and analytics.

- [Graph schema](https://github.com/luno141/tigergraph/blob/main/schema_only.gsql): TigerGraph schema · Core vertex and edge model centered on users, phones, bank accounts, devices, and transaction links. · `schema_only.gsql`
- [Analytics queries](https://github.com/luno141/tigergraph/blob/main/queries_only.gsql): GSQL queries · Stored procedures for connection discovery, circular flow detection, and shared-asset analysis. · `queries_only.gsql`
- [Query bundle](https://github.com/luno141/tigergraph/blob/main/tigergraph_queries.gsql): GSQL package · Repository-level query definitions prepared for installation into TigerGraph. · `tigergraph_queries.gsql`
- [DB setup](https://github.com/luno141/tigergraph/blob/main/tigergraph_setup.gsql): TigerGraph install · Schema and query installation script for provisioning the graph database. · `tigergraph_setup.gsql`
- [Query patch](https://github.com/luno141/tigergraph/blob/main/fix_two.gsql): GSQL fix · Targeted query correction or replacement artifact kept alongside the main graph procedures. · `fix_two.gsql`

### API layer

FastAPI adapter that runs TigerGraph queries, scores risk, and shapes responses for the UI.

- [API entrypoint](https://github.com/luno141/tigergraph/blob/main/backend/main.py): FastAPI app · HTTP server entrypoint that exposes fraud investigation endpoints. · `backend/main.py`
- [API models](https://github.com/luno141/tigergraph/blob/main/backend/models.py): Pydantic shapes · Request and response contracts for search, graph payloads, and risk outputs. · `backend/models.py`
- [Graph client](https://github.com/luno141/tigergraph/blob/main/backend/tigergraph_client.py): TigerGraph adapter · Database integration wrapper around TigerGraph REST queries and response normalization. · `backend/tigergraph_client.py`
- [Risk scorer](https://github.com/luno141/tigergraph/blob/main/backend/risk_scorer.py): Fraud logic · Graph-based scoring and severity logic derived from proximity, shared infrastructure, and motifs. · `backend/risk_scorer.py`
- [Data loader](https://github.com/luno141/tigergraph/blob/main/backend/data_loader.py): Seed pipeline · Loads mock or starter data into the graph database during setup and development. · `backend/data_loader.py`

### Investigation UI

React/Vite workspace that lets analysts search, inspect subgraphs, and review risk explanations.

- [App shell](https://github.com/luno141/tigergraph/blob/main/frontend/src/App.jsx): React entry · Top-level frontend composition for the investigation workspace. · `frontend/src/App.jsx`
- [Search bar](https://github.com/luno141/tigergraph/blob/main/frontend/src/components/SearchBar.jsx): UI control · Investigation input used to launch graph lookups and analyst queries. · `frontend/src/components/SearchBar.jsx`
- [Graph view](https://github.com/luno141/tigergraph/blob/main/frontend/src/components/GraphView.jsx): Cytoscape view · Interactive node-edge visualization for discovered fraud networks. · `frontend/src/components/GraphView.jsx`
- [Risk meter](https://github.com/luno141/tigergraph/blob/main/frontend/src/components/RiskMeter.jsx): UI summary · Visualizes the backend risk score or severity signal for the current case. · `frontend/src/components/RiskMeter.jsx`
- [Stats cards](https://github.com/luno141/tigergraph/blob/main/frontend/src/components/StatsCards.jsx): UI summary · Displays key investigation counts and graph metrics returned by the backend. · `frontend/src/components/StatsCards.jsx`
- [Explanation panel](https://github.com/luno141/tigergraph/blob/main/frontend/src/components/ExplanationPanel.jsx): UI narrative · Shows human-readable reasoning and supporting signals for the investigation result. · `frontend/src/components/ExplanationPanel.jsx`
- [Header](https://github.com/luno141/tigergraph/blob/main/frontend/src/components/Header.jsx): UI chrome · Top-level branding and navigation chrome for the dashboard. · `frontend/src/components/Header.jsx`

### Bootstrap scripts

Repository automation for installing schema, loading data, and maintaining queries.

- [Setup script](https://github.com/luno141/tigergraph/blob/main/backend/setup_tigergraph.py): Provisioning script · Automates TigerGraph schema creation, query installation, and initial loading. · `backend/setup_tigergraph.py`
- [Setup v2](https://github.com/luno141/tigergraph/blob/main/backend/setup_tigergraph_v2.py): Provisioning script · Alternate or updated TigerGraph provisioning workflow. · `backend/setup_tigergraph_v2.py`
- [Query maintainer](https://github.com/luno141/tigergraph/blob/main/backend/fix_queries.py): Maintenance script · Supports updating or patching graph queries independently from the app runtime. · `backend/fix_queries.py`

## Connections

- DB setup → Graph schema: installs · The database setup script provisions the core graph schema.
- DB setup → Analytics queries: loads · The setup script installs query procedures into TigerGraph.
- Query bundle → Analytics queries: packages · Repository query bundle provides the deployed analytics procedures.
- Query patch → Analytics queries: patches · Targeted fixes adjust graph query behavior.
- Setup script → DB setup: orchestrates · Provisioning automation coordinates database setup.
- Setup v2 → DB setup: orchestrates · Updated provisioning automation coordinates database setup.
- Setup script → Data loader: seeds · Bootstrap flow loads starter data after provisioning.
- Data loader → Graph schema: populates · Seed data is loaded into the graph schema.
- Query maintainer → Analytics queries: maintains · Maintenance script updates query artifacts over time.
- API entrypoint → Graph client: uses · API entrypoint delegates graph access to the client wrapper.
- API entrypoint → Risk scorer: scores · API layer applies fraud scoring before returning responses.
- API entrypoint → API models: shapes · HTTP payloads are validated and serialized with API models.
- Graph client → Analytics queries: executes · Client wrapper sends graph queries to TigerGraph.
- Graph client → Graph schema: reads · Client operates against the graph-native entity model.
- Risk scorer → Analytics queries: interprets · Risk logic is informed by graph query results and motifs.
- App shell → Search bar: composes · App shell includes the search control.
- App shell → Graph view: composes · App shell includes the main graph visualization.
- App shell → Risk meter: composes · App shell includes the risk summary panel.
- App shell → Stats cards: composes · App shell includes metric summaries.
- App shell → Explanation panel: composes · App shell includes the explanation output panel.
- App shell → Header: composes · App shell includes top-level page chrome.
- Search bar → API entrypoint: queries · User searches trigger backend investigation requests.
- Graph view → API entrypoint: renders · Visualization consumes graph payloads returned by the API.
- Risk meter → API entrypoint: displays · Risk UI reflects backend scoring output.
- Stats cards → API entrypoint: displays · Stats UI reflects API-returned metrics.
- Explanation panel → API entrypoint: explains · Narrative panel shows backend reasoning and evidence.
