# guy-gits/ringbreaker architecture

> Architecture diagram of the GitHub repository guy-gits/ringbreaker, 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/guy-gits/ringbreaker
- Repository: https://github.com/guy-gits/ringbreaker

## Overview

RingBreaker is a local P2P-payment fraud detection and analyst investigation product. The workflow is to score each payment before movement, combine pair, behavioral and coordination signals into an action, create evidence-rich alerts, then let analysts confirm or clear accounts; confirmations propagate risk. Analysts also replay the held-out stream and retrain from verified labels. The graph connects only relationships supported by excerpts, the SOURCE INDEX, or README; unsampled API and dashboard capabilities are represented without speculative internal call chains.

Main entry points: [`ringbreaker/engine/engine.py`](https://github.com/guy-gits/ringbreaker/blob/main/ringbreaker/engine/engine.py) (Scoring engine), [`dashboard/src/api/client.ts`](https://github.com/guy-gits/ringbreaker/blob/main/dashboard/src/api/client.ts) (API client), [`ringbreaker/api/main.py`](https://github.com/guy-gits/ringbreaker/blob/main/ringbreaker/api/main.py) (HTTP API), [`dashboard/src/App.tsx`](https://github.com/guy-gits/ringbreaker/blob/main/dashboard/src/App.tsx) (Dashboard routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data and features"]
  node_features["Online features<br/>[online.py]"]
  node_graphs["Transaction and identity graphs<br/>[build.py]"]
  node_simulator["Synthetic payment data<br/>[generate.py]"]
end

subgraph group_detect["Risk detection"]
  node_engine["Scoring engine<br/>[engine.py]"]
  node_patterns["Pattern detection"]
  node_risk["Risk fusion<br/>[risk.py]"]
  node_policy["Action policy<br/>[action.py]"]
end

subgraph group_investigate["Cases and network"]
  node_api["HTTP API<br/>[main.py]"]
  node_case["Case evidence<br/>[case_file.py]"]
  node_explain["Counterfactuals<br/>[counterfactual.py]"]
  node_stream["Stream replay<br/>[stream.py]"]
end

subgraph group_learn["Analyst learning"]
  node_retrain["Verified-label retraining<br/>[retrain.py]"]
end

subgraph group_console["Analyst console"]
  node_dashboard["Dashboard routes<br/>[App.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
  node_overview["Overview and stream controls<br/>[Overview.tsx]"]
  node_alerts["Alerts and investigation<br/>[Investigation.tsx]"]
  node_network_view["Network visualization<br/>[NetworkGraph.tsx]"]
  node_account_view["Account profiles<br/>[AccountDrawer.tsx]"]
  node_learning_view["Learning dashboard<br/>[Learning.tsx]"]
  node_api_types["API response types<br/>[types.ts]"]
end

node_analyst(("Analyst"))
node_payment["Payment input"]

node_payment -->|"scores before movement"| node_engine
node_engine -->|"computes features"| node_features
node_engine -->|"queries graph"| node_graphs
node_engine -->|"detects patterns"| node_patterns
node_engine -.->|"fuses signals"| node_risk
node_risk -->|"selects action"| node_policy
node_engine -->|"builds case evidence"| node_case
node_case -->|"queries evidence graph"| node_graphs
node_case -->|"requests counterfactual"| node_explain
node_api -->|"serves scoring"| node_engine
node_api -->|"controls replay"| node_stream
node_stream -.->|"replays payments"| node_engine
node_analyst -->|"reviews and acts"| node_dashboard
node_dashboard -->|"routes to"| node_overview
node_dashboard -->|"routes to"| node_alerts
node_dashboard -->|"routes to"| node_learning_view
node_overview -.->|"requests overview and stream"| node_api_client
node_alerts -->|"requests cases and verdicts"| node_api_client
node_alerts -->|"renders case graph"| node_network_view
node_account_view -->|"requests account data"| node_api_client
node_learning_view -->|"requests learning and retrain"| node_api_client
node_api_client -->|"calls API"| node_api
node_api_client -->|"types responses"| node_api_types
node_analyst -->|"confirms or clears"| node_api
node_api -.->|"initiates retraining"| node_retrain
node_retrain -->|"trains from features"| node_features
node_simulator -.->|"builds training features"| node_features

click node_api "https://github.com/guy-gits/ringbreaker/blob/main/ringbreaker/api/main.py"
click node_engine "https://github.com/guy-gits/ringbreaker/blob/main/ringbreaker/engine/engine.py"
click node_features "https://github.com/guy-gits/ringbreaker/blob/main/ringbreaker/features/online.py"
click node_graphs "https://github.com/guy-gits/ringbreaker/blob/main/ringbreaker/graphs/build.py"
click node_patterns "https://github.com/guy-gits/ringbreaker/tree/main/ringbreaker/patterns"
click node_risk "https://github.com/guy-gits/ringbreaker/blob/main/ringbreaker/engine/risk.py"
click node_policy "https://github.com/guy-gits/ringbreaker/blob/main/ringbreaker/scoring/action.py"
click node_case "https://github.com/guy-gits/ringbreaker/blob/main/ringbreaker/engine/case_file.py"
click node_explain "https://github.com/guy-gits/ringbreaker/blob/main/ringbreaker/explain/counterfactual.py"
click node_stream "https://github.com/guy-gits/ringbreaker/blob/main/ringbreaker/engine/stream.py"
click node_retrain "https://github.com/guy-gits/ringbreaker/blob/main/ringbreaker/learn/retrain.py"
click node_simulator "https://github.com/guy-gits/ringbreaker/blob/main/ringbreaker/simulator/generate.py"
click node_dashboard "https://github.com/guy-gits/ringbreaker/blob/main/dashboard/src/App.tsx"
click node_api_client "https://github.com/guy-gits/ringbreaker/blob/main/dashboard/src/api/client.ts"
click node_overview "https://github.com/guy-gits/ringbreaker/blob/main/dashboard/src/pages/Overview.tsx"
click node_alerts "https://github.com/guy-gits/ringbreaker/blob/main/dashboard/src/pages/Investigation.tsx"
click node_network_view "https://github.com/guy-gits/ringbreaker/blob/main/dashboard/src/components/graph/NetworkGraph.tsx"
click node_account_view "https://github.com/guy-gits/ringbreaker/blob/main/dashboard/src/components/account/AccountDrawer.tsx"
click node_learning_view "https://github.com/guy-gits/ringbreaker/blob/main/dashboard/src/pages/Learning.tsx"
click node_api_types "https://github.com/guy-gits/ringbreaker/blob/main/dashboard/src/api/types.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_features,node_graphs,node_simulator toneBlue
class node_engine,node_patterns,node_risk,node_policy toneAmber
class node_api,node_case,node_explain,node_stream toneMint
class node_retrain toneRose
class node_dashboard,node_api_client,node_overview,node_alerts,node_network_view,node_account_view,node_learning_view,node_api_types,node_analyst,node_payment toneIndigo
```

## Components

### Data and features

- [Online features](https://github.com/guy-gits/ringbreaker/blob/main/ringbreaker/features/online.py): `ringbreaker/features/online.py`
- [Transaction and identity graphs](https://github.com/guy-gits/ringbreaker/blob/main/ringbreaker/graphs/build.py): `ringbreaker/graphs/build.py`
- [Synthetic payment data](https://github.com/guy-gits/ringbreaker/blob/main/ringbreaker/simulator/generate.py): `ringbreaker/simulator/generate.py`

### Risk detection

- [Scoring engine](https://github.com/guy-gits/ringbreaker/blob/main/ringbreaker/engine/engine.py): `ringbreaker/engine/engine.py`
- [Pattern detection](https://github.com/guy-gits/ringbreaker/tree/main/ringbreaker/patterns): `ringbreaker/patterns`
- [Risk fusion](https://github.com/guy-gits/ringbreaker/blob/main/ringbreaker/engine/risk.py): `ringbreaker/engine/risk.py`
- [Action policy](https://github.com/guy-gits/ringbreaker/blob/main/ringbreaker/scoring/action.py): `ringbreaker/scoring/action.py`

### Cases and network

- [HTTP API](https://github.com/guy-gits/ringbreaker/blob/main/ringbreaker/api/main.py): `ringbreaker/api/main.py`
- [Case evidence](https://github.com/guy-gits/ringbreaker/blob/main/ringbreaker/engine/case_file.py): `ringbreaker/engine/case_file.py`
- [Counterfactuals](https://github.com/guy-gits/ringbreaker/blob/main/ringbreaker/explain/counterfactual.py): `ringbreaker/explain/counterfactual.py`
- [Stream replay](https://github.com/guy-gits/ringbreaker/blob/main/ringbreaker/engine/stream.py): `ringbreaker/engine/stream.py`

### Analyst learning

- [Verified-label retraining](https://github.com/guy-gits/ringbreaker/blob/main/ringbreaker/learn/retrain.py): `ringbreaker/learn/retrain.py`

### Analyst console

- [Dashboard routes](https://github.com/guy-gits/ringbreaker/blob/main/dashboard/src/App.tsx): `dashboard/src/App.tsx`
- [API client](https://github.com/guy-gits/ringbreaker/blob/main/dashboard/src/api/client.ts): `dashboard/src/api/client.ts`
- [Overview and stream controls](https://github.com/guy-gits/ringbreaker/blob/main/dashboard/src/pages/Overview.tsx): `dashboard/src/pages/Overview.tsx`
- [Alerts and investigation](https://github.com/guy-gits/ringbreaker/blob/main/dashboard/src/pages/Investigation.tsx): `dashboard/src/pages/Investigation.tsx`
- [Network visualization](https://github.com/guy-gits/ringbreaker/blob/main/dashboard/src/components/graph/NetworkGraph.tsx): `dashboard/src/components/graph/NetworkGraph.tsx`
- [Account profiles](https://github.com/guy-gits/ringbreaker/blob/main/dashboard/src/components/account/AccountDrawer.tsx): `dashboard/src/components/account/AccountDrawer.tsx`
- [Learning dashboard](https://github.com/guy-gits/ringbreaker/blob/main/dashboard/src/pages/Learning.tsx): `dashboard/src/pages/Learning.tsx`
- [API response types](https://github.com/guy-gits/ringbreaker/blob/main/dashboard/src/api/types.ts): `dashboard/src/api/types.ts`

### Other components

- **Analyst**
- **Payment input**

## Connections

- Payment input → Scoring engine: scores before movement (evidence: `ringbreaker/engine/engine.py`)
- Scoring engine → Online features: computes features (evidence: `ringbreaker/engine/engine.py`)
- Scoring engine → Transaction and identity graphs: queries graph (evidence: `ringbreaker/engine/engine.py`)
- Scoring engine → Pattern detection: detects patterns (evidence: `ringbreaker/engine/engine.py`)
- Scoring engine → Risk fusion: fuses signals (evidence: `ringbreaker/engine/engine.py`)
- Risk fusion → Action policy: selects action (evidence: `ringbreaker/engine/risk.py`)
- Scoring engine → Case evidence: builds case evidence (evidence: `ringbreaker/engine/engine.py`)
- Case evidence → Transaction and identity graphs: queries evidence graph (evidence: `ringbreaker/engine/case_file.py`)
- Case evidence → Counterfactuals: requests counterfactual (evidence: `ringbreaker/engine/case_file.py`)
- HTTP API → Scoring engine: serves scoring (evidence: `ringbreaker/api/main.py`)
- HTTP API → Stream replay: controls replay (evidence: `ringbreaker/api/main.py`)
- Stream replay → Scoring engine: replays payments
- Analyst → Dashboard routes: reviews and acts (evidence: `README.md`)
- Dashboard routes → Overview and stream controls: routes to (evidence: `dashboard/src/App.tsx`)
- Dashboard routes → Alerts and investigation: routes to (evidence: `dashboard/src/App.tsx`)
- Dashboard routes → Learning dashboard: routes to (evidence: `dashboard/src/App.tsx`)
- Overview and stream controls → API client: requests overview and stream
- Alerts and investigation → API client: requests cases and verdicts (evidence: `dashboard/src/pages/Investigation.tsx`)
- Alerts and investigation → Network visualization: renders case graph (evidence: `dashboard/src/pages/Investigation.tsx`)
- Account profiles → API client: requests account data (evidence: `dashboard/src/components/account/AccountDrawer.tsx`)
- Learning dashboard → API client: requests learning and retrain (evidence: `dashboard/src/pages/Learning.tsx`)
- API client → HTTP API: calls API (evidence: `dashboard/src/api/client.ts`)
- API client → API response types: types responses (evidence: `dashboard/src/api/client.ts`)
- Analyst → HTTP API: confirms or clears (evidence: `README.md`)
- HTTP API → Verified-label retraining: initiates retraining
- Verified-label retraining → Online features: trains from features (evidence: `ringbreaker/learn/retrain.py`)
- Synthetic payment data → Online features: builds training features