# karthikeyan-s-developer/fraud-risk-engine architecture

> Architecture diagram of the GitHub repository karthikeyan-s-developer/fraud-risk-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/karthikeyan-s-developer/fraud-risk-engine
- Repository: https://github.com/karthikeyan-s-developer/fraud-risk-engine

## Overview

Acentra Aegis detects location-aware financial fraud and gives investigators an explainable review cockpit. Its main workflow accepts transaction events through the API, evaluates deterministic rules using transaction history and entity relationships, adds an auxiliary ML signal, persists flags and alerts on high risk, then supports dashboard monitoring and human review. The README also describes mobility analysis, audit history, live simulation, and geospatial/entity-graph investigations. Some backend wiring is only partially excerpted; edges rely on shown references or explicit README statements, and unsampled details are not inferred.

Main entry points: [`backend/main.py`](https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/backend/main.py) (Transaction API), [`frontend/src/pages/FlagDetail.jsx`](https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/frontend/src/pages/FlagDetail.jsx) (Flag Investigation), [`frontend/src/App.jsx`](https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/frontend/src/App.jsx) (Cockpit App), [`frontend/src/config.js`](https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/frontend/src/config.js) (API Configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Ingestion and API"]
  node_api["Transaction API<br/>[main.py]"]
  node_schemas["API Schemas<br/>[schemas.py]"]
  node_simulator["Transaction Simulator<br/>[simulator.py]"]
end

subgraph group_detection["Fraud Detection"]
  node_engine["Rule Engine<br/>[engine.py]"]
  node_rules["Deterministic Rules"]
  node_base["Rule Contract<br/>[base.py]"]
  node_entitygraph["Entity Graph<br/>[graph.py]"]
  node_mobility["Mobility Analysis<br/>[mobility.py]"]
  node_ml["ML Risk Signal<br/>[pipeline.py]"]
  node_explainer["SHAP Explainer<br/>[explainer.py]"]
end

subgraph group_operations["Persistence and Alerts"]
  node_models["Fraud Data Models<br/>[models.py]"]
  node_db["Database Access<br/>[db.py]"]
  node_postgres[("Neon PostgreSQL")]
  node_notifier["Alert Notifier<br/>[notifier.py]"]
  node_sns["AWS SNS / SES"]
end

subgraph group_cockpit["Reviewer Cockpit"]
  node_app["Cockpit App<br/>[App.jsx]"]
  node_dashboard["Dashboard<br/>[Dashboard.jsx]"]
  node_flaglist["Flag Queue<br/>[FlagList.jsx]"]
  node_flagdetail["Flag Investigation<br/>[FlagDetail.jsx]"]
  node_audit["Audit Log<br/>[AuditLog.jsx]"]
  node_action["Review Actions<br/>[ActionPanel.jsx]"]
  node_map["Geo Investigation Map"]
  node_entityview["Entity Graph View"]
  node_breakdown["Rule Breakdown"]
  node_apiurl["API Configuration<br/>[config.js]"]
end

node_event(("Financial Event"))
node_reviewer(("Investigator"))

node_event -->|"submits"| node_api
node_simulator -.->|"submits events"| node_api
node_api -->|"validates with"| node_schemas
node_api -->|"evaluates with"| node_engine
node_engine -->|"discovers and runs"| node_rules
node_rules -->|"implement contract"| node_base
node_api -->|"uses graph"| node_entitygraph
node_api -->|"uses mobility"| node_mobility
node_api -->|"scores transaction"| node_ml
node_explainer -.->|"explains signals"| node_ml
node_api -->|"reads and writes"| node_models
node_models -->|"uses database"| node_db
node_db -->|"connects to"| node_postgres
node_api -->|"dispatches alerts"| node_notifier
node_notifier -->|"publishes alerts"| node_sns
node_reviewer -->|"uses cockpit"| node_app
node_app -->|"renders"| node_dashboard
node_app -->|"renders"| node_flaglist
node_app -->|"renders"| node_flagdetail
node_app -->|"renders"| node_audit
node_dashboard -->|"configures requests"| node_apiurl
node_flaglist -->|"configures requests"| node_apiurl
node_flagdetail -->|"configures requests"| node_apiurl
node_audit -->|"configures requests"| node_apiurl
node_dashboard -->|"opens live stream"| node_api
node_flagdetail -->|"renders"| node_action
node_flagdetail -->|"renders"| node_map
node_flagdetail -->|"renders"| node_entityview
node_flagdetail -->|"renders"| node_breakdown
node_action -->|"configures requests"| node_apiurl

click node_api "https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/backend/main.py"
click node_schemas "https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/backend/schemas.py"
click node_simulator "https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/backend/simulator/simulator.py"
click node_engine "https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/backend/engine/engine.py"
click node_rules "https://github.com/karthikeyan-s-developer/fraud-risk-engine/tree/main/backend/rules"
click node_base "https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/backend/engine/base.py"
click node_entitygraph "https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/backend/engine/graph.py"
click node_mobility "https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/backend/engine/mobility.py"
click node_ml "https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/backend/ml/pipeline.py"
click node_explainer "https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/backend/ml/explainer.py"
click node_models "https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/backend/models.py"
click node_db "https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/backend/db.py"
click node_notifier "https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/backend/services/notifier.py"
click node_app "https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/frontend/src/App.jsx"
click node_dashboard "https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/frontend/src/pages/Dashboard.jsx"
click node_flaglist "https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/frontend/src/pages/FlagList.jsx"
click node_flagdetail "https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/frontend/src/pages/FlagDetail.jsx"
click node_audit "https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/frontend/src/pages/AuditLog.jsx"
click node_action "https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/frontend/src/components/ActionPanel.jsx"
click node_map "https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/frontend/src/components/GeoInvestigationMap.jsx"
click node_entityview "https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/frontend/src/components/EntityGraphView.jsx"
click node_breakdown "https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/frontend/src/components/RuleBreakdownCard.jsx"
click node_apiurl "https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/frontend/src/config.js"

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_api,node_schemas,node_simulator toneBlue
class node_engine,node_rules,node_base,node_entitygraph,node_mobility,node_ml,node_explainer toneAmber
class node_models,node_db,node_postgres,node_notifier,node_sns toneMint
class node_app,node_dashboard,node_flaglist,node_flagdetail,node_audit,node_action,node_map,node_entityview,node_breakdown,node_apiurl toneRose
class node_event,node_reviewer toneIndigo
```

## Components

### Ingestion and API

- [Transaction API](https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/backend/main.py): `backend/main.py`
- [API Schemas](https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/backend/schemas.py): `backend/schemas.py`
- [Transaction Simulator](https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/backend/simulator/simulator.py): `backend/simulator/simulator.py`

### Fraud Detection

- [Rule Engine](https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/backend/engine/engine.py): `backend/engine/engine.py`
- [Deterministic Rules](https://github.com/karthikeyan-s-developer/fraud-risk-engine/tree/main/backend/rules): `backend/rules`
- [Rule Contract](https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/backend/engine/base.py): `backend/engine/base.py`
- [Entity Graph](https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/backend/engine/graph.py): `backend/engine/graph.py`
- [Mobility Analysis](https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/backend/engine/mobility.py): `backend/engine/mobility.py`
- [ML Risk Signal](https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/backend/ml/pipeline.py): `backend/ml/pipeline.py`
- [SHAP Explainer](https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/backend/ml/explainer.py): `backend/ml/explainer.py`

### Persistence and Alerts

- [Fraud Data Models](https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/backend/models.py): `backend/models.py`
- [Database Access](https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/backend/db.py): `backend/db.py`
- **Neon PostgreSQL**
- [Alert Notifier](https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/backend/services/notifier.py): `backend/services/notifier.py`
- **AWS SNS / SES**

### Reviewer Cockpit

- [Cockpit App](https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Dashboard](https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Flag Queue](https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/frontend/src/pages/FlagList.jsx): `frontend/src/pages/FlagList.jsx`
- [Flag Investigation](https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/frontend/src/pages/FlagDetail.jsx): `frontend/src/pages/FlagDetail.jsx`
- [Audit Log](https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/frontend/src/pages/AuditLog.jsx): `frontend/src/pages/AuditLog.jsx`
- [Review Actions](https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/frontend/src/components/ActionPanel.jsx): `frontend/src/components/ActionPanel.jsx`
- [Geo Investigation Map](https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/frontend/src/components/GeoInvestigationMap.jsx): `frontend/src/components/GeoInvestigationMap.jsx`
- [Entity Graph View](https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/frontend/src/components/EntityGraphView.jsx): `frontend/src/components/EntityGraphView.jsx`
- [Rule Breakdown](https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/frontend/src/components/RuleBreakdownCard.jsx): `frontend/src/components/RuleBreakdownCard.jsx`
- [API Configuration](https://github.com/karthikeyan-s-developer/fraud-risk-engine/blob/main/frontend/src/config.js): `frontend/src/config.js`

### Other components

- **Financial Event**
- **Investigator**

## Connections

- Financial Event → Transaction API: submits (evidence: `README.md`)
- Transaction Simulator → Transaction API: submits events (evidence: `backend/main.py`)
- Transaction API → API Schemas: validates with (evidence: `backend/main.py`)
- Transaction API → Rule Engine: evaluates with (evidence: `backend/main.py`)
- Rule Engine → Deterministic Rules: discovers and runs (evidence: `backend/engine/engine.py`)
- Deterministic Rules → Rule Contract: implement contract (evidence: `backend/rules/amount.py`)
- Transaction API → Entity Graph: uses graph (evidence: `backend/main.py`)
- Transaction API → Mobility Analysis: uses mobility (evidence: `backend/main.py`)
- Transaction API → ML Risk Signal: scores transaction (evidence: `backend/main.py`)
- SHAP Explainer → ML Risk Signal: explains signals (evidence: `backend/ml/explainer.py`)
- Transaction API → Fraud Data Models: reads and writes (evidence: `backend/main.py`)
- Fraud Data Models → Database Access: uses database (evidence: `backend/models.py`)
- Database Access → Neon PostgreSQL: connects to (evidence: `README.md`)
- Transaction API → Alert Notifier: dispatches alerts (evidence: `README.md`)
- Alert Notifier → AWS SNS / SES: publishes alerts (evidence: `backend/services/notifier.py`)
- Investigator → Cockpit App: uses cockpit (evidence: `README.md`)
- Cockpit App → Dashboard: renders (evidence: `frontend/src/App.jsx`)
- Cockpit App → Flag Queue: renders (evidence: `frontend/src/App.jsx`)
- Cockpit App → Flag Investigation: renders (evidence: `frontend/src/App.jsx`)
- Cockpit App → Audit Log: renders (evidence: `frontend/src/App.jsx`)
- Dashboard → API Configuration: configures requests (evidence: `frontend/src/pages/Dashboard.jsx`)
- Flag Queue → API Configuration: configures requests (evidence: `frontend/src/pages/FlagList.jsx`)
- Flag Investigation → API Configuration: configures requests (evidence: `frontend/src/pages/FlagDetail.jsx`)
- Audit Log → API Configuration: configures requests (evidence: `frontend/src/pages/AuditLog.jsx`)
- Dashboard → Transaction API: opens live stream (evidence: `frontend/src/pages/Dashboard.jsx`)
- Flag Investigation → Review Actions: renders (evidence: `frontend/src/pages/FlagDetail.jsx`)
- Flag Investigation → Geo Investigation Map: renders (evidence: `frontend/src/pages/FlagDetail.jsx`)
- Flag Investigation → Entity Graph View: renders (evidence: `frontend/src/pages/FlagDetail.jsx`)
- Flag Investigation → Rule Breakdown: renders (evidence: `frontend/src/pages/FlagDetail.jsx`)
- Review Actions → API Configuration: configures requests (evidence: `frontend/src/components/ActionPanel.jsx`)
