# shereiff1/finguard architecture

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

- Interactive diagram: https://gitdiagram.com/shereiff1/finguard
- Repository: https://github.com/shereiff1/finguard

## Overview

FinGuard streams transactions from clients through Go ingestion and Kafka, scores them with a Python ONNX service using Redis profile features, then settles or flags them in a Java/PostgreSQL ledger. The graph preserves the documented ingestion, scoring, settlement, and fraud-handling stages. Internal relationships are shown where excerpts or the README support them; unsampled wiring is not inferred.

Main entry points: [`finguard-ledger/src/main/java/com/finguard/ledger/service/LedgerService.java`](https://github.com/shereiff1/finguard/blob/main/finguard-ledger/src/main/java/com/finguard/ledger/service/LedgerService.java) (Ledger settlement), [`finguard-ledger/src/main/java/com/finguard/ledger/service/FraudHandlerService.java`](https://github.com/shereiff1/finguard/blob/main/finguard-ledger/src/main/java/com/finguard/ledger/service/FraudHandlerService.java) (Fraud handling), [`finguard-ml/app/services/kafka_worker.py`](https://github.com/shereiff1/finguard/blob/main/finguard-ml/app/services/kafka_worker.py) (Scoring worker), [`finguard-ml/app/main.py`](https://github.com/shereiff1/finguard/blob/main/finguard-ml/app/main.py) (ML service lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Transaction ingestion"]
  node_ws["WebSocket transport<br/>[http.go]"]
  node_transaction["Transaction model<br/>[transaction.go]"]
  node_ingest_worker["Kafka worker pool<br/>[kafka_worker.go]"]
  node_server["Ingestion server<br/>[main.go]"]
end

subgraph group_scoring["Fraud scoring"]
  node_ml_app["ML service lifecycle<br/>[main.py]"]
  node_worker["Scoring worker<br/>[kafka_worker.py]"]
  node_inference["ONNX inference<br/>[inference.py]"]
  node_cache["Feature cache<br/>[cache.py]"]
  node_config["ML configuration<br/>[config.py]"]
end

subgraph group_ledger["Ledger settlement"]
  node_consumer["Transaction consumer"]
  node_dto["Evaluated transaction DTO"]
  node_ledger_service["Ledger settlement<br/>[LedgerService.java]"]
  node_fraud_service["Fraud handling"]
  node_account_repo["Account repository"]
  node_transaction_repo["Transaction repository"]
  node_alert_repo["Fraud alert repository"]
  node_account["Account entity<br/>[Account.java]"]
  node_ledger_tx["Ledger transaction entity"]
  node_fraud_alert["Fraud alert entity<br/>[FraudAlert.java]"]
end

subgraph group_infra["Streaming and storage"]
  node_kafka["Apache Kafka"]
  node_raw_topic["Raw transactions"]
  node_redis[("Redis profiles")]
  node_evaluated_topic["Evaluated transactions"]
  node_postgres[("PostgreSQL")]
end

node_client(("Transaction client"))

node_client -->|"streams transactions"| node_ws
node_ws -->|"publishes asynchronously"| node_ingest_worker
node_ingest_worker -->|"publishes events"| node_raw_topic
node_raw_topic -->|"consumes"| node_worker
node_ml_app -->|"starts"| node_worker
node_ml_app -->|"creates"| node_cache
node_ml_app -->|"creates"| node_inference
node_worker -->|"reads profiles"| node_cache
node_worker -->|"scores features"| node_inference
node_cache -->|"reads profiles"| node_redis
node_worker -->|"publishes scored events"| node_evaluated_topic
node_evaluated_topic -->|"delivers events"| node_consumer
node_consumer -->|"deserializes as"| node_dto
node_consumer -->|"calls process"| node_ledger_service
node_ledger_service -->|"checks and handles fraud"| node_fraud_service
node_ledger_service -->|"locks and updates accounts"| node_account_repo
node_ledger_service -->|"persists transactions"| node_transaction_repo
node_fraud_service -->|"freezes account"| node_account_repo
node_fraud_service -->|"marks rollback"| node_transaction_repo
node_fraud_service -->|"saves alert"| node_alert_repo
node_account_repo -->|"maps entity"| node_account
node_transaction_repo -->|"maps entity"| node_ledger_tx
node_alert_repo -->|"maps entity"| node_fraud_alert
node_ledger_service -->|"persists settlement"| node_postgres
node_fraud_service -->|"persists alerts"| node_postgres

click node_ws "https://github.com/shereiff1/finguard/blob/main/finguard-ingestion/internal/transport/http.go"
click node_transaction "https://github.com/shereiff1/finguard/blob/main/finguard-ingestion/internal/domain/transaction.go"
click node_ingest_worker "https://github.com/shereiff1/finguard/blob/main/finguard-ingestion/internal/worker/kafka_worker.go"
click node_server "https://github.com/shereiff1/finguard/blob/main/finguard-ingestion/cmd/server/main.go"
click node_ml_app "https://github.com/shereiff1/finguard/blob/main/finguard-ml/app/main.py"
click node_worker "https://github.com/shereiff1/finguard/blob/main/finguard-ml/app/services/kafka_worker.py"
click node_inference "https://github.com/shereiff1/finguard/blob/main/finguard-ml/app/services/inference.py"
click node_cache "https://github.com/shereiff1/finguard/blob/main/finguard-ml/app/services/cache.py"
click node_config "https://github.com/shereiff1/finguard/blob/main/finguard-ml/app/config.py"
click node_consumer "https://github.com/shereiff1/finguard/blob/main/finguard-ledger/src/main/java/com/finguard/ledger/consumer/TransactionConsumer.java"
click node_dto "https://github.com/shereiff1/finguard/blob/main/finguard-ledger/src/main/java/com/finguard/ledger/dto/EvaluatedTransaction.java"
click node_ledger_service "https://github.com/shereiff1/finguard/blob/main/finguard-ledger/src/main/java/com/finguard/ledger/service/LedgerService.java"
click node_fraud_service "https://github.com/shereiff1/finguard/blob/main/finguard-ledger/src/main/java/com/finguard/ledger/service/FraudHandlerService.java"
click node_account_repo "https://github.com/shereiff1/finguard/blob/main/finguard-ledger/src/main/java/com/finguard/ledger/repository/AccountRepository.java"
click node_transaction_repo "https://github.com/shereiff1/finguard/blob/main/finguard-ledger/src/main/java/com/finguard/ledger/repository/LedgerTransactionRepository.java"
click node_alert_repo "https://github.com/shereiff1/finguard/blob/main/finguard-ledger/src/main/java/com/finguard/ledger/repository/FraudAlertRepository.java"
click node_account "https://github.com/shereiff1/finguard/blob/main/finguard-ledger/src/main/java/com/finguard/ledger/domain/Account.java"
click node_ledger_tx "https://github.com/shereiff1/finguard/blob/main/finguard-ledger/src/main/java/com/finguard/ledger/domain/LedgerTransaction.java"
click node_fraud_alert "https://github.com/shereiff1/finguard/blob/main/finguard-ledger/src/main/java/com/finguard/ledger/domain/FraudAlert.java"

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_ws,node_transaction,node_ingest_worker,node_server,node_client toneBlue
class node_ml_app,node_worker,node_inference,node_cache,node_config toneAmber
class node_consumer,node_dto,node_ledger_service,node_fraud_service,node_account_repo,node_transaction_repo,node_alert_repo,node_account,node_ledger_tx,node_fraud_alert toneMint
class node_kafka,node_raw_topic,node_redis,node_evaluated_topic,node_postgres toneRose
```

## Components

### Transaction ingestion

- [WebSocket transport](https://github.com/shereiff1/finguard/blob/main/finguard-ingestion/internal/transport/http.go): `finguard-ingestion/internal/transport/http.go`
- [Transaction model](https://github.com/shereiff1/finguard/blob/main/finguard-ingestion/internal/domain/transaction.go): `finguard-ingestion/internal/domain/transaction.go`
- [Kafka worker pool](https://github.com/shereiff1/finguard/blob/main/finguard-ingestion/internal/worker/kafka_worker.go): `finguard-ingestion/internal/worker/kafka_worker.go`
- [Ingestion server](https://github.com/shereiff1/finguard/blob/main/finguard-ingestion/cmd/server/main.go): `finguard-ingestion/cmd/server/main.go`

### Fraud scoring

- [ML service lifecycle](https://github.com/shereiff1/finguard/blob/main/finguard-ml/app/main.py): `finguard-ml/app/main.py`
- [Scoring worker](https://github.com/shereiff1/finguard/blob/main/finguard-ml/app/services/kafka_worker.py): `finguard-ml/app/services/kafka_worker.py`
- [ONNX inference](https://github.com/shereiff1/finguard/blob/main/finguard-ml/app/services/inference.py): `finguard-ml/app/services/inference.py`
- [Feature cache](https://github.com/shereiff1/finguard/blob/main/finguard-ml/app/services/cache.py): `finguard-ml/app/services/cache.py`
- [ML configuration](https://github.com/shereiff1/finguard/blob/main/finguard-ml/app/config.py): `finguard-ml/app/config.py`

### Ledger settlement

- [Transaction consumer](https://github.com/shereiff1/finguard/blob/main/finguard-ledger/src/main/java/com/finguard/ledger/consumer/TransactionConsumer.java): `finguard-ledger/src/main/java/com/finguard/ledger/consumer/TransactionConsumer.java`
- [Evaluated transaction DTO](https://github.com/shereiff1/finguard/blob/main/finguard-ledger/src/main/java/com/finguard/ledger/dto/EvaluatedTransaction.java): `finguard-ledger/src/main/java/com/finguard/ledger/dto/EvaluatedTransaction.java`
- [Ledger settlement](https://github.com/shereiff1/finguard/blob/main/finguard-ledger/src/main/java/com/finguard/ledger/service/LedgerService.java): `finguard-ledger/src/main/java/com/finguard/ledger/service/LedgerService.java`
- [Fraud handling](https://github.com/shereiff1/finguard/blob/main/finguard-ledger/src/main/java/com/finguard/ledger/service/FraudHandlerService.java): `finguard-ledger/src/main/java/com/finguard/ledger/service/FraudHandlerService.java`
- [Account repository](https://github.com/shereiff1/finguard/blob/main/finguard-ledger/src/main/java/com/finguard/ledger/repository/AccountRepository.java): `finguard-ledger/src/main/java/com/finguard/ledger/repository/AccountRepository.java`
- [Transaction repository](https://github.com/shereiff1/finguard/blob/main/finguard-ledger/src/main/java/com/finguard/ledger/repository/LedgerTransactionRepository.java): `finguard-ledger/src/main/java/com/finguard/ledger/repository/LedgerTransactionRepository.java`
- [Fraud alert repository](https://github.com/shereiff1/finguard/blob/main/finguard-ledger/src/main/java/com/finguard/ledger/repository/FraudAlertRepository.java): `finguard-ledger/src/main/java/com/finguard/ledger/repository/FraudAlertRepository.java`
- [Account entity](https://github.com/shereiff1/finguard/blob/main/finguard-ledger/src/main/java/com/finguard/ledger/domain/Account.java): `finguard-ledger/src/main/java/com/finguard/ledger/domain/Account.java`
- [Ledger transaction entity](https://github.com/shereiff1/finguard/blob/main/finguard-ledger/src/main/java/com/finguard/ledger/domain/LedgerTransaction.java): `finguard-ledger/src/main/java/com/finguard/ledger/domain/LedgerTransaction.java`
- [Fraud alert entity](https://github.com/shereiff1/finguard/blob/main/finguard-ledger/src/main/java/com/finguard/ledger/domain/FraudAlert.java): `finguard-ledger/src/main/java/com/finguard/ledger/domain/FraudAlert.java`

### Streaming and storage

- **Apache Kafka**
- **Raw transactions**
- **Redis profiles**
- **Evaluated transactions**
- **PostgreSQL**

### Other components

- **Transaction client**

## Connections

- Transaction client → WebSocket transport: streams transactions (evidence: `README.md`)
- WebSocket transport → Kafka worker pool: publishes asynchronously (evidence: `README.md`)
- Kafka worker pool → Raw transactions: publishes events (evidence: `README.md`)
- Raw transactions → Scoring worker: consumes (evidence: `README.md`)
- ML service lifecycle → Scoring worker: starts (evidence: `finguard-ml/app/main.py`)
- ML service lifecycle → Feature cache: creates (evidence: `finguard-ml/app/main.py`)
- ML service lifecycle → ONNX inference: creates (evidence: `finguard-ml/app/main.py`)
- Scoring worker → Feature cache: reads profiles (evidence: `finguard-ml/app/services/kafka_worker.py`)
- Scoring worker → ONNX inference: scores features (evidence: `finguard-ml/app/services/kafka_worker.py`)
- Feature cache → Redis profiles: reads profiles (evidence: `README.md`)
- Scoring worker → Evaluated transactions: publishes scored events (evidence: `finguard-ml/app/services/kafka_worker.py`)
- Evaluated transactions → Transaction consumer: delivers events (evidence: `README.md`)
- Transaction consumer → Evaluated transaction DTO: deserializes as (evidence: `finguard-ledger/src/main/java/com/finguard/ledger/consumer/TransactionConsumer.java`)
- Transaction consumer → Ledger settlement: calls process (evidence: `finguard-ledger/src/main/java/com/finguard/ledger/consumer/TransactionConsumer.java`)
- Ledger settlement → Fraud handling: checks and handles fraud (evidence: `finguard-ledger/src/main/java/com/finguard/ledger/service/LedgerService.java`)
- Ledger settlement → Account repository: locks and updates accounts (evidence: `finguard-ledger/src/main/java/com/finguard/ledger/service/LedgerService.java`)
- Ledger settlement → Transaction repository: persists transactions (evidence: `finguard-ledger/src/main/java/com/finguard/ledger/service/LedgerService.java`)
- Fraud handling → Account repository: freezes account (evidence: `finguard-ledger/src/main/java/com/finguard/ledger/service/FraudHandlerService.java`)
- Fraud handling → Transaction repository: marks rollback (evidence: `finguard-ledger/src/main/java/com/finguard/ledger/service/FraudHandlerService.java`)
- Fraud handling → Fraud alert repository: saves alert (evidence: `finguard-ledger/src/main/java/com/finguard/ledger/service/FraudHandlerService.java`)
- Account repository → Account entity: maps entity (evidence: `finguard-ledger/src/main/java/com/finguard/ledger/repository/AccountRepository.java`)
- Transaction repository → Ledger transaction entity: maps entity (evidence: `finguard-ledger/src/main/java/com/finguard/ledger/repository/LedgerTransactionRepository.java`)
- Fraud alert repository → Fraud alert entity: maps entity (evidence: `finguard-ledger/src/main/java/com/finguard/ledger/repository/FraudAlertRepository.java`)
- Ledger settlement → PostgreSQL: persists settlement (evidence: `README.md`)
- Fraud handling → PostgreSQL: persists alerts (evidence: `README.md`)
