# concurrents-org/ledgerzero architecture

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

- Interactive diagram: https://gitdiagram.com/concurrents-org/ledgerzero
- Repository: https://github.com/concurrents-org/ledgerzero

## Overview

LedgerZero is a UPI-style payment and fraud-analysis platform. The user journey runs from authentication and onboarding through account access, payment initiation, transaction routing and bank processing; fraud scoring and graph-based investigation add risk decisions and forensic reports. The sampled frontend and Python backend show API access, graph retrieval, Gemini-backed analysis, and graph synchronization. The README documents Java payment services and broader features, but those service sources are absent from this tree, so their links are documentation-based rather than source-verified.

Main entry points: [`website/src/services/api.ts`](https://github.com/concurrents-org/ledgerzero/blob/main/website/src/services/api.ts) (API Client), [`Python Backend/app.py`](https://github.com/concurrents-org/ledgerzero/blob/main/Python%20Backend/app.py) (Fraud API), [`Python Backend/DB Poller/graph_sync_service.py`](https://github.com/concurrents-org/ledgerzero/blob/main/Python%20Backend/DB%20Poller/graph_sync_service.py) (Graph Sync), [`Python Backend/graph_rag.py`](https://github.com/concurrents-org/ledgerzero/blob/main/Python%20Backend/graph_rag.py) (Forensic GraphRAG)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Payment Client"]
  node_auth["Authentication<br/>[AuthPage.tsx]"]
  node_onboarding["Onboarding<br/>[OnboardingPage.tsx]"]
  node_account["Account Views<br/>[useAccountData.ts]"]
  node_send["Send Payment<br/>[SendMoneyPage.tsx]"]
  node_transactions["Transaction History"]
  node_api["API Client<br/>[api.ts]"]
  node_state[("Client State<br/>[index.ts]")]
  node_notifications["Live Notifications"]
end

subgraph group_payments["Payment Services"]
  node_gateway["Gateway Service"]
  node_switch["Transaction Switch"]
  node_bank["Bank Service"]
end

subgraph group_fraud["Fraud Analysis"]
  node_fraud_api["Fraud API<br/>[app.py]"]
  node_sync["Graph Sync"]
  node_rag["Forensic GraphRAG<br/>[graph_rag.py]"]
  node_gnn["GNN Risk Detection"]
end

subgraph group_data["Data Stores"]
  node_neo4j[("Neo4j Graph")]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis")]
end

node_user(("Payment User"))
node_gemini["Google Gemini"]

node_user -->|"authenticates"| node_auth
node_user -->|"sets up account"| node_onboarding
node_user -->|"initiates payment"| node_send
node_auth -->|"calls"| node_api
node_onboarding -->|"calls"| node_api
node_send -->|"calls"| node_api
node_account -->|"fetches data"| node_api
node_account -->|"updates"| node_state
node_transactions -->|"fetches history"| node_api
node_api -.->|"sends requests"| node_gateway
node_gateway -.->|"routes payments"| node_switch
node_switch -.->|"requests processing"| node_bank
node_gateway -.->|"streams events"| node_fraud_api
node_switch -.->|"requests risk score"| node_fraud_api
node_fraud_api -->|"initializes engine"| node_rag
node_fraud_api -.->|"runs synchronization"| node_sync
node_sync -->|"reads transactions"| node_postgres
node_sync -.->|"syncs graph"| node_neo4j
node_sync -->|"stores sync state"| node_redis
node_rag -->|"retrieves ego graph"| node_neo4j
node_rag -->|"generates report"| node_gemini
node_fraud_api -.->|"scores transactions"| node_gnn
node_user -->|"views history"| node_transactions
node_gateway -.->|"publishes alerts"| node_notifications
node_notifications -->|"updates balance"| node_state

click node_auth "https://github.com/concurrents-org/ledgerzero/blob/main/website/src/pages/auth/AuthPage.tsx"
click node_onboarding "https://github.com/concurrents-org/ledgerzero/blob/main/website/src/pages/onboarding/OnboardingPage.tsx"
click node_account "https://github.com/concurrents-org/ledgerzero/blob/main/website/src/hooks/useAccountData.ts"
click node_send "https://github.com/concurrents-org/ledgerzero/blob/main/website/src/pages/send/SendMoneyPage.tsx"
click node_transactions "https://github.com/concurrents-org/ledgerzero/blob/main/website/src/pages/transactions/TransactionsPage.tsx"
click node_api "https://github.com/concurrents-org/ledgerzero/blob/main/website/src/services/api.ts"
click node_state "https://github.com/concurrents-org/ledgerzero/blob/main/website/src/store/index.ts"
click node_notifications "https://github.com/concurrents-org/ledgerzero/blob/main/website/src/hooks/usePaymentNotifications.ts"
click node_fraud_api "https://github.com/concurrents-org/ledgerzero/blob/main/Python%20Backend/app.py"
click node_sync "https://github.com/concurrents-org/ledgerzero/blob/main/Python%20Backend/DB%20Poller/graph_sync_service.py"
click node_rag "https://github.com/concurrents-org/ledgerzero/blob/main/Python%20Backend/graph_rag.py"
click node_gnn "https://github.com/concurrents-org/ledgerzero/tree/main/Python%20Backend"

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_auth,node_onboarding,node_account,node_send,node_transactions,node_api,node_state,node_notifications,node_user toneBlue
class node_gateway,node_switch,node_bank toneAmber
class node_fraud_api,node_sync,node_rag,node_gnn toneMint
class node_neo4j,node_postgres,node_redis toneRose
class node_gemini toneIndigo
```

## Components

### Payment Client

- [Authentication](https://github.com/concurrents-org/ledgerzero/blob/main/website/src/pages/auth/AuthPage.tsx): `website/src/pages/auth/AuthPage.tsx`
- [Onboarding](https://github.com/concurrents-org/ledgerzero/blob/main/website/src/pages/onboarding/OnboardingPage.tsx): `website/src/pages/onboarding/OnboardingPage.tsx`
- [Account Views](https://github.com/concurrents-org/ledgerzero/blob/main/website/src/hooks/useAccountData.ts): `website/src/hooks/useAccountData.ts`
- [Send Payment](https://github.com/concurrents-org/ledgerzero/blob/main/website/src/pages/send/SendMoneyPage.tsx): `website/src/pages/send/SendMoneyPage.tsx`
- [Transaction History](https://github.com/concurrents-org/ledgerzero/blob/main/website/src/pages/transactions/TransactionsPage.tsx): `website/src/pages/transactions/TransactionsPage.tsx`
- [API Client](https://github.com/concurrents-org/ledgerzero/blob/main/website/src/services/api.ts): `website/src/services/api.ts`
- [Client State](https://github.com/concurrents-org/ledgerzero/blob/main/website/src/store/index.ts): `website/src/store/index.ts`
- [Live Notifications](https://github.com/concurrents-org/ledgerzero/blob/main/website/src/hooks/usePaymentNotifications.ts): `website/src/hooks/usePaymentNotifications.ts`

### Payment Services

- **Gateway Service**
- **Transaction Switch**
- **Bank Service**

### Fraud Analysis

- [Fraud API](https://github.com/concurrents-org/ledgerzero/blob/main/Python%20Backend/app.py): `Python Backend/app.py`
- [Graph Sync](https://github.com/concurrents-org/ledgerzero/blob/main/Python%20Backend/DB%20Poller/graph_sync_service.py): `Python Backend/DB Poller/graph_sync_service.py`
- [Forensic GraphRAG](https://github.com/concurrents-org/ledgerzero/blob/main/Python%20Backend/graph_rag.py): `Python Backend/graph_rag.py`
- [GNN Risk Detection](https://github.com/concurrents-org/ledgerzero/tree/main/Python%20Backend): `Python Backend`

### Data Stores

- **Neo4j Graph**
- **PostgreSQL**
- **Redis**

### Other components

- **Payment User**
- **Google Gemini**

## Connections

- Payment User → Authentication: authenticates
- Payment User → Onboarding: sets up account
- Payment User → Send Payment: initiates payment
- Authentication → API Client: calls (evidence: `website/src/pages/auth/AuthPage.tsx`)
- Onboarding → API Client: calls (evidence: `website/src/pages/onboarding/OnboardingPage.tsx`)
- Send Payment → API Client: calls (evidence: `website/src/pages/send/SendMoneyPage.tsx`)
- Account Views → API Client: fetches data (evidence: `website/src/hooks/useAccountData.ts`)
- Account Views → Client State: updates (evidence: `website/src/hooks/useAccountData.ts`)
- Transaction History → API Client: fetches history (evidence: `website/src/pages/transactions/TransactionsPage.tsx`)
- API Client → Gateway Service: sends requests
- Gateway Service → Transaction Switch: routes payments
- Transaction Switch → Bank Service: requests processing
- Gateway Service → Fraud API: streams events
- Transaction Switch → Fraud API: requests risk score
- Fraud API → Forensic GraphRAG: initializes engine (evidence: `Python Backend/app.py`)
- Fraud API → Graph Sync: runs synchronization
- Graph Sync → PostgreSQL: reads transactions (evidence: `Python Backend/DB Poller/graph_sync_service.py`)
- Graph Sync → Neo4j Graph: syncs graph
- Graph Sync → Redis: stores sync state (evidence: `Python Backend/DB Poller/graph_sync_service.py`)
- Forensic GraphRAG → Neo4j Graph: retrieves ego graph (evidence: `Python Backend/graph_rag.py`)
- Forensic GraphRAG → Google Gemini: generates report (evidence: `Python Backend/graph_rag.py`)
- Fraud API → GNN Risk Detection: scores transactions (evidence: `Python Backend/app.py`)
- Payment User → Transaction History: views history
- Gateway Service → Live Notifications: publishes alerts
- Live Notifications → Client State: updates balance (evidence: `website/src/hooks/usePaymentNotifications.ts`)