# atillatan/kafka-microservices-and-transactions architecture

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

- Interactive diagram: https://gitdiagram.com/atillatan/kafka-microservices-and-transactions
- Repository: https://github.com/atillatan/kafka-microservices-and-transactions

## Overview

This is a Spring Boot trade-ingestion system: clients submit trades to a REST producer, which validates and asynchronously publishes them to Kafka; a consumer validates received trades and persists valid ones to PostgreSQL. Invalid consumer messages are routed to a dead-letter topic for separate listening. Producer-side exception advice formats rejected requests. The README documents a three-broker, three-partition scenario and transaction management. Some runtime wiring is documented rather than shown in sampled source, so those relationships cite the README; unsampled internals are not inferred.

Main entry points: [`src/consumer/src/main/java/com/tradingcorp/consumer/service/TradeConsumerServiceImpl.java`](https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/consumer/src/main/java/com/tradingcorp/consumer/service/TradeConsumerServiceImpl.java) (Consume and validate), [`src/producer/src/main/java/com/tradingcorp/producer/controller/TradeController.java`](https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/producer/src/main/java/com/tradingcorp/producer/controller/TradeController.java) (Trade REST API), [`src/producer/src/main/java/com/tradingcorp/producer/service/TradeProducerService.java`](https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/producer/src/main/java/com/tradingcorp/producer/service/TradeProducerService.java) (Validate and send), [`src/consumer/src/main/java/com/tradingcorp/consumer/service/KafkaConsumerConfig.java`](https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/consumer/src/main/java/com/tradingcorp/consumer/service/KafkaConsumerConfig.java) (Consumer configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_producer["Trade producer"]
  node_controller["Trade REST API"]
  node_producer_service["Validate and send"]
  node_producer_model["Trade payload<br/>[Trade.java]"]
  node_rest_advice["REST error advice"]
end

subgraph group_messaging["Kafka messaging"]
  node_producer_config["Kafka transaction config"]
  node_kafka["Kafka brokers and topics"]
  node_consumer_config["Consumer configuration"]
end

subgraph group_consumer["Trade consumer"]
  node_consumer_service["Consume and validate"]
  node_consumer_interface["Consumer contract"]
  node_consumer_model["Persistent trade entity<br/>[Trade.java]"]
  node_invalid_exception["Invalid trade exception"]
  node_error_handler["Dead-letter error handler"]
  node_dlt_listener["Dead-letter listener"]
end

subgraph group_persistence["Persistence"]
  node_repository["Trade repository"]
  node_postgres[("PostgreSQL")]
end

node_client(("Trade client"))

node_client -->|"submits trade"| node_controller
node_controller -->|"validates and sends"| node_producer_service
node_controller -->|"builds payload"| node_producer_model
node_controller -->|"raises invalid trade"| node_rest_advice
node_producer_service -->|"validates payload"| node_producer_model
node_producer_service -->|"publishes asynchronously"| node_kafka
node_producer_config -->|"configures producer"| node_kafka
node_kafka -->|"delivers trade records"| node_consumer_service
node_consumer_config -->|"configures listeners"| node_consumer_service
node_consumer_config -->|"registers handler"| node_error_handler
node_consumer_service -->|"implements contract"| node_consumer_interface
node_consumer_service -->|"validates and persists"| node_consumer_model
node_consumer_service -->|"rejects invalid trade"| node_invalid_exception
node_consumer_service -->|"saves valid trade"| node_repository
node_repository -->|"persists trades"| node_postgres
node_error_handler -->|"publishes failed record"| node_kafka
node_kafka -->|"delivers dead letters"| node_dlt_listener

click node_controller "https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/producer/src/main/java/com/tradingcorp/producer/controller/TradeController.java"
click node_producer_service "https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/producer/src/main/java/com/tradingcorp/producer/service/TradeProducerService.java"
click node_producer_model "https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/producer/src/main/java/com/tradingcorp/model/Trade.java"
click node_producer_config "https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/producer/src/main/java/com/tradingcorp/producer/KafkaProducerConfig.java"
click node_rest_advice "https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/producer/src/main/java/com/tradingcorp/producer/controller/TradeControllerAdvice.java"
click node_consumer_config "https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/consumer/src/main/java/com/tradingcorp/consumer/service/KafkaConsumerConfig.java"
click node_consumer_service "https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/consumer/src/main/java/com/tradingcorp/consumer/service/TradeConsumerServiceImpl.java"
click node_consumer_interface "https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/consumer/src/main/java/com/tradingcorp/consumer/service/TradeConsumerService.java"
click node_consumer_model "https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/consumer/src/main/java/com/tradingcorp/model/Trade.java"
click node_invalid_exception "https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/consumer/src/main/java/com/tradingcorp/model/InvalidTradeException.java"
click node_error_handler "https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/consumer/src/main/java/com/tradingcorp/consumer/service/TradeErrorHandler.java"
click node_repository "https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/consumer/src/main/java/com/tradingcorp/consumer/repository/TradeRepository.java"
click node_dlt_listener "https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/consumer/src/main/java/com/tradingcorp/consumer/service/TradeConsumerServiceImpl.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_producer_service,node_producer_model,node_rest_advice,node_client toneBlue
class node_producer_config,node_kafka,node_consumer_config toneAmber
class node_consumer_service,node_consumer_interface,node_consumer_model,node_invalid_exception,node_error_handler,node_dlt_listener toneMint
class node_repository,node_postgres toneRose
```

## Components

### Trade producer

- [Trade REST API](https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/producer/src/main/java/com/tradingcorp/producer/controller/TradeController.java): `src/producer/src/main/java/com/tradingcorp/producer/controller/TradeController.java`
- [Validate and send](https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/producer/src/main/java/com/tradingcorp/producer/service/TradeProducerService.java): `src/producer/src/main/java/com/tradingcorp/producer/service/TradeProducerService.java`
- [Trade payload](https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/producer/src/main/java/com/tradingcorp/model/Trade.java): `src/producer/src/main/java/com/tradingcorp/model/Trade.java`
- [REST error advice](https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/producer/src/main/java/com/tradingcorp/producer/controller/TradeControllerAdvice.java): `src/producer/src/main/java/com/tradingcorp/producer/controller/TradeControllerAdvice.java`

### Kafka messaging

- [Kafka transaction config](https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/producer/src/main/java/com/tradingcorp/producer/KafkaProducerConfig.java): `src/producer/src/main/java/com/tradingcorp/producer/KafkaProducerConfig.java`
- **Kafka brokers and topics**
- [Consumer configuration](https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/consumer/src/main/java/com/tradingcorp/consumer/service/KafkaConsumerConfig.java): `src/consumer/src/main/java/com/tradingcorp/consumer/service/KafkaConsumerConfig.java`

### Trade consumer

- [Consume and validate](https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/consumer/src/main/java/com/tradingcorp/consumer/service/TradeConsumerServiceImpl.java): `src/consumer/src/main/java/com/tradingcorp/consumer/service/TradeConsumerServiceImpl.java`
- [Consumer contract](https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/consumer/src/main/java/com/tradingcorp/consumer/service/TradeConsumerService.java): `src/consumer/src/main/java/com/tradingcorp/consumer/service/TradeConsumerService.java`
- [Persistent trade entity](https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/consumer/src/main/java/com/tradingcorp/model/Trade.java): `src/consumer/src/main/java/com/tradingcorp/model/Trade.java`
- [Invalid trade exception](https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/consumer/src/main/java/com/tradingcorp/model/InvalidTradeException.java): `src/consumer/src/main/java/com/tradingcorp/model/InvalidTradeException.java`
- [Dead-letter error handler](https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/consumer/src/main/java/com/tradingcorp/consumer/service/TradeErrorHandler.java): `src/consumer/src/main/java/com/tradingcorp/consumer/service/TradeErrorHandler.java`
- [Dead-letter listener](https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/consumer/src/main/java/com/tradingcorp/consumer/service/TradeConsumerServiceImpl.java): `src/consumer/src/main/java/com/tradingcorp/consumer/service/TradeConsumerServiceImpl.java`

### Persistence

- [Trade repository](https://github.com/atillatan/kafka-microservices-and-transactions/blob/main/src/consumer/src/main/java/com/tradingcorp/consumer/repository/TradeRepository.java): `src/consumer/src/main/java/com/tradingcorp/consumer/repository/TradeRepository.java`
- **PostgreSQL**

### Other components

- **Trade client**

## Connections

- Trade client → Trade REST API: submits trade (evidence: `README.md`)
- Trade REST API → Validate and send: validates and sends (evidence: `src/producer/src/main/java/com/tradingcorp/producer/controller/TradeController.java`)
- Trade REST API → Trade payload: builds payload (evidence: `src/producer/src/main/java/com/tradingcorp/producer/controller/TradeController.java`)
- Trade REST API → REST error advice: raises invalid trade (evidence: `src/producer/src/main/java/com/tradingcorp/producer/controller/TradeController.java`)
- Validate and send → Trade payload: validates payload (evidence: `src/producer/src/main/java/com/tradingcorp/producer/service/TradeProducerService.java`)
- Validate and send → Kafka brokers and topics: publishes asynchronously (evidence: `README.md`)
- Kafka transaction config → Kafka brokers and topics: configures producer (evidence: `src/producer/src/main/java/com/tradingcorp/producer/KafkaProducerConfig.java`)
- Kafka brokers and topics → Consume and validate: delivers trade records (evidence: `src/consumer/src/main/java/com/tradingcorp/consumer/service/TradeConsumerServiceImpl.java`)
- Consumer configuration → Consume and validate: configures listeners (evidence: `src/consumer/src/main/java/com/tradingcorp/consumer/service/KafkaConsumerConfig.java`)
- Consumer configuration → Dead-letter error handler: registers handler (evidence: `src/consumer/src/main/java/com/tradingcorp/consumer/service/KafkaConsumerConfig.java`)
- Consume and validate → Consumer contract: implements contract (evidence: `src/consumer/src/main/java/com/tradingcorp/consumer/service/TradeConsumerServiceImpl.java`)
- Consume and validate → Persistent trade entity: validates and persists (evidence: `src/consumer/src/main/java/com/tradingcorp/consumer/service/TradeConsumerServiceImpl.java`)
- Consume and validate → Invalid trade exception: rejects invalid trade (evidence: `src/consumer/src/main/java/com/tradingcorp/consumer/service/TradeConsumerServiceImpl.java`)
- Consume and validate → Trade repository: saves valid trade (evidence: `src/consumer/src/main/java/com/tradingcorp/consumer/service/TradeConsumerServiceImpl.java`)
- Trade repository → PostgreSQL: persists trades (evidence: `README.md`)
- Dead-letter error handler → Kafka brokers and topics: publishes failed record (evidence: `src/consumer/src/main/java/com/tradingcorp/consumer/service/TradeErrorHandler.java`)
- Kafka brokers and topics → Dead-letter listener: delivers dead letters (evidence: `src/consumer/src/main/java/com/tradingcorp/consumer/service/TradeConsumerServiceImpl.java`)
