# yoandypv/spring-boot-kafka-basics architecture

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

- Interactive diagram: https://gitdiagram.com/yoandypv/spring-boot-kafka-basics
- Repository: https://github.com/yoandypv/spring-boot-kafka-basics

## Overview

##### Project Type and Purpose
- This is a microservices demo consisting of two independent Spring Boot applications (“Customers” and “Notifications”) that communicate asynchronously via Apache Kafka.
- The “Customers” service exposes a REST API to create new customers. Upon creation, it publishes a CustomerCreatedEvent to a Kafka topic. The “Notifications” service consumes that event to perform further processing (e.g., sending emails, logging, etc.).

##### File‐structure Analysis
- Top level: `README.md`, plus two sibling folders: `customers/` and `notifications/`.
- Each folder is a standalone Maven + Spring Boot project, with the usual Maven wrapper and `pom.xml`.
- Inside each service:
- `config/` (Kafka producer/consumer configuration)
- `entity/` (Customer domain object)
- `events/` (shared event definitions: `Event`, `EventType`, `CustomerCreatedEvent`)
- `service/` (business logic + event publishing or consuming)
- `web/` (for Customers: REST controller)
- No database or repository layers are present, so state persistence is out of scope in this example.

##### Insights from README
- Confirms the roles: Customers = Kafka producer, Notifications = Kafka consumer.
- Goal is to illustrate asynchronous communication between microservices.

a. Main Components
- Customers Service
- REST API (CustomerController)
- Business Logic (CustomerService)
- Event Publisher (CustomerEventsService + KafkaProducer)
- Apache Kafka Cluster (brokers + topics; optionally Zookeeper)
- Notifications Service
- Kafka Consumer (CustomerEventsService + KafkaConsumer)
- Processing Logic (could represent NotificationService)

b. Relationships and Data Flow
1. Client → Customers Service (HTTP POST /customers)
2. Customers Service handles request → CustomerController → CustomerService
3. CustomerService invokes CustomerEventsService → serializes event
4. KafkaProducer sends `CustomerCreatedEvent` to `customer.events` topic
5. Notifications Service’s KafkaConsumer subscribes to same topic
6. On event arrival → NotificationEventHandler processes the event

c. Architectural Patterns and Principles
- Microservices pattern: two loosely coupled Spring Boot applications
- Asynchronous messaging via event-driven architecture
- Single responsibility: each service has its own bounded context
- Shared kernel for event definitions to enforce schema compatibility

