How luno141/tigergraph works
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: main.py API entrypoint · App.jsx App shell · queries_only.gsql Analytics queries · tigergraph_setup.gsql DB setup
Components 20
TigerGraph layer
Graph database schema, queries, and setup artifacts that hold the fraud investigation model and analytics.
- Graph schema · Core vertex and edge model centered on users, phones, bank accounts, devices, and transaction links.
schema_only.gsql - Analytics queries · Stored procedures for connection discovery, circular flow detection, and shared-asset analysis.
queries_only.gsql - Query bundle · Repository-level query definitions prepared for installation into TigerGraph.
tigergraph_queries.gsql - DB setup · Schema and query installation script for provisioning the graph database.
tigergraph_setup.gsql - Query patch · 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 · HTTP server entrypoint that exposes fraud investigation endpoints.
backend/main.py - API models · Request and response contracts for search, graph payloads, and risk outputs.
backend/models.py - Graph client · Database integration wrapper around TigerGraph REST queries and response normalization.
backend/tigergraph_client.py - Risk scorer · Graph-based scoring and severity logic derived from proximity, shared infrastructure, and motifs.
backend/risk_scorer.py - Data loader · 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 · Top-level frontend composition for the investigation workspace.
frontend/src/App.jsx - Search bar · Investigation input used to launch graph lookups and analyst queries.
frontend/src/components/SearchBar.jsx - Graph view · Interactive node-edge visualization for discovered fraud networks.
frontend/src/components/GraphView.jsx - Risk meter · Visualizes the backend risk score or severity signal for the current case.
frontend/src/components/RiskMeter.jsx - Stats cards · Displays key investigation counts and graph metrics returned by the backend.
frontend/src/components/StatsCards.jsx - Explanation panel · Shows human-readable reasoning and supporting signals for the investigation result.
frontend/src/components/ExplanationPanel.jsx - Header · 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 · Automates TigerGraph schema creation, query installation, and initial loading.
backend/setup_tigergraph.py - Setup v2 · Alternate or updated TigerGraph provisioning workflow.
backend/setup_tigergraph_v2.py - Query maintainer · Supports updating or patching graph queries independently from the app runtime.
backend/fix_queries.py
Connections 26
- 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.