# jessicapersou/fraud-detection-sdd architecture

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

- Interactive diagram: https://gitdiagram.com/jessicapersou/fraud-detection-sdd
- Repository: https://github.com/jessicapersou/fraud-detection-sdd

## Overview

This is a real-time fraud detection system built from three Kafka-connected services. A client submits an idempotent transaction; the transaction service stores it with an outbox event, fraud analysis evaluates frequency and amount rules and emits alerts for medium/high risk, and notification processing records delivery attempts and sends through a provider. The README documents the cross-service event flow; sampled use cases show their internal calls. Several adapters and listeners are listed in the tree but were not sampled, so their wiring is not asserted beyond documented relationships.

Main entry points: [`fraud-service/src/main/java/com/persou/antifraud/fraud/application/usecase/AnalyzeTransactionService.java`](https://github.com/jessicapersou/fraud-detection-sdd/blob/main/fraud-service/src/main/java/com/persou/antifraud/fraud/application/usecase/AnalyzeTransactionService.java) (Analyze transaction), [`transaction-service/src/main/java/com/persou/antifraud/transaction/application/usecase/ReceiveTransactionService.java`](https://github.com/jessicapersou/fraud-detection-sdd/blob/main/transaction-service/src/main/java/com/persou/antifraud/transaction/application/usecase/ReceiveTransactionService.java) (Receive transaction), [`notification-service/src/main/java/com/persou/antifraud/notification/application/usecase/ProcessFraudAlertService.java`](https://github.com/jessicapersou/fraud-detection-sdd/blob/main/notification-service/src/main/java/com/persou/antifraud/notification/application/usecase/ProcessFraudAlertService.java) (Process alert), [`transaction-service/src/main/java/com/persou/antifraud/transaction/adapter/out/kafka/OutboxPublisher.java`](https://github.com/jessicapersou/fraud-detection-sdd/blob/main/transaction-service/src/main/java/com/persou/antifraud/transaction/adapter/out/kafka/OutboxPublisher.java) (Outbox publisher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_transactions["Transaction intake"]
  node_controller["Transaction REST"]
  node_receive["Receive transaction"]
  node_txrecord[("Transaction store")]
  node_idempotency[("Idempotency store")]
  node_outbox[("Outbox store")]
  node_publisher["Outbox publisher"]
end

subgraph group_fraud["Fraud analysis"]
  node_fraudlistener["Transaction listener"]
  node_analyze["Analyze transaction"]
  node_rules["Fraud rules"]
  node_frequency[("Frequency history")]
  node_analysisstore[("Analysis store")]
  node_fraudpublisher["Alert publisher"]
end

subgraph group_notifications["Alert notifications"]
  node_alertlistener["Fraud alert listener"]
  node_processalert["Process alert"]
  node_notifystore[("Notification store")]
  node_provider["Notification provider"]
end

subgraph group_events["Event contracts"]
  node_txevent["Transaction event"]
  node_fraudevent["Fraud alert event"]
end

node_client(("API client"))
node_broker["Kafka"]

node_client -->|"submits transaction"| node_controller
node_controller -->|"invokes"| node_receive
node_receive -->|"checks and reserves"| node_idempotency
node_receive -->|"saves transaction"| node_txrecord
node_receive -->|"saves event"| node_outbox
node_publisher -.->|"publishes pending"| node_outbox
node_publisher -->|"publishes event"| node_broker
node_broker -->|"delivers event"| node_fraudlistener
node_fraudlistener -.->|"dispatches"| node_analyze
node_analyze -->|"records and counts"| node_frequency
node_analyze -->|"evaluates findings"| node_rules
node_analyze -->|"stores analysis"| node_analysisstore
node_analyze -->|"publishes qualifying alert"| node_fraudpublisher
node_fraudpublisher -->|"publishes alert"| node_broker
node_broker -->|"delivers alert"| node_alertlistener
node_alertlistener -.->|"dispatches"| node_processalert
node_processalert -->|"records attempts"| node_notifystore
node_processalert -->|"sends notification"| node_provider

click node_controller "https://github.com/jessicapersou/fraud-detection-sdd/blob/main/transaction-service/src/main/java/com/persou/antifraud/transaction/adapter/in/rest/TransactionController.java"
click node_receive "https://github.com/jessicapersou/fraud-detection-sdd/blob/main/transaction-service/src/main/java/com/persou/antifraud/transaction/application/usecase/ReceiveTransactionService.java"
click node_txrecord "https://github.com/jessicapersou/fraud-detection-sdd/blob/main/transaction-service/src/main/java/com/persou/antifraud/transaction/adapter/out/persistence/JpaTransactionRepositoryAdapter.java"
click node_idempotency "https://github.com/jessicapersou/fraud-detection-sdd/blob/main/transaction-service/src/main/java/com/persou/antifraud/transaction/adapter/out/persistence/JpaIdempotencyRepositoryAdapter.java"
click node_outbox "https://github.com/jessicapersou/fraud-detection-sdd/blob/main/transaction-service/src/main/java/com/persou/antifraud/transaction/adapter/out/persistence/JpaOutboxRepositoryAdapter.java"
click node_publisher "https://github.com/jessicapersou/fraud-detection-sdd/blob/main/transaction-service/src/main/java/com/persou/antifraud/transaction/adapter/out/kafka/OutboxPublisher.java"
click node_txevent "https://github.com/jessicapersou/fraud-detection-sdd/blob/main/event-contracts/src/main/java/com/persou/antifraud/contracts/TransactionCreatedEvent.java"
click node_fraudlistener "https://github.com/jessicapersou/fraud-detection-sdd/blob/main/fraud-service/src/main/java/com/persou/antifraud/fraud/adapter/in/kafka/TransactionCreatedListener.java"
click node_analyze "https://github.com/jessicapersou/fraud-detection-sdd/blob/main/fraud-service/src/main/java/com/persou/antifraud/fraud/application/usecase/AnalyzeTransactionService.java"
click node_rules "https://github.com/jessicapersou/fraud-detection-sdd/blob/main/fraud-service/src/main/java/com/persou/antifraud/fraud/domain/service/FraudRuleEvaluator.java"
click node_frequency "https://github.com/jessicapersou/fraud-detection-sdd/blob/main/fraud-service/src/main/java/com/persou/antifraud/fraud/adapter/out/persistence/JpaTransactionFrequencyAdapter.java"
click node_analysisstore "https://github.com/jessicapersou/fraud-detection-sdd/blob/main/fraud-service/src/main/java/com/persou/antifraud/fraud/adapter/out/persistence/JpaFraudAnalysisAdapter.java"
click node_fraudpublisher "https://github.com/jessicapersou/fraud-detection-sdd/blob/main/fraud-service/src/main/java/com/persou/antifraud/fraud/adapter/out/kafka/KafkaFraudAlertPublisher.java"
click node_fraudevent "https://github.com/jessicapersou/fraud-detection-sdd/blob/main/event-contracts/src/main/java/com/persou/antifraud/contracts/FraudDetectedEvent.java"
click node_alertlistener "https://github.com/jessicapersou/fraud-detection-sdd/blob/main/notification-service/src/main/java/com/persou/antifraud/notification/adapter/in/kafka/FraudAlertListener.java"
click node_processalert "https://github.com/jessicapersou/fraud-detection-sdd/blob/main/notification-service/src/main/java/com/persou/antifraud/notification/application/usecase/ProcessFraudAlertService.java"
click node_notifystore "https://github.com/jessicapersou/fraud-detection-sdd/blob/main/notification-service/src/main/java/com/persou/antifraud/notification/adapter/out/persistence/JpaNotificationRepositoryAdapter.java"
click node_provider "https://github.com/jessicapersou/fraud-detection-sdd/blob/main/notification-service/src/main/java/com/persou/antifraud/notification/adapter/out/mail/SmtpNotificationProvider.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_controller,node_receive,node_txrecord,node_idempotency,node_outbox,node_publisher,node_client toneBlue
class node_fraudlistener,node_analyze,node_rules,node_frequency,node_analysisstore,node_fraudpublisher toneAmber
class node_alertlistener,node_processalert,node_notifystore,node_provider toneMint
class node_txevent,node_fraudevent toneRose
class node_broker toneIndigo
```

## Components

### Transaction intake

- [Transaction REST](https://github.com/jessicapersou/fraud-detection-sdd/blob/main/transaction-service/src/main/java/com/persou/antifraud/transaction/adapter/in/rest/TransactionController.java): `transaction-service/src/main/java/com/persou/antifraud/transaction/adapter/in/rest/TransactionController.java`
- [Receive transaction](https://github.com/jessicapersou/fraud-detection-sdd/blob/main/transaction-service/src/main/java/com/persou/antifraud/transaction/application/usecase/ReceiveTransactionService.java): `transaction-service/src/main/java/com/persou/antifraud/transaction/application/usecase/ReceiveTransactionService.java`
- [Transaction store](https://github.com/jessicapersou/fraud-detection-sdd/blob/main/transaction-service/src/main/java/com/persou/antifraud/transaction/adapter/out/persistence/JpaTransactionRepositoryAdapter.java): `transaction-service/src/main/java/com/persou/antifraud/transaction/adapter/out/persistence/JpaTransactionRepositoryAdapter.java`
- [Idempotency store](https://github.com/jessicapersou/fraud-detection-sdd/blob/main/transaction-service/src/main/java/com/persou/antifraud/transaction/adapter/out/persistence/JpaIdempotencyRepositoryAdapter.java): `transaction-service/src/main/java/com/persou/antifraud/transaction/adapter/out/persistence/JpaIdempotencyRepositoryAdapter.java`
- [Outbox store](https://github.com/jessicapersou/fraud-detection-sdd/blob/main/transaction-service/src/main/java/com/persou/antifraud/transaction/adapter/out/persistence/JpaOutboxRepositoryAdapter.java): `transaction-service/src/main/java/com/persou/antifraud/transaction/adapter/out/persistence/JpaOutboxRepositoryAdapter.java`
- [Outbox publisher](https://github.com/jessicapersou/fraud-detection-sdd/blob/main/transaction-service/src/main/java/com/persou/antifraud/transaction/adapter/out/kafka/OutboxPublisher.java): `transaction-service/src/main/java/com/persou/antifraud/transaction/adapter/out/kafka/OutboxPublisher.java`

### Fraud analysis

- [Transaction listener](https://github.com/jessicapersou/fraud-detection-sdd/blob/main/fraud-service/src/main/java/com/persou/antifraud/fraud/adapter/in/kafka/TransactionCreatedListener.java): `fraud-service/src/main/java/com/persou/antifraud/fraud/adapter/in/kafka/TransactionCreatedListener.java`
- [Analyze transaction](https://github.com/jessicapersou/fraud-detection-sdd/blob/main/fraud-service/src/main/java/com/persou/antifraud/fraud/application/usecase/AnalyzeTransactionService.java): `fraud-service/src/main/java/com/persou/antifraud/fraud/application/usecase/AnalyzeTransactionService.java`
- [Fraud rules](https://github.com/jessicapersou/fraud-detection-sdd/blob/main/fraud-service/src/main/java/com/persou/antifraud/fraud/domain/service/FraudRuleEvaluator.java): `fraud-service/src/main/java/com/persou/antifraud/fraud/domain/service/FraudRuleEvaluator.java`
- [Frequency history](https://github.com/jessicapersou/fraud-detection-sdd/blob/main/fraud-service/src/main/java/com/persou/antifraud/fraud/adapter/out/persistence/JpaTransactionFrequencyAdapter.java): `fraud-service/src/main/java/com/persou/antifraud/fraud/adapter/out/persistence/JpaTransactionFrequencyAdapter.java`
- [Analysis store](https://github.com/jessicapersou/fraud-detection-sdd/blob/main/fraud-service/src/main/java/com/persou/antifraud/fraud/adapter/out/persistence/JpaFraudAnalysisAdapter.java): `fraud-service/src/main/java/com/persou/antifraud/fraud/adapter/out/persistence/JpaFraudAnalysisAdapter.java`
- [Alert publisher](https://github.com/jessicapersou/fraud-detection-sdd/blob/main/fraud-service/src/main/java/com/persou/antifraud/fraud/adapter/out/kafka/KafkaFraudAlertPublisher.java): `fraud-service/src/main/java/com/persou/antifraud/fraud/adapter/out/kafka/KafkaFraudAlertPublisher.java`

### Alert notifications

- [Fraud alert listener](https://github.com/jessicapersou/fraud-detection-sdd/blob/main/notification-service/src/main/java/com/persou/antifraud/notification/adapter/in/kafka/FraudAlertListener.java): `notification-service/src/main/java/com/persou/antifraud/notification/adapter/in/kafka/FraudAlertListener.java`
- [Process alert](https://github.com/jessicapersou/fraud-detection-sdd/blob/main/notification-service/src/main/java/com/persou/antifraud/notification/application/usecase/ProcessFraudAlertService.java): `notification-service/src/main/java/com/persou/antifraud/notification/application/usecase/ProcessFraudAlertService.java`
- [Notification store](https://github.com/jessicapersou/fraud-detection-sdd/blob/main/notification-service/src/main/java/com/persou/antifraud/notification/adapter/out/persistence/JpaNotificationRepositoryAdapter.java): `notification-service/src/main/java/com/persou/antifraud/notification/adapter/out/persistence/JpaNotificationRepositoryAdapter.java`
- [Notification provider](https://github.com/jessicapersou/fraud-detection-sdd/blob/main/notification-service/src/main/java/com/persou/antifraud/notification/adapter/out/mail/SmtpNotificationProvider.java): `notification-service/src/main/java/com/persou/antifraud/notification/adapter/out/mail/SmtpNotificationProvider.java`

### Event contracts

- [Transaction event](https://github.com/jessicapersou/fraud-detection-sdd/blob/main/event-contracts/src/main/java/com/persou/antifraud/contracts/TransactionCreatedEvent.java): `event-contracts/src/main/java/com/persou/antifraud/contracts/TransactionCreatedEvent.java`
- [Fraud alert event](https://github.com/jessicapersou/fraud-detection-sdd/blob/main/event-contracts/src/main/java/com/persou/antifraud/contracts/FraudDetectedEvent.java): `event-contracts/src/main/java/com/persou/antifraud/contracts/FraudDetectedEvent.java`

### Other components

- **API client**
- **Kafka**

## Connections

- API client → Transaction REST: submits transaction (evidence: `README.md`)
- Transaction REST → Receive transaction: invokes (evidence: `transaction-service/src/main/java/com/persou/antifraud/transaction/adapter/in/rest/TransactionController.java`)
- Receive transaction → Idempotency store: checks and reserves (evidence: `transaction-service/src/main/java/com/persou/antifraud/transaction/application/usecase/ReceiveTransactionService.java`)
- Receive transaction → Transaction store: saves transaction (evidence: `transaction-service/src/main/java/com/persou/antifraud/transaction/application/usecase/ReceiveTransactionService.java`)
- Receive transaction → Outbox store: saves event (evidence: `transaction-service/src/main/java/com/persou/antifraud/transaction/application/usecase/ReceiveTransactionService.java`)
- Outbox publisher → Outbox store: publishes pending
- Outbox publisher → Kafka: publishes event (evidence: `README.md`)
- Kafka → Transaction listener: delivers event (evidence: `README.md`)
- Transaction listener → Analyze transaction: dispatches
- Analyze transaction → Frequency history: records and counts (evidence: `fraud-service/src/main/java/com/persou/antifraud/fraud/application/usecase/AnalyzeTransactionService.java`)
- Analyze transaction → Fraud rules: evaluates findings (evidence: `fraud-service/src/main/java/com/persou/antifraud/fraud/application/usecase/AnalyzeTransactionService.java`)
- Analyze transaction → Analysis store: stores analysis (evidence: `fraud-service/src/main/java/com/persou/antifraud/fraud/application/usecase/AnalyzeTransactionService.java`)
- Analyze transaction → Alert publisher: publishes qualifying alert (evidence: `fraud-service/src/main/java/com/persou/antifraud/fraud/application/usecase/AnalyzeTransactionService.java`)
- Alert publisher → Kafka: publishes alert (evidence: `README.md`)
- Kafka → Fraud alert listener: delivers alert (evidence: `README.md`)
- Fraud alert listener → Process alert: dispatches
- Process alert → Notification store: records attempts (evidence: `notification-service/src/main/java/com/persou/antifraud/notification/application/usecase/ProcessFraudAlertService.java`)
- Process alert → Notification provider: sends notification (evidence: `notification-service/src/main/java/com/persou/antifraud/notification/application/usecase/ProcessFraudAlertService.java`)