d. Key Technologies
- Java + Spring Boot
- Apache Kafka (producers + consumers configured via `KafkaProducerConfig` / `KafkaConsumerConfig`)
- Maven build system
- JSON or Avro (depending on configuration) for event serialization

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["Client"]:::external

    %% Customers Service
    subgraph "Customers Service"
        direction TB
        CustomersService["Customers Service"]:::service
        CustomersApp["CustomersApplication"]:::service
        CustomerController["CustomerController"]:::api
        CustomerServiceNode["CustomerService"]:::internal
        PubService["CustomerEventsService"]:::internal
        ProducerConfig["KafkaProducerConfig"]:::infra
        CustomerEntity["Customer"]:::data
        EventBase["Event"]:::data
        EventType["EventType"]:::data
        CustomerCreatedEvent["CustomerCreatedEvent"]:::data
    end

    %% Kafka Cluster
    Kafka["Kafka Cluster"]:::infra

    %% Notifications Service
    subgraph "Notifications Service"
        direction TB
        NotificationsService["Notifications Service"]:::service
        NotificationsApp["NotificationsApplication"]:::service
        ConsumerConfig["KafkaConsumerConfig"]:::infra
        SubService["CustomerEventsService"]:::internal
        NotificationService["NotificationService"]:::internal
        CustomerEntityNotif["Customer"]:::data
        EventBaseNotif["Event"]:::data
        EventTypeNotif["EventType"]:::data
        CustomerCreatedEventNotif["CustomerCreatedEvent"]:::data
    end

    %% Connections - Customers Flow
    Client -->|"POST /customers"| CustomerController
    CustomerController -->|"invokes"| CustomerServiceNode
    CustomerController -->|"uses"| CustomerEntity
    CustomerServiceNode -->|"calls"| PubService
    PubService -->|"uses"| ProducerConfig
    PubService -->|"serializes"| CustomerCreatedEvent
    PubService -->|"CustomerCreatedEvent"| Kafka

    %% Connections - Kafka to Notifications
    Kafka -->|"CustomerCreatedEvent"| SubService
    SubService -->|"uses"| ConsumerConfig
    SubService -->|"processes"| NotificationService
    NotificationService -->|"uses"| CustomerEntityNotif

    %% Click Events - Customers
    click CustomersService "https://github.com/yoandypv/spring-boot-kafka-basics/tree/main/customers/"
    click CustomersApp "https://github.com/yoandypv/spring-boot-kafka-basics/blob/main/customers/src/main/java/com/sacavix/CustomersApplication.java"
    click CustomerController "https://github.com/yoandypv/spring-boot-kafka-basics/blob/main/customers/src/main/java/com/sacavix/web/CustomerController.java"
    click CustomerServiceNode "https://github.com/yoandypv/spring-boot-kafka-basics/blob/main/customers/src/main/java/com/sacavix/service/CustomerService.java"
    click PubService "https://github.com/yoandypv/spring-boot-kafka-basics/blob/main/customers/src/main/java/com/sacavix/service/CustomerEventsService.java"
    click ProducerConfig "https://github.com/yoandypv/spring-boot-kafka-basics/blob/main/customers/src/main/java/com/sacavix/config/KafkaProducerConfig.java"
    click CustomerEntity "https://github.com/yoandypv/spring-boot-kafka-basics/blob/main/customers/src/main/java/com/sacavix/entity/Customer.java"
    click EventBase "https://github.com/yoandypv/spring-boot-kafka-basics/blob/main/customers/src/main/java/com/sacavix/events/Event.java"
    click EventType "https://github.com/yoandypv/spring-boot-kafka-basics/blob/main/customers/src/main/java/com/sacavix/events/EventType.java"
    click CustomerCreatedEvent "https://github.com/yoandypv/spring-boot-kafka-basics/blob/main/customers/src/main/java/com/sacavix/events/CustomerCreatedEvent.java"

    %% Click Events - Notifications
    click NotificationsService "https://github.com/yoandypv/spring-boot-kafka-basics/tree/main/notifications/"
    click NotificationsApp "https://github.com/yoandypv/spring-boot-kafka-basics/blob/main/notifications/src/main/java/com/sacavix/NotificationsApplication.java"
    click ConsumerConfig "https://github.com/yoandypv/spring-boot-kafka-basics/blob/main/notifications/src/main/java/com/sacavix/config/KafkaConsumerConfig.java"
    click SubService "https://github.com/yoandypv/spring-boot-kafka-basics/blob/main/notifications/src/main/java/com/sacavix/service/CustomerEventsService.java"
    click CustomerEntityNotif "https://github.com/yoandypv/spring-boot-kafka-basics/blob/main/notifications/src/main/java/com/sacavix/entity/Customer.java"
    click EventBaseNotif "https://github.com/yoandypv/spring-boot-kafka-basics/blob/main/notifications/src/main/java/com/sacavix/events/Event.java"
    click EventTypeNotif "https://github.com/yoandypv/spring-boot-kafka-basics/blob/main/notifications/src/main/java/com/sacavix/events/EventType.java"
    click CustomerCreatedEventNotif "https://github.com/yoandypv/spring-boot-kafka-basics/blob/main/notifications/src/main/java/com/sacavix/events/CustomerCreatedEvent.java"

    %% Styles
    classDef external fill:#d9d9d9,stroke:#333,stroke-width:1px;
    classDef service fill:#a6cee3,stroke:#333,stroke-width:1px;
    classDef api fill:#b3cde0,stroke:#333,stroke-width:1px;
    classDef internal fill:#c7e9c0,stroke:#333,stroke-width:1px;
    classDef infra fill:#fccde5,stroke:#333,stroke-width:1px;
    classDef data fill:#fdae61,stroke:#333,stroke-width:1px;
```
