Modular monolith with Quarkus - Supporting Hexagonal Architecture

[doogle-oss]

Over past 2 years spring team had been focussing on spring modulith project to provide a clear flow on how hexagonal architecture based applications can be built easily.

Is there some tutorial or details on the same to do in Quarkus.

I have come up with the following but i feel there is a need, may be a quarkus insights for this to clarify the right flow.

p.s. ofcourse part of it is by AI referencing my code with spring modulith flow

1. Recommended Project Structure

quarkus-modulith/
 ├── pom.xml                      # Parent POM
 ├── app-shell/                   # REST APIs, main Quarkus app
 ├── modules/
 │     ├── user-module/
 │     ├── order-module/
 │     ├── inventory-module/
 │     ├── payment-module/
 │     └── notification-module/
 └── architecture-tests/          # ArchUnit boundary checks

✔ Each module = one bounded context
✔ Modules do NOT call each other via direct Java dependency
✔ Modules communicate via CDI Events or Messaging (Kafka)

Option A — CDI Domain Events (recommended for monolith)

📌 Works exactly like Spring Modulith’s Domain Events.

Publish (order-module)

🔁 2. Module Communication Patterns (Internal)

@Inject
Event<OrderCreated> orderCreatedEvent;

public void placeOrder(Order order) {
    repo.save(order);
    orderCreatedEvent.fireAsync(new OrderCreated(order.id()));
}

Listen (notification-module)

@ApplicationScoped
public class OrderNotificationHandler {

    void onOrderCreated(@ObservesAsync OrderCreated event) {
        System.out.println("Notify customer for order " + event.orderId());
    }
}

Benefits

✔ Zero coupling
✔ Fully synchronous or async
✔ Easy to test
✔ Similar to Modulith EventRegistry

🧩 3. Module Structure Template (Example: order-module)

order-module/
 └── src/main/java/com/example/order
        ├── api/        # DTOs, public API
        ├── internal/   # Repositories, services, domain model
        ├── domain/     # Entities / Aggregates
        └── events/     # Domain events, listeners

Only api package is public

Everything under internal is private to module (enforced via ArchUnit).

📦 4. Main Application (app-shell)

app-shell is the only module exposing REST endpoints.

Example:

@Path("/orders")
public class OrderResource {

    @Inject
    OrderService orderService;

    @POST
    public Response place(OrderDto dto) {
        return Response.ok(orderService.place(dto)).build();
    }
}

Key rule:

➡️ REST controllers never exist inside individual modules
➡️ Only the shell exposes APIs

🧪 5. Enforcing Module Boundaries with ArchUnit

To simulate Spring Modulith’s boundary checks, add:

architecture-tests/src/test/java/ModuleBoundaryTest.java

public class ModuleBoundaryTest {

    @Test
    void modules_should_not_access_each_other_internal_packages() {
        JavaClasses classes = new ClassFileImporter().importPackages("com.example");

        noClasses()
            .that().resideOutsideOfPackages("..order.api..")
            .should().accessClassesThat().resideInAPackage("..order.internal..")
            .because("Order module internals should not be accessed by other modules")
            .check(classes);
    }
}

You can extend this for all modules.

🌐 6. External Communication (Kafka, REST, S3, etc.)

Use Kafka only for external cross-service events when needed.

Example Quarkus Kafka Listener:

@Incoming("payments")
public void process(PaymentSuccess event) {
    // forward as CDI domain event
}

⚡ 7. Quarkus Dev Productivity Advantages

Dev Mode (mvn quarkus:dev) → live reload modules
Native Build → faster than Spring Modulith if deployed as monolith
DevServices → automatic Postgres, Kafka, Redis containers per module
Quarkus Dev UI → visualize components and configs

