# auzzton/financial-fraud-detector architecture

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

- Interactive diagram: https://gitdiagram.com/auzzton/financial-fraud-detector
- Repository: https://github.com/auzzton/financial-fraud-detector

## Overview

This platform generates or receives transactions, scores them for fraud, persists outcomes, and streams updates to an analyst dashboard. The consumer combines velocity enrichment, threshold rules, and an ML prediction; high-risk outcomes can trigger alerts and blocking. Analysts label transactions and download reports, while a separate training workflow uses stored transactions and labels to register models that the consumer can load. README documents these capabilities; some endpoint and blocking details are only partially visible in the sampled consumer source, so uncertain internal wiring is omitted.

Main entry points: [`consumer/main.py`](https://github.com/auzzton/financial-fraud-detector/blob/main/consumer/main.py) (FastAPI consumer), [`frontend/src/app/page.tsx`](https://github.com/auzzton/financial-fraud-detector/blob/main/frontend/src/app/page.tsx) (Live dashboard), [`ml/train.py`](https://github.com/auzzton/financial-fraud-detector/blob/main/ml/train.py) (Model training), [`consumer/enrichment.py`](https://github.com/auzzton/financial-fraud-detector/blob/main/consumer/enrichment.py) (User enrichment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_streaming["Transaction streaming"]
  node_producer["Transaction producer<br/>[producer.py]"]
  node_kafka["Kafka topic"]
end

subgraph group_detection["Fraud detection"]
  node_consumer["FastAPI consumer<br/>[main.py]"]
  node_enrichment["User enrichment<br/>[enrichment.py]"]
  node_scoring["Risk scoring<br/>[scoring.py]"]
  node_notifications["Critical notifications<br/>[notifications.py]"]
end

subgraph group_persistence["State and persistence"]
  node_models["Data models<br/>[models.py]"]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis counters")]
end

subgraph group_learning["Model learning"]
  node_trainer["Model training<br/>[train.py]"]
  node_mlflow["MLflow registry"]
end

subgraph group_analyst["Analyst experience"]
  node_dashboard["Live dashboard<br/>[page.tsx]"]
end

node_analyst(("Fraud analyst"))

node_producer -->|"publishes transactions"| node_kafka
node_kafka -->|"delivers transactions"| node_consumer
node_consumer -->|"updates and reads counters"| node_enrichment
node_enrichment -->|"reads/writes counters"| node_redis
node_consumer -->|"calculates risk"| node_scoring
node_consumer -->|"dispatches critical alerts"| node_notifications
node_consumer -->|"uses sessions and records"| node_models
node_models -->|"maps and connects"| node_postgres
node_consumer -->|"queries and persists"| node_postgres
node_trainer -->|"loads transactions and labels"| node_postgres
node_trainer -->|"logs and registers models"| node_mlflow
node_consumer -->|"loads registered models"| node_mlflow
node_consumer -->|"streams alert updates"| node_dashboard
node_dashboard -->|"submits labels and report requests"| node_consumer
node_analyst -->|"reviews and labels"| node_dashboard

click node_producer "https://github.com/auzzton/financial-fraud-detector/blob/main/producer.py"
click node_consumer "https://github.com/auzzton/financial-fraud-detector/blob/main/consumer/main.py"
click node_enrichment "https://github.com/auzzton/financial-fraud-detector/blob/main/consumer/enrichment.py"
click node_scoring "https://github.com/auzzton/financial-fraud-detector/blob/main/consumer/scoring.py"
click node_notifications "https://github.com/auzzton/financial-fraud-detector/blob/main/consumer/notifications.py"
click node_models "https://github.com/auzzton/financial-fraud-detector/blob/main/consumer/models.py"
click node_trainer "https://github.com/auzzton/financial-fraud-detector/blob/main/ml/train.py"
click node_dashboard "https://github.com/auzzton/financial-fraud-detector/blob/main/frontend/src/app/page.tsx"

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_producer,node_kafka toneBlue
class node_consumer,node_enrichment,node_scoring,node_notifications toneAmber
class node_models,node_postgres,node_redis toneMint
class node_trainer,node_mlflow toneRose
class node_dashboard,node_analyst toneIndigo
```

## Components

### Transaction streaming

- [Transaction producer](https://github.com/auzzton/financial-fraud-detector/blob/main/producer.py): `producer.py`
- **Kafka topic**

### Fraud detection

- [FastAPI consumer](https://github.com/auzzton/financial-fraud-detector/blob/main/consumer/main.py): `consumer/main.py`
- [User enrichment](https://github.com/auzzton/financial-fraud-detector/blob/main/consumer/enrichment.py): `consumer/enrichment.py`
- [Risk scoring](https://github.com/auzzton/financial-fraud-detector/blob/main/consumer/scoring.py): `consumer/scoring.py`
- [Critical notifications](https://github.com/auzzton/financial-fraud-detector/blob/main/consumer/notifications.py): `consumer/notifications.py`

### State and persistence

- [Data models](https://github.com/auzzton/financial-fraud-detector/blob/main/consumer/models.py): `consumer/models.py`
- **PostgreSQL**
- **Redis counters**

### Model learning

- [Model training](https://github.com/auzzton/financial-fraud-detector/blob/main/ml/train.py): `ml/train.py`
- **MLflow registry**

### Analyst experience

- [Live dashboard](https://github.com/auzzton/financial-fraud-detector/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`

### Other components

- **Fraud analyst**

## Connections

- Transaction producer → Kafka topic: publishes transactions
- Kafka topic → FastAPI consumer: delivers transactions
- FastAPI consumer → User enrichment: updates and reads counters
- User enrichment → Redis counters: reads/writes counters
- FastAPI consumer → Risk scoring: calculates risk
- FastAPI consumer → Critical notifications: dispatches critical alerts
- FastAPI consumer → Data models: uses sessions and records
- Data models → PostgreSQL: maps and connects
- FastAPI consumer → PostgreSQL: queries and persists
- Model training → PostgreSQL: loads transactions and labels
- Model training → MLflow registry: logs and registers models
- FastAPI consumer → MLflow registry: loads registered models
- FastAPI consumer → Live dashboard: streams alert updates
- Live dashboard → FastAPI consumer: submits labels and report requests
- Fraud analyst → Live dashboard: reviews and labels