# atomfinger/javazone-2024 architecture

> Architecture diagram of the GitHub repository atomfinger/javazone-2024, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/atomfinger/javazone-2024
- Repository: https://github.com/atomfinger/javazone-2024

## Overview

##### Project Type & Purpose
- This is a single “BookStoreService” microservice implemented as a multi‐module Gradle project that exposes a web API (module “web”), contains domain logic (“service”), persistence code (“persistence”), and integration glue (“integration”), plus a standalone Kafka listener service (“kafka”) and an example stub service for contract tests (“external_orderservice”). The service’s responsibility is to manage books: listing, adding, and integrating with inventory, ordering, and review systems.

##### Key Architectural Layers / Components
a. Web API Layer (“web” module)
- Spring Boot REST controllers handle HTTP requests (BookController).
- Exposes endpoints to clients (e.g., listBooks, addBook).
b. Domain Layer (“service” module)
- Business logic lives in BookService.
- Orchestrates calls to persistence and integration clients.
c. Persistence Layer (“persistence” module)
- JPA entities (Book) and Spring Data repository.
- Database migrations (Flyway or SQL scripts).
d. Integration Layer (“integration” module)
- HTTP clients for BestReads, InventoryService, OrderService.
- Kafka producer for BookCreated events.
- Configured via Spring Cloud Contract stubs for contract testing.
e. Kafka Listener Service (“kafka” module)
- Separate Spring Boot app that consumes AddBook messages.
- Demonstrates event-driven handling (AddBookListener).
f. External Order Service Stub (“external_orderservice” module)
- Provides contract stubs & generated tests for OrderService.

##### External Systems
- InventoryService (HTTP API)
- OrderService (HTTP API, stubbed locally via contract)
- BestReads (HTTP API)
- Kafka cluster
- SQL database (PostgreSQL via TestContainers in tests)

##### Interactions & Data Flow
- Client → Web API → Domain (BookService)
- Domain → Persistence → Database
- Domain → Integration HTTP clients → External services
- Domain → Kafka producer → Kafka topic “book‐created”
- Kafka listener (separate service) consumes “add_book” messages → persists to DB
- Contract test runner and TestContainers spin up stubbed services, DB, and Kafka for CI