flowchart TB

    subgraph APP_SHELL["🟦 App Shell (Quarkus Application)"]
        API["REST Controllers\nHTTP Entry Points"]
        CONFIG["Configuration / Security Filters"]
    end

    API --> ORDER_API
    API --> USER_API
    API --> INVENTORY_API
    API --> PAYMENT_API
    API --> NOTIF_API

    %% ORDER MODULE
    subgraph ORDER["🟩 Order Module"]
        ORDER_API["Order API\n(Public Interface)"]
        ORDER_INTERNAL["Order Internal\nDomain/Service/Repo"]
        ORDER_EVENTS["Order Events"]
    end

    %% USER MODULE
    subgraph USER["🟩 User Module"]
        USER_API["User API"]
        USER_INTERNAL["User Internal"]
    end

    %% INVENTORY MODULE
    subgraph INVENTORY["🟩 Inventory Module"]
        INVENTORY_API["Inventory API"]
        INVENTORY_INTERNAL["Inventory Internal"]
    end

    %% PAYMENT MODULE
    subgraph PAYMENT["🟩 Payment Module"]
        PAYMENT_API["Payment API"]
        PAYMENT_INTERNAL["Payment Internal"]
    end

    %% NOTIFICATION MODULE
    subgraph NOTIF["🟩 Notification Module"]
        NOTIF_API["Notification API"]
        NOTIF_INTERNAL["Notification Internal"]
    end

    %% CDI EVENTS
    ORDER_INTERNAL --> CDI_EVENT["🔄 CDI Event Bus"]
    PAYMENT_INTERNAL --> CDI_EVENT

    CDI_EVENT --> NOTIF_INTERNAL
    CDI_EVENT --> INVENTORY_INTERNAL
    CDI_EVENT --> PAYMENT_INTERNAL

    %% DATABASES
    ORDER_INTERNAL --> POSTGRES[(PostgreSQL)]
    USER_INTERNAL --> POSTGRES
    INVENTORY_INTERNAL --> POSTGRES
    PAYMENT_INTERNAL --> POSTGRES

    %% REDIS
    INVENTORY_INTERNAL --> REDIS[(Redis Cache)]

    %% KAFKA (Optional External Integration)
    PAYMENT_INTERNAL --> KAFKA[(Kafka Broker)]
    NOTIF_INTERNAL --> KAFKA

    %% STYLES
    style APP_SHELL fill:#dbeafe,stroke:#1e40af
    style ORDER fill:#dcfce7,stroke:#166534
    style USER fill:#dcfce7,stroke:#166534
    style INVENTORY fill:#dcfce7,stroke:#166534
    style PAYMENT fill:#dcfce7,stroke:#166534
    style NOTIF fill:#dcfce7,stroke:#166534
    style CDI_EVENT fill:#fff7ed,stroke:#b45309
    style POSTGRES fill:#e9d5ff,stroke:#6b21a8
    style REDIS fill:#fecaca,stroke:#b91c1c
    style KAFKA fill:#fef9c3,stroke:#ca8a04

Loading

[doogle-oss]

I did not know mermaid makes things so easy to explain 🥇

[cescoffier]

Thanks for sharing! Very interesting! Do you have concrete code we can look at?

[doogle-oss]

Let me create a sample and share.

[doogle-oss]

@cescoffier

quarkus-modulith - Example
Here you go, where order creation and notification are linked via cdi bus no dependency. Now it just needs to get expanded to every other module viz. Payments/User/Inventory which connect to external systems like redis/postgres/kafka or redpanda etc.

now for Order creation - it can publish event to Notification and to Payments if both are co hosted or only to Notification which will publish it to kafka for external payment system to act upon. Similarly inventory update can be done once payment is received and then a response event fired to order module to update the order to successful.

Ideally people get confused on building everything separately and stall the essence sometimes.

[doogle-oss]

Hexagonal architecture enforces a clear import dependency constraint known as the Dependency Rule: source code dependencies must always point inward toward the domain or business logic. This means code in the inner layers (like domain models and business rules) cannot import or depend on anything in outer layers (such as infrastructure, UI, or external adapters). Instead, the outer layers depend on abstractions (interfaces or ports) defined by the inner layers. This achieves a strict inversion of control where high-level modules do not depend on low-level modules; both depend on abstractions, and abstractions do not depend on details but vice versa.

[doogle-oss]

jmolecules
Also adding something like jmolecules to the setup makes the readablity standout in the whole process.

In spring if not using jmolecules DomainEvent etc.
Then plain use is

- ApplicationEventPublisher events, events.publishEvent(new OrderCompleted(order.getId()) 
- @ApplicationModuleListener are used.  

Similar to that in quarkus

- @Inject Event<OrderCreated> orderCreatedEvent , orderCreatedEvent.fireAsync(new OrderCreated(order.id()) 
-  @ObservesAsync