# zakariaalla/event-driven-architecture-kafka architecture

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

- Interactive diagram: https://gitdiagram.com/zakariaalla/event-driven-architecture-kafka
- Repository: https://github.com/zakariaalla/event-driven-architecture-kafka

## Overview

##### Project Type and Purpose
- This is an event-driven, microservices-based system built with Spring Boot and Apache Kafka.
- Four deployable units:
- Order Service (produces events)
- Stock Service (consumes and processes events, persists to PostgreSQL)
- Email Service (consumes events and sends emails)
- Base-domains Service (shared DTOs and domain types library)

##### Main Components
- Kafka Cluster (one or more brokers)
- Topic: “orders” (or similar)
- Microservices (Spring Boot apps)
- Order Service
- Stock Service
- Email Service
- Shared Library
- Base-domains (contains Order, OrderEvent DTOs)
- Database
- PostgreSQL (used by Stock Service)

##### Relationships & Data Flow
1. Client or external system → Order Service REST API (OrderController)
2. Order Service → serializes OrderEvent → publishes to Kafka topic
3. Kafka topic → fan-out to consumers (Stock Service & Email Service)
4. Stock Service consumes the event → maps DTO to Entity → persists OrderEntity in PostgreSQL
5. Email Service consumes the event → sends email to customer
6. All services depend on Base-domains for shared types

##### Architectural Patterns & Principles
- Microservices: Each service runs in its own process, has its own codebase and data store (only Stock Service uses a DB).
- Event-Driven: Asynchronous communication via Kafka topic; loose coupling between producer and consumers.
- Shared Kernel (Domain Library): Base-domains is a shared module for keeping DTOs in sync.
- Single Responsibility: Each service focuses on one bounded context (orders, stock, email).

##### Technologies & Frameworks to Call Out
- Spring Boot (embedded server, auto-configuration)
- Spring Kafka (KafkaTemplate for producer, @KafkaListener for consumer)
- Spring Data JPA / Hibernate (in Stock Service)
- Apache Kafka (message broker, topics, producers, consumers)
- PostgreSQL (relational store for Stock Service)
- Maven (build, manage dependencies)

##### Essential Elements Checklist
- [ ] Kafka cluster & “order-events” topic

