kirtan011/wexa-ai

Purpose and entry points

This is a Next.js App Router investigator tool for discovering financial-fraud rings in a Neo4j-compatible graph database. The primary UI entry points are the search/dashboard page at app/page.tsx, account investigation detail at app/account/[id]/page.tsx, and ring dashboard at app/rings/page.tsx. Root layout and global styling are defined in app/layout.tsx and app/globals.css.

Presentation and client data orchestration

Pages compose focused dashboard, account, and graph components while client hooks fetch API-backed data and manage loading/error states. The account detail view presents account metadata, risk, graph connections, and AI insight; the rings view summarizes detected clusters.

• hooks/useDashboard.ts

• hooks/useAccountAnalysis.ts

• components/NetworkGraph.tsx

• components/AccountInfoPanel.tsx

• components/InsightPanel.tsx

NetworkGraph.tsx is the browser-only visualization boundary for react-force-graph-2d; it must avoid server rendering because it depends on Canvas/browser APIs.

HTTP API boundary

Route handlers isolate UI code from database and analysis implementation. They expose account lookup, graph analysis, ring discovery, and search endpoints:

• app/api/account/[id]/route.ts

• app/api/analyze/[id]/route.ts

• app/api/rings/route.ts

• app/api/search/route.ts

The expected flow is client page/hook → /api/* route → query or analyzer service → typed response. This is the main trust boundary: browser clients do not send Cypher directly.

Graph persistence and deterministic investigation

CognoDB Cloud is accessed as a Neo4j-compatible Bolt/openCypher graph through the official neo4j-driver. The driver is a singleton/pool boundary; graph reads use parameterized Cypher and predictable success/error result shapes.

• lib/db.ts

• lib/queries.ts

• types/index.ts

The graph models Accounts linked to Devices, IP addresses, Phone Numbers, and Transactions. Core investigations traverse shared identity/infrastructure edges, find high-fan-out attributes, trace directed transaction chains, and retrieve account neighborhoods. Query depth and result limits bound potentially expensive graph exploration.

Analysis and explainability stage

The analysis endpoint obtains factual graph evidence through deterministic queries, then delegates pattern interpretation to the analyzer layer rather than allowing an LLM to query the database. This preserves the separation between data retrieval and narrative fraud explanation.

• lib/analyzer.ts

• app/api/analyze/[id]/route.ts

• components/InsightPanel.tsx

The AI-facing boundary should receive only structured, retrieved evidence. External AI service credentials/runtime details are not represented in the supplied tree, but the README identifies Gemini as the interpretation provider.

Ring discovery and investigator workflow

An investigator searches an account, opens its detail route, reviews direct account facts and a multi-hop connected network, then requests an evidence-based explanation. Separately, the rings dashboard surfaces clusters discovered from shared devices, IPs, or phone numbers.

• components/SearchBar.tsx

• app/account/[id]/page.tsx

• app/rings/page.tsx

• components/RingCard.tsx

Runtime, deployment, and data provisioning

The application runs on Node.js 18+ with Next.js, TypeScript, and Tailwind CSS; it is designed for Vercel deployment and requires CognoDB URI/user/password environment variables. Sample graph data—including synthetic hidden rings—is generated outside request handling by:

• scripts/seed.ts

• lib/db.ts