##### Architectural Patterns & Principles
- Layered architecture (Presentation, Domain, Persistence, Integration)
- Hexagonal/Ports & Adapters: modules act as adapters to external systems
- Consumer/Producer event‐driven pattern via Kafka
- Contract testing with Spring Cloud Contract
- TestContainers for ephemeral dependencies
- ApprovalTests for API response validation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        Client["Frontend Client"]:::presentation
    end

    %% Web API Layer
    subgraph "Web API (web module)" 
        direction TB
        BookController["BookController\n(Spring Boot REST)"]:::presentation
        ApplicationWeb["Application.java"]:::presentation
    end

    %% Domain Layer
    subgraph "Domain Layer (service module)" 
        direction TB
        BookService["BookService\n(Business Logic)"]:::domain
    end

    %% Persistence Layer
    subgraph "Persistence Layer (persistence module)" 
        direction TB
        BookEntity["Book.java\n(JPA Entity)"]:::persistence
        BookRepository["BookRepository\n(Spring Data)"]:::persistence
        PersistenceConfig["PersistenceConfig.java"]:::persistence
        Migrations["V1__initial_version.sql\n(DB Migrations)"]:::persistence
        Database[(PostgreSQL)]:::database
    end

    %% Integration Layer
    subgraph "Integration Layer (integration module)" 
        direction TB
        BestReadsIntegration["BestReadsServiceIntegration"]:::integration
        InventoryIntegration["InventoryServiceIntegration"]:::integration
        OrderIntegration["OrderServiceIntegration"]:::integration
        BookCreatedProducer["BookCreatedMessageProducer\n(Kafka Producer)"]:::integration
        KafkaCluster[(Kafka Cluster)]:::messaging
        ExternalInventory["InventoryService\n(HTTP API)"]:::external
        ExternalBestReads["BestReads\n(HTTP API)"]:::external
        ExternalOrder["OrderService\n(HTTP API)"]:::external
    end

    %% Kafka Listener Service
    subgraph "Kafka Listener (kafka module)" 
        direction TB
        AddBookListener["AddBookListener"]:::messaging
        AddBookMessage["AddBookMessage"]:::messaging
        KafkaConfig["KafkaConfiguration.java"]:::messaging
    end

    %% External Order Service Stub
    subgraph "Test Stub (external_orderservice module)" 
        direction TB
        OrderServiceContract["order_service_contract.groovy"]:::test
        TestRunner["Test Runner"]:::test
    end

    %% Flows
    Client -->|"HTTP"| BookController
    BookController -->|"calls"| BookService
    BookService -->|"JDBC"| BookRepository
    BookRepository -->|"persists"| Database
    BookService -->|"uses"| BestReadsIntegration
    BookService -->|"uses"| InventoryIntegration
    BookService -->|"uses"| OrderIntegration
    BestReadsIntegration -->|"HTTP"| ExternalBestReads
    InventoryIntegration -->|"HTTP"| ExternalInventory
    OrderIntegration -->|"HTTP"| ExternalOrder
    BookService -->|"publishes"| BookCreatedProducer
    BookCreatedProducer -->|"Kafka"| KafkaCluster
    KafkaCluster -->|"consumes"| AddBookListener
    AddBookListener -->|"handles"| AddBookMessage
    AddBookListener -->|"persists"| Database
    TestRunner -->|"contracts"| OrderServiceContract
    OrderServiceContract -->|"stubs"| ExternalOrder
    TestRunner -->|"TestContainers"| Database
    TestRunner -->|"TestContainers"| KafkaCluster

    %% Click Events
    click BookController "https://github.com/atomfinger/javazone-2024/blob/main/web/src/main/java/io/github/atomfinger/javazone/bookstore/controller/BookController.java"
    click ApplicationWeb "https://github.com/atomfinger/javazone-2024/blob/main/web/src/main/java/io/github/atomfinger/javazone/bookstore/Application.java"
    click BookService "https://github.com/atomfinger/javazone-2024/blob/main/service/src/main/java/io/github/atomfinger/javazone/bookstore/service/BookService.java"
    click BookEntity "https://github.com/atomfinger/javazone-2024/blob/main/persistence/src/main/java/io/github/atomfinger/javazone/bookstore/persistence/entities/Book.java"
    click BookRepository "https://github.com/atomfinger/javazone-2024/blob/main/persistence/src/main/java/io/github/atomfinger/javazone/bookstore/persistence/repository/BookRepository.java"
    click PersistenceConfig "https://github.com/atomfinger/javazone-2024/blob/main/persistence/src/main/java/io/github/atomfinger/javazone/bookstore/persistence/configuration/PersistenceConfig.java"
    click Migrations "https://github.com/atomfinger/javazone-2024/blob/main/persistence/src/main/resources/db/migrations/V1__initial_version.sql"
    click BestReadsIntegration "https://github.com/atomfinger/javazone-2024/blob/main/integration/src/main/java/io/github/atomfinger/javazone/bookstore/integration/web/BestReadsServiceIntegration.java"
    click InventoryIntegration "https://github.com/atomfinger/javazone-2024/blob/main/integration/src/main/java/io/github/atomfinger/javazone/bookstore/integration/web/InventoryServiceIntegration.java"
    click OrderIntegration "https://github.com/atomfinger/javazone-2024/blob/main/integration/src/main/java/io/github/atomfinger/javazone/bookstore/integration/web/OrderServiceIntegration.java"
    click BookCreatedProducer "https://github.com/atomfinger/javazone-2024/blob/main/integration/src/main/java/io/github/atomfinger/javazone/bookstore/integration/kafka/BookCreatedMessageProducer.java"
    click KafkaConfig "https://github.com/atomfinger/javazone-2024/blob/main/kafka/src/main/java/io/github/atomfinger/javazone/bookstore/kafka/configuration/KafkaConfiguration.java"
    click AddBookListener "https://github.com/atomfinger/javazone-2024/blob/main/kafka/src/main/java/io/github/atomfinger/javazone/bookstore/kafka/add_book_listener/AddBookListener.java"
    click AddBookMessage "https://github.com/atomfinger/javazone-2024/blob/main/kafka/src/main/java/io/github/atomfinger/javazone/bookstore/kafka/add_book_listener/AddBookMessage.java"
    click OrderServiceContract "https://github.com/atomfinger/javazone-2024/blob/main/external_orderservice/src/test/resources/contracts/bookstore/orderservice/order_service_contract.groovy"

    %% Styles
    classDef presentation fill:#cfe2f3,stroke:#036; 
    classDef domain fill:#d9ead3,stroke:#060; 
    classDef persistence fill:#ffe599,stroke:#aa5500; 
    classDef integration fill:#d0baff,stroke:#6600aa; 
    classDef messaging fill:#fff2cc,stroke:#997300; 
    classDef external fill:#f4cccc,stroke:#a00; 
    classDef database fill:#d9d2e9,stroke:#5a2a83; 
    classDef test fill:#e2e2e2,stroke:#999;
```
