# thepracticaldeveloper/kafka-spring-boot-example architecture

> Architecture diagram of the GitHub repository thepracticaldeveloper/kafka-spring-boot-example, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thepracticaldeveloper/kafka-spring-boot-example
- Repository: https://github.com/thepracticaldeveloper/kafka-spring-boot-example

## Overview

##### Project type and purpose
- This is a single-module Spring Boot back-end demo application whose sole purpose is to illustrate how to configure a Kafka producer and a consumer group (with three consumers) using Spring Boot’s auto-configuration.

##### File structure
- Top-level files:
- `pom.xml` (Maven build)
- `docker-compose.yml` (defines Kafka broker + ZooKeeper)
- `README.md` + `img/` (documentation)
- `src/main/java/io/tpd/kafkaexample`:
- `KafkaExampleApplication.java` (Spring Boot entry point)
- `HelloKafkaController.java` (REST controller that publishes messages)
- `PracticalAdvice.java` (service/bean that sends messages to Kafka)
- `src/main/resources/application.yml` (Kafka producer/consumer config: serializers, topic, group, partitions)
- `src/test/java/...` (standard Spring Boot integration test)

##### README for additional insights
- It describes three serialization types (JSON→POJO, plain String, byte[])

##### Main components
a. Spring Boot Application
– Controller Layer (HelloKafkaController)
– Service/Producer Bean (PracticalAdvice)
– Consumer Beans (three separate listeners in the same application, each in the same consumer group)
b. Apache Kafka Cluster
– Topic with three partitions
– ZooKeeper (for broker leadership election)
c. Docker Compose (external service orchestration)
d. Clients (e.g., `curl` or Postman) that send HTTP POST requests to the REST endpoint

##### Relationships and interactions
1. Client → HTTP POST → Spring Boot’s HelloKafkaController
2. Controller calls PracticalAdvice to format and send a message
3. PracticalAdvice autowired KafkaTemplate publishes to `my-topic`
4. Kafka distributes messages across 3 partitions
5. The Consumer Group (3 parallel listener beans) each receives messages from assigned partitions
6. Consumer beans process and log or further propagate the data

##### Architectural patterns & design principles
- Layered architecture (Controller → Service → Messaging)
- Asynchronous communication via Kafka (pub/sub)
- Consumer group parallelism (scalability)
- Externalized configuration (application.yml + Docker Compose)

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Client
  Client["Client (curl/Postman)"]:::client

  %% Spring Boot Application
  subgraph "Spring Boot Application"
    direction TB
    Entry["KafkaExampleApplication"]:::spring
    click Entry "https://github.com/thepracticaldeveloper/kafka-spring-boot-example/blob/master/src/main/java/io/tpd/kafkaexample/KafkaExampleApplication.java"
    Controller["HelloKafkaController"]:::spring
    click Controller "https://github.com/thepracticaldeveloper/kafka-spring-boot-example/blob/master/src/main/java/io/tpd/kafkaexample/HelloKafkaController.java"
    Producer["PracticalAdvice / KafkaTemplate"]:::spring
    click Producer "https://github.com/thepracticaldeveloper/kafka-spring-boot-example/blob/master/src/main/java/io/tpd/kafkaexample/PracticalAdvice.java"
    subgraph "Consumer Group (3 listeners)"
      direction TB
      C1["Consumer Listener 1"]:::spring
      C2["Consumer Listener 2"]:::spring
      C3["Consumer Listener 3"]:::spring
    end
  end

  %% Docker Compose with Kafka and ZooKeeper
  subgraph "Docker Compose"
    direction TB
    ZooKeeper["ZooKeeper"]:::kafka
    KafkaCluster["Kafka Cluster\nTopic: my-topic\nPartitions: 0,1,2"]:::kafka
  end

  %% External files/config
  Config["application.yml"]:::external
  click Config "https://github.com/thepracticaldeveloper/kafka-spring-boot-example/blob/master/src/main/resources/application.yml"
  POM["pom.xml"]:::external
  click POM "https://github.com/thepracticaldeveloper/kafka-spring-boot-example/blob/master/pom.xml"
  DockerComposeFile["docker-compose.yml"]:::external
  click DockerComposeFile "https://github.com/thepracticaldeveloper/kafka-spring-boot-example/blob/master/docker-compose.yml"
  Docs["README.md & img/"]:::external
  click Docs "https://github.com/thepracticaldeveloper/kafka-spring-boot-example/blob/master/README.md"
  Tests["Integration Tests"]:::external
  click Tests "https://github.com/thepracticaldeveloper/kafka-spring-boot-example/blob/master/src/test/java/io/tpd/kafkaexample/KafkaExampleApplicationTests.java"

  %% Relationships
  Client -->|"HTTP POST"| Controller
  Controller -->|"calls service"| Producer
  Producer -->|"publishes serialized JSON/String/bytes"| KafkaCluster
  KafkaCluster -->|"via Partition 0"| C1
  KafkaCluster -->|"via Partition 1"| C2
  KafkaCluster -->|"via Partition 2"| C3
  ZooKeeper --> KafkaCluster

  %% Styling
  classDef spring fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1
  classDef kafka fill:#FFE0B2,stroke:#FB8C00,color:#E65100
  classDef client fill:#C8E6C9,stroke:#43A047,color:#1B5E20
  classDef external fill:#E0E0E0,stroke:#9E9E9E,color:#424242
```