## Diagram (Mermaid)

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

    %% Shared Library
    subgraph "Base-domains (shared)"
        BDApp["BaseDomainsApplication.java"]:::library
        DTO["DTOs: Order.java, OrderEvent.java"]:::library
    end

    %% Order Service
    subgraph "Order Service"
        OSApp["OrderServiceApplication.java"]:::service
        Controller["OrderController.java"]:::service
        Producer["OrderProducer.java"]:::service
        OSService["OrderService.java"]:::service
        OSConfig["KafkaTopicConfig.java"]:::service
        OSProps["application.properties"]:::service
    end

    %% Kafka Cluster
    Kafka["Kafka Cluster\n(order-events topic)"]:::kafka

    %% Stock Service
    subgraph "Stock Service"
        SSApp["StockServiceApplication.java"]:::service
        ConsumerSS["OrderConsumer.java"]:::service
        Mapper["OrderMapper.java"]:::service
        Entity["OrderEntity.java"]:::service
        Repo["OrderRepository.java"]:::service
        SSProps["application.properties"]:::service
    end

    %% Email Service
    subgraph "Email Service"
        ESApp["EmailServiceApplication.java"]:::service
        ConsumerES["OrderConsumer.java"]:::service
        EmailIface["EmailService.java"]:::service
        EmailImpl["EmailServceImpl.java"]:::service
        ESProps["application.properties"]:::service
    end

    %% Database
    DB["PostgreSQL\n(stock_db)"]:::db

    %% Data Flows
    Client -->|HTTP/JSON| Controller
    Controller -->|invoke| OSService
    OSService -->|produce JSON OrderEvent| Producer
    Producer -->|"publish JSON OrderEvent"| Kafka
    Kafka -->|"consume OrderEvent"| ConsumerSS
    Kafka -->|"consume OrderEvent"| ConsumerES
    ConsumerSS --> Mapper
    Mapper --> Entity
    Entity --> Repo
    Repo -->|"persist"| DB
    ConsumerES -->|"trigger email"| EmailIface
    EmailIface --> EmailImpl

    %% Shared Dependency
    OSApp --> BDApp
    SSApp --> BDApp
    ESApp --> BDApp

    %% Click Events
    click BDApp "https://github.com/zakariaalla/event-driven-architecture-kafka/blob/master/base-domains/src/main/java/net/zakariaservices/basedomains/BaseDomainsApplication.java"
    click DTO "https://github.com/zakariaalla/event-driven-architecture-kafka/tree/master/base-domains/src/main/java/net/zakariaservices/basedomains/dto/"
    click OSApp "https://github.com/zakariaalla/event-driven-architecture-kafka/blob/master/order-service/src/main/java/net/zakariaservices/orderservice/OrderServiceApplication.java"
    click Controller "https://github.com/zakariaalla/event-driven-architecture-kafka/blob/master/order-service/src/main/java/net/zakariaservices/orderservice/controller/OrderController.java"
    click Producer "https://github.com/zakariaalla/event-driven-architecture-kafka/blob/master/order-service/src/main/java/net/zakariaservices/orderservice/kafka/OrderProducer.java"
    click OSService "https://github.com/zakariaalla/event-driven-architecture-kafka/blob/master/order-service/src/main/java/net/zakariaservices/orderservice/service/OrderService.java"
    click OSConfig "https://github.com/zakariaalla/event-driven-architecture-kafka/blob/master/order-service/src/main/java/net/zakariaservices/orderservice/config/KafkaTopicConfig.java"
    click OSProps "https://github.com/zakariaalla/event-driven-architecture-kafka/blob/master/order-service/src/main/resources/application.properties"
    click SSApp "https://github.com/zakariaalla/event-driven-architecture-kafka/blob/master/stock-service/src/main/java/net/zakariaservices/stockservice/StockServiceApplication.java"
    click ConsumerSS "https://github.com/zakariaalla/event-driven-architecture-kafka/blob/master/stock-service/src/main/java/net/zakariaservices/stockservice/kafka/OrderConsumer.java"
    click Mapper "https://github.com/zakariaalla/event-driven-architecture-kafka/blob/master/stock-service/src/main/java/net/zakariaservices/stockservice/mapper/OrderMapper.java"
    click Entity "https://github.com/zakariaalla/event-driven-architecture-kafka/blob/master/stock-service/src/main/java/net/zakariaservices/stockservice/persistence/entities/OrderEntity.java"
    click Repo "https://github.com/zakariaalla/event-driven-architecture-kafka/blob/master/stock-service/src/main/java/net/zakariaservices/stockservice/persistence/repositories/OrderRepository.java"
    click SSProps "https://github.com/zakariaalla/event-driven-architecture-kafka/blob/master/stock-service/src/main/resources/application.properties"
    click ESApp "https://github.com/zakariaalla/event-driven-architecture-kafka/blob/master/email-service/src/main/java/net/zakariaservices/emailservice/EmailServiceApplication.java"
    click ConsumerES "https://github.com/zakariaalla/event-driven-architecture-kafka/blob/master/email-service/src/main/java/net/zakariaservices/emailservice/kafka/OrderConsumer.java"
    click EmailIface "https://github.com/zakariaalla/event-driven-architecture-kafka/blob/master/email-service/src/main/java/net/zakariaservices/emailservice/config/EmailService.java"
    click EmailImpl "https://github.com/zakariaalla/event-driven-architecture-kafka/blob/master/email-service/src/main/java/net/zakariaservices/emailservice/config/EmailServceImpl.java"
    click ESProps "https://github.com/zakariaalla/event-driven-architecture-kafka/blob/master/email-service/src/main/resources/application.properties"

    %% Styling
    classDef service fill:#AED6F1,stroke:#2980B9,stroke-width:1px
    classDef db fill:#ABEBC6,stroke:#27AE60,stroke-width:1px
    classDef kafka fill:#F5CBA7,stroke:#D35400,stroke-width:1px
    classDef library fill:#FADBD8,stroke:#C0392B,stroke-width:1px
    classDef external fill:#D5D8DC,stroke:#566573,stroke-width:1px
```
