# kirtan011/wexa-ai architecture

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

- Interactive diagram: https://gitdiagram.com/kirtan011/wexa-ai
- Repository: https://github.com/kirtan011/wexa-ai

## Overview

#### 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`

Main entry points: [`lib/queries.ts`](https://github.com/kirtan011/wexa-ai/blob/master/lib/queries.ts) (Graph queries), [`app/account/[id]/page.tsx`](https://github.com/kirtan011/wexa-ai/blob/master/app/account/%5Bid%5D/page.tsx) (Account investigation), [`app/page.tsx`](https://github.com/kirtan011/wexa-ai/blob/master/app/page.tsx) (Search dashboard), [`hooks/useDashboard.ts`](https://github.com/kirtan011/wexa-ai/blob/master/hooks/useDashboard.ts) (Dashboard data hook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Investigator UI"]
  node_root_layout["Root layout<br/>Next.js layout<br/>[layout.tsx]"]
  node_dashboard["Search dashboard<br/>App Router page<br/>[page.tsx]"]
  node_account_page["Account investigation<br/>App Router page<br/>[page.tsx]"]
  node_rings_page["Ring dashboard<br/>App Router page<br/>[page.tsx]"]
  node_dashboard_hook["Dashboard data hook<br/>client hook<br/>[useDashboard.ts]"]
  node_account_hook["Account analysis hook<br/>client hook"]
  node_search_bar["Search bar<br/>UI component<br/>[SearchBar.tsx]"]
  node_network_graph["Network graph<br/>browser-only visualization<br/>[NetworkGraph.tsx]"]
  node_account_panel["Account info panel<br/>UI component"]
  node_insight_panel["Insight panel<br/>UI component<br/>[InsightPanel.tsx]"]
  node_ring_card["Ring card<br/>UI component<br/>[RingCard.tsx]"]
end

subgraph group_api["HTTP API"]
  node_account_api{{"Account lookup API<br/>route handler<br/>[route.ts]"}}
  node_analyze_api{{"Analysis API<br/>route handler<br/>[route.ts]"}}
  node_rings_api{{"Ring discovery API<br/>route handler<br/>[route.ts]"}}
  node_search_api{{"Search API<br/>route handler<br/>[route.ts]"}}
end

subgraph group_investigation["Investigation Services"]
  node_queries["Graph queries<br/>Cypher query layer<br/>[queries.ts]"]
  node_analyzer["Evidence analyzer<br/>analysis service<br/>[analyzer.ts]"]
  node_db_driver[("Neo4j driver singleton<br/>database boundary<br/>[db.ts]")]
  node_seed["Synthetic graph seed<br/>data provisioning script<br/>[seed.ts]"]
end

subgraph group_external["Data and AI"]
  node_graph_db[("CognoDB Cloud<br/>Neo4j-compatible graph")]
  node_gemini["Gemini<br/>AI interpretation provider"]
end

node_root_layout -->|"wraps"| node_dashboard
node_dashboard -->|"composes"| node_search_bar
node_dashboard -->|"loads data"| node_dashboard_hook
node_account_page -->|"loads investigation"| node_account_hook
node_account_page -->|"renders facts"| node_account_panel
node_account_page -->|"renders network"| node_network_graph
node_account_page -->|"renders explanation"| node_insight_panel
node_rings_page -->|"renders clusters"| node_ring_card
node_dashboard_hook -->|"searches"| node_search_api
node_dashboard_hook -->|"loads rings"| node_rings_api
node_account_hook -->|"loads account and network"| node_account_api
node_account_hook -->|"requests explanation"| node_analyze_api
node_account_api -->|"retrieves evidence"| node_queries
node_search_api -->|"searches accounts"| node_queries
node_rings_api -->|"finds shared-attribute clusters"| node_queries
node_analyze_api -->|"retrieves factual evidence"| node_queries
node_analyze_api -->|"interprets evidence"| node_analyzer
node_queries -->|"executes Cypher"| node_db_driver
node_db_driver -->|"Bolt/openCypher"| node_graph_db
node_analyzer -->|"structured evidence"| node_gemini
node_seed -->|"provisions graph"| node_db_driver

click node_root_layout "https://github.com/kirtan011/wexa-ai/blob/master/app/layout.tsx"
click node_dashboard "https://github.com/kirtan011/wexa-ai/blob/master/app/page.tsx"
click node_account_page "https://github.com/kirtan011/wexa-ai/blob/master/app/account/%5Bid%5D/page.tsx"
click node_rings_page "https://github.com/kirtan011/wexa-ai/blob/master/app/rings/page.tsx"
click node_dashboard_hook "https://github.com/kirtan011/wexa-ai/blob/master/hooks/useDashboard.ts"
click node_account_hook "https://github.com/kirtan011/wexa-ai/blob/master/hooks/useAccountAnalysis.ts"
click node_search_bar "https://github.com/kirtan011/wexa-ai/blob/master/components/SearchBar.tsx"
click node_network_graph "https://github.com/kirtan011/wexa-ai/blob/master/components/NetworkGraph.tsx"
click node_account_panel "https://github.com/kirtan011/wexa-ai/blob/master/components/AccountInfoPanel.tsx"
click node_insight_panel "https://github.com/kirtan011/wexa-ai/blob/master/components/InsightPanel.tsx"
click node_ring_card "https://github.com/kirtan011/wexa-ai/blob/master/components/RingCard.tsx"
click node_account_api "https://github.com/kirtan011/wexa-ai/blob/master/app/api/account/%5Bid%5D/route.ts"
click node_analyze_api "https://github.com/kirtan011/wexa-ai/blob/master/app/api/analyze/%5Bid%5D/route.ts"
click node_rings_api "https://github.com/kirtan011/wexa-ai/blob/master/app/api/rings/route.ts"
click node_search_api "https://github.com/kirtan011/wexa-ai/blob/master/app/api/search/route.ts"
click node_queries "https://github.com/kirtan011/wexa-ai/blob/master/lib/queries.ts"
click node_analyzer "https://github.com/kirtan011/wexa-ai/blob/master/lib/analyzer.ts"
click node_db_driver "https://github.com/kirtan011/wexa-ai/blob/master/lib/db.ts"
click node_seed "https://github.com/kirtan011/wexa-ai/blob/master/scripts/seed.ts"

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_root_layout,node_dashboard,node_account_page,node_rings_page,node_dashboard_hook,node_account_hook,node_search_bar,node_network_graph,node_account_panel,node_insight_panel,node_ring_card toneBlue
class node_account_api,node_analyze_api,node_rings_api,node_search_api toneAmber
class node_queries,node_analyzer,node_db_driver,node_seed toneMint
class node_graph_db,node_gemini toneRose
```

## Components

### Investigator UI

- [Root layout](https://github.com/kirtan011/wexa-ai/blob/master/app/layout.tsx): Next.js layout · `app/layout.tsx`
- [Search dashboard](https://github.com/kirtan011/wexa-ai/blob/master/app/page.tsx): App Router page · `app/page.tsx`
- [Account investigation](https://github.com/kirtan011/wexa-ai/blob/master/app/account/%5Bid%5D/page.tsx): App Router page · Shows account facts, network evidence, and AI insight. · `app/account/[id]/page.tsx`
- [Ring dashboard](https://github.com/kirtan011/wexa-ai/blob/master/app/rings/page.tsx): App Router page · `app/rings/page.tsx`
- [Dashboard data hook](https://github.com/kirtan011/wexa-ai/blob/master/hooks/useDashboard.ts): client hook · `hooks/useDashboard.ts`
- [Account analysis hook](https://github.com/kirtan011/wexa-ai/blob/master/hooks/useAccountAnalysis.ts): client hook · `hooks/useAccountAnalysis.ts`
- [Search bar](https://github.com/kirtan011/wexa-ai/blob/master/components/SearchBar.tsx): UI component · `components/SearchBar.tsx`
- [Network graph](https://github.com/kirtan011/wexa-ai/blob/master/components/NetworkGraph.tsx): browser-only visualization · Canvas-based react-force-graph view excluded from server rendering. · `components/NetworkGraph.tsx`
- [Account info panel](https://github.com/kirtan011/wexa-ai/blob/master/components/AccountInfoPanel.tsx): UI component · `components/AccountInfoPanel.tsx`
- [Insight panel](https://github.com/kirtan011/wexa-ai/blob/master/components/InsightPanel.tsx): UI component · `components/InsightPanel.tsx`
- [Ring card](https://github.com/kirtan011/wexa-ai/blob/master/components/RingCard.tsx): UI component · `components/RingCard.tsx`

### HTTP API

Browser clients access graph data only through route handlers.

- [Account lookup API](https://github.com/kirtan011/wexa-ai/blob/master/app/api/account/%5Bid%5D/route.ts): route handler · `app/api/account/[id]/route.ts`
- [Analysis API](https://github.com/kirtan011/wexa-ai/blob/master/app/api/analyze/%5Bid%5D/route.ts): route handler · Retrieves evidence before requesting interpretation. · `app/api/analyze/[id]/route.ts`
- [Ring discovery API](https://github.com/kirtan011/wexa-ai/blob/master/app/api/rings/route.ts): route handler · `app/api/rings/route.ts`
- [Search API](https://github.com/kirtan011/wexa-ai/blob/master/app/api/search/route.ts): route handler · `app/api/search/route.ts`

### Investigation Services

- [Graph queries](https://github.com/kirtan011/wexa-ai/blob/master/lib/queries.ts): Cypher query layer · Parameterized, bounded traversals for neighborhoods, chains, and shared attributes. · `lib/queries.ts`
- [Evidence analyzer](https://github.com/kirtan011/wexa-ai/blob/master/lib/analyzer.ts): analysis service · Converts structured graph evidence into fraud-pattern interpretation. · `lib/analyzer.ts`
- [Neo4j driver singleton](https://github.com/kirtan011/wexa-ai/blob/master/lib/db.ts): database boundary · Pooled Bolt/openCypher connection boundary. · `lib/db.ts`
- [Synthetic graph seed](https://github.com/kirtan011/wexa-ai/blob/master/scripts/seed.ts): data provisioning script · Generates sample data and hidden fraud rings outside request handling. · `scripts/seed.ts`

### Data and AI

- **CognoDB Cloud**: Neo4j-compatible graph · Accounts connect to devices, IPs, phones, and transactions.
- **Gemini**: AI interpretation provider · Receives retrieved structured evidence, not database access.

## Connections

- Root layout → Search dashboard: wraps
- Search dashboard → Search bar: composes
- Search dashboard → Dashboard data hook: loads data
- Account investigation → Account analysis hook: loads investigation
- Account investigation → Account info panel: renders facts
- Account investigation → Network graph: renders network
- Account investigation → Insight panel: renders explanation
- Ring dashboard → Ring card: renders clusters
- Dashboard data hook → Search API: searches
- Dashboard data hook → Ring discovery API: loads rings
- Account analysis hook → Account lookup API: loads account and network
- Account analysis hook → Analysis API: requests explanation
- Account lookup API → Graph queries: retrieves evidence
- Search API → Graph queries: searches accounts
- Ring discovery API → Graph queries: finds shared-attribute clusters
- Analysis API → Graph queries: retrieves factual evidence
- Analysis API → Evidence analyzer: interprets evidence
- Graph queries → Neo4j driver singleton: executes Cypher
- Neo4j driver singleton → CognoDB Cloud: Bolt/openCypher
- Evidence analyzer → Gemini: structured evidence
- Synthetic graph seed → Neo4j driver singleton: provisions graph