# pravinraj213/fraud-engine architecture

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

- Interactive diagram: https://gitdiagram.com/pravinraj213/fraud-engine
- Repository: https://github.com/pravinraj213/fraud-engine

## Overview

This is a card-transaction fraud scoring and review application. Clients submit transactions; the backend evaluates pluggable rules against prior account history, stores transactions and assessments, and queues high-risk alerts. Reviewers use the React console to inspect flags and record decisions; the console also exposes rule configuration and transaction simulation. The README documents several subsystem relationships not visible in the sampled source; those links cite the README. Some API routes and frontend pages were not sampled, so their internal wiring is not expanded.

Main entry points: [`backend/app/api`](https://github.com/pravinraj213/fraud-engine/tree/main/backend/app/api) (FastAPI routes), [`frontend/src/api/client.js`](https://github.com/pravinraj213/fraud-engine/blob/main/frontend/src/api/client.js) (API client), [`backend/app/repositories`](https://github.com/pravinraj213/fraud-engine/tree/main/backend/app/repositories) (Persistence repositories), [`backend/app/services/transaction_service.py`](https://github.com/pravinraj213/fraud-engine/blob/main/backend/app/services/transaction_service.py) (Transaction service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Ingestion and scoring"]
  node_api["FastAPI routes"]
  node_transaction_service["Transaction service"]
  node_engine["Rule engine<br/>[engine.py]"]
  node_rules["Detection rules"]
  node_history["Account history<br/>[history.py]"]
  node_repositories["Persistence repositories"]
  node_database[("SQLite database<br/>[database.py]")]
  node_data_models["Fraud records<br/>[models.py]"]
end

subgraph group_review["Review and reporting"]
  node_query_service["Queue and detail queries<br/>[query_service.py]"]
  node_review_service["Review lifecycle<br/>[review_service.py]"]
end

subgraph group_alerts["Alert delivery"]
  node_alert_service["Alert orchestration"]
  node_notifier["Notifier selection<br/>[factory.py]"]
  node_ses["Amazon SES<br/>[ses.py]"]
  node_log_notifier["Log notifier<br/>[log.py]"]
end

subgraph group_console["Reviewer console"]
  node_console["React console<br/>[App.jsx]"]
  node_api_client["API client<br/>[client.js]"]
  node_queue_page["Review queue<br/>[QueuePage.jsx]"]
  node_transaction_page["Transaction review"]
  node_rules_page["Rules view<br/>[RulesPage.jsx]"]
  node_simulator_page["Transaction simulator<br/>[SimulatorPage.jsx]"]
end

node_client(("Simulator / client"))
node_reviewer(("Reviewer"))
node_mail_service["Amazon SES"]

node_client -->|"posts transactions"| node_api
node_api -->|"ingests"| node_transaction_service
node_transaction_service -->|"evaluates"| node_engine
node_engine -->|"runs enabled rules"| node_rules
node_transaction_service -->|"reads prior activity"| node_history
node_transaction_service -->|"stores transaction and verdict"| node_repositories
node_repositories -->|"persists records"| node_database
node_database -->|"creates tables for"| node_data_models
node_api -->|"requests queue and details"| node_query_service
node_api -->|"requests review action"| node_review_service
node_query_service -->|"queries assessments and alerts"| node_repositories
node_review_service -->|"records decisions"| node_repositories
node_api -->|"schedules high-risk alert"| node_alert_service
node_alert_service -->|"claims and records delivery"| node_repositories
node_alert_service -->|"selects delivery channel"| node_notifier
node_notifier -->|"selects SES"| node_ses
node_notifier -->|"selects log"| node_log_notifier
node_ses -->|"sends email"| node_mail_service
node_reviewer -->|"uses"| node_console
node_console -->|"polls system and stats"| node_api_client
node_queue_page -->|"loads queue"| node_api_client
node_transaction_page -.->|"loads transaction"| node_api_client
node_rules_page -.->|"loads rules"| node_api_client
node_simulator_page -.->|"submits transactions"| node_api_client
node_api_client -->|"calls endpoints"| node_api

click node_api "https://github.com/pravinraj213/fraud-engine/tree/main/backend/app/api"
click node_transaction_service "https://github.com/pravinraj213/fraud-engine/blob/main/backend/app/services/transaction_service.py"
click node_engine "https://github.com/pravinraj213/fraud-engine/blob/main/backend/app/engine/engine.py"
click node_rules "https://github.com/pravinraj213/fraud-engine/tree/main/backend/app/engine/rules"
click node_history "https://github.com/pravinraj213/fraud-engine/blob/main/backend/app/repositories/history.py"
click node_repositories "https://github.com/pravinraj213/fraud-engine/tree/main/backend/app/repositories"
click node_database "https://github.com/pravinraj213/fraud-engine/blob/main/backend/app/database.py"
click node_data_models "https://github.com/pravinraj213/fraud-engine/blob/main/backend/app/models.py"
click node_query_service "https://github.com/pravinraj213/fraud-engine/blob/main/backend/app/services/query_service.py"
click node_review_service "https://github.com/pravinraj213/fraud-engine/blob/main/backend/app/services/review_service.py"
click node_alert_service "https://github.com/pravinraj213/fraud-engine/blob/main/backend/app/services/notification_service.py"
click node_notifier "https://github.com/pravinraj213/fraud-engine/blob/main/backend/app/notifications/factory.py"
click node_ses "https://github.com/pravinraj213/fraud-engine/blob/main/backend/app/notifications/ses.py"
click node_log_notifier "https://github.com/pravinraj213/fraud-engine/blob/main/backend/app/notifications/log.py"
click node_console "https://github.com/pravinraj213/fraud-engine/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/pravinraj213/fraud-engine/blob/main/frontend/src/api/client.js"
click node_queue_page "https://github.com/pravinraj213/fraud-engine/blob/main/frontend/src/pages/QueuePage.jsx"
click node_transaction_page "https://github.com/pravinraj213/fraud-engine/blob/main/frontend/src/pages/TransactionPage.jsx"
click node_rules_page "https://github.com/pravinraj213/fraud-engine/blob/main/frontend/src/pages/RulesPage.jsx"
click node_simulator_page "https://github.com/pravinraj213/fraud-engine/blob/main/frontend/src/pages/SimulatorPage.jsx"

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_transaction_service,node_engine,node_rules,node_history,node_repositories,node_database,node_data_models,node_client,node_reviewer toneBlue
class node_query_service,node_review_service toneAmber
class node_alert_service,node_notifier,node_ses,node_log_notifier toneMint
class node_console,node_api_client,node_queue_page,node_transaction_page,node_rules_page,node_simulator_page toneRose
class node_mail_service toneIndigo
```

## Components

### Ingestion and scoring

- [FastAPI routes](https://github.com/pravinraj213/fraud-engine/tree/main/backend/app/api): `backend/app/api`
- [Transaction service](https://github.com/pravinraj213/fraud-engine/blob/main/backend/app/services/transaction_service.py): `backend/app/services/transaction_service.py`
- [Rule engine](https://github.com/pravinraj213/fraud-engine/blob/main/backend/app/engine/engine.py): `backend/app/engine/engine.py`
- [Detection rules](https://github.com/pravinraj213/fraud-engine/tree/main/backend/app/engine/rules): `backend/app/engine/rules`
- [Account history](https://github.com/pravinraj213/fraud-engine/blob/main/backend/app/repositories/history.py): `backend/app/repositories/history.py`
- [Persistence repositories](https://github.com/pravinraj213/fraud-engine/tree/main/backend/app/repositories): `backend/app/repositories`
- [SQLite database](https://github.com/pravinraj213/fraud-engine/blob/main/backend/app/database.py): `backend/app/database.py`
- [Fraud records](https://github.com/pravinraj213/fraud-engine/blob/main/backend/app/models.py): `backend/app/models.py`

### Review and reporting

- [Queue and detail queries](https://github.com/pravinraj213/fraud-engine/blob/main/backend/app/services/query_service.py): `backend/app/services/query_service.py`
- [Review lifecycle](https://github.com/pravinraj213/fraud-engine/blob/main/backend/app/services/review_service.py): `backend/app/services/review_service.py`

### Alert delivery

- [Alert orchestration](https://github.com/pravinraj213/fraud-engine/blob/main/backend/app/services/notification_service.py): `backend/app/services/notification_service.py`
- [Notifier selection](https://github.com/pravinraj213/fraud-engine/blob/main/backend/app/notifications/factory.py): `backend/app/notifications/factory.py`
- [Amazon SES](https://github.com/pravinraj213/fraud-engine/blob/main/backend/app/notifications/ses.py): `backend/app/notifications/ses.py`
- [Log notifier](https://github.com/pravinraj213/fraud-engine/blob/main/backend/app/notifications/log.py): `backend/app/notifications/log.py`

### Reviewer console

- [React console](https://github.com/pravinraj213/fraud-engine/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/pravinraj213/fraud-engine/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`
- [Review queue](https://github.com/pravinraj213/fraud-engine/blob/main/frontend/src/pages/QueuePage.jsx): `frontend/src/pages/QueuePage.jsx`
- [Transaction review](https://github.com/pravinraj213/fraud-engine/blob/main/frontend/src/pages/TransactionPage.jsx): `frontend/src/pages/TransactionPage.jsx`
- [Rules view](https://github.com/pravinraj213/fraud-engine/blob/main/frontend/src/pages/RulesPage.jsx): `frontend/src/pages/RulesPage.jsx`
- [Transaction simulator](https://github.com/pravinraj213/fraud-engine/blob/main/frontend/src/pages/SimulatorPage.jsx): `frontend/src/pages/SimulatorPage.jsx`

### Other components

- **Simulator / client**
- **Reviewer**
- **Amazon SES**

## Connections

- Simulator / client → FastAPI routes: posts transactions
- FastAPI routes → Transaction service: ingests (evidence: `backend/app/api/transactions.py`)
- Transaction service → Rule engine: evaluates (evidence: `backend/app/services/transaction_service.py`)
- Rule engine → Detection rules: runs enabled rules
- Transaction service → Account history: reads prior activity (evidence: `backend/app/services/transaction_service.py`)
- Transaction service → Persistence repositories: stores transaction and verdict (evidence: `backend/app/services/transaction_service.py`)
- Persistence repositories → SQLite database: persists records
- SQLite database → Fraud records: creates tables for (evidence: `backend/app/database.py`)
- FastAPI routes → Queue and detail queries: requests queue and details (evidence: `backend/app/api/transactions.py`)
- FastAPI routes → Review lifecycle: requests review action (evidence: `backend/app/api/transactions.py`)
- Queue and detail queries → Persistence repositories: queries assessments and alerts (evidence: `backend/app/services/query_service.py`)
- Review lifecycle → Persistence repositories: records decisions (evidence: `backend/app/services/review_service.py`)
- FastAPI routes → Alert orchestration: schedules high-risk alert (evidence: `backend/app/api/transactions.py`)
- Alert orchestration → Persistence repositories: claims and records delivery (evidence: `backend/app/services/notification_service.py`)
- Alert orchestration → Notifier selection: selects delivery channel (evidence: `backend/app/services/notification_service.py`)
- Notifier selection → Amazon SES: selects SES (evidence: `backend/app/notifications/factory.py`)
- Notifier selection → Log notifier: selects log (evidence: `backend/app/notifications/factory.py`)
- Amazon SES → Amazon SES: sends email (evidence: `backend/app/notifications/ses.py`)
- Reviewer → React console: uses
- React console → API client: polls system and stats (evidence: `frontend/src/App.jsx`)
- Review queue → API client: loads queue (evidence: `frontend/src/pages/QueuePage.jsx`)
- Transaction review → API client: loads transaction
- Rules view → API client: loads rules
- Transaction simulator → API client: submits transactions
- API client → FastAPI routes: calls endpoints
