Overview

Want to apply Hexagonal Architecture with modern OOP languages? This tutorial teaches the Ports and Adapters pattern through 80 side-by-side annotated examples in Java 21+, Kotlin, and C# 12+.

What This Tutorial Is

This tutorial presents 80 examples showing identical hexagonal architecture concepts implemented three times in parallel — once in modern Java, once in idiomatic Kotlin, and once in modern C#. Seeing the same structural pattern expressed across three language idioms simultaneously sharpens your understanding of the pattern itself rather than any single language's syntax.

Each example demonstrates a focused hexagonal concept. Examples build progressively: the three-zone structure and basic port/adapter separation appear first, application service orchestration and infrastructure adapters follow, and strategic multi-context patterns close the tutorial. Every example follows a consistent five-part structure (see below).

Prerequisites

• Comfortable with at least one of Java, Kotlin, or C# at an intermediate level
• Familiar with OOP fundamentals: classes, interfaces, inheritance, and composition
• Has read the paradigm-agnostic overview at Hexagonal Architecture Overview

How to Read This Tutorial

This tutorial is code-first. Each example leads with working, self-contained code annotated with // => markers that show values, types, zones, and effects at each step.

Read one language deeply if you want to build fluency in that language's hexagonal idioms. Scan all three languages on each example if you want cross-language insight into how the same structural boundary maps onto different type systems and frameworks. Language contrasts are noted in examples where the difference matters to the hexagonal pattern.

The running domain across all examples is e-commerce order placement — the same system used in the DDD OOP tutorial. Using a single domain lets you see how hexagonal boundaries fit around the DDD building blocks.

What This Tutorial Covers

Core structural patterns:

• The three-zone model — domain core, application layer, adapters
• Input ports (driving ports) — use case interfaces called by adapters
• Output ports (driven ports) — repository, notification, and service interfaces called by the application
• Primary adapters — HTTP controllers, CLI handlers, message consumers
• Secondary adapters — database repositories, email senders, external API clients
• In-memory adapters — fast, deterministic implementations for tests
• Dependency injection wiring — Spring, ASP.NET Core DI, Koin

Intermediate patterns:

• CQRS with separate command/query ports
• Domain events and event publishing ports
• Clock, logger, configuration, and feature-flag ports
• Retry, circuit-breaker, and idempotency in adapters
• Multiple bounded contexts as separate hexagons
• Anti-Corruption Layer adapters between contexts

Advanced patterns:

• Bounded context maps — hexagon relationships
• Event sourcing port and adapter
• Saga orchestration
• Observability adapters (OpenTelemetry)
• Domain evolution — adding a new port without breaking the domain
• Adapter replacement without touching the domain

What This Tutorial Does NOT Cover

• Language tutorials: Java, Kotlin, and C# each have their own by-example tutorials for language fundamentals
• DDD tactical patterns in depth: read the DDD OOP tutorial for entities, aggregates, value objects, and domain services
• Framework setup and project bootstrapping (Spring Boot, ASP.NET Core, Ktor)
• Kubernetes, Docker, or deployment infrastructure

Sibling Tutorial: Functional Programming Approach

If you prefer a functional programming treatment of Hexagonal Architecture, see Hexagonal Architecture Using FP (F#) — By Example. That tutorial covers the same patterns through F# function type aliases, partial application, and Railway-Oriented Programming pipelines.

Structure of Each Example

Every example follows a consistent five-part format:

1. Brief Explanation: What hexagonal concept the example demonstrates (2–3 sentences).
2. Optional Diagram: A Mermaid diagram when concept relationships are complex enough to warrant visual representation. Skipped for straightforward code definitions.
3. Three Code Blocks: Java, Kotlin, and C# implementations with // => annotations explaining values, states, zones, and effects. Brief text between blocks notes meaningful language idiom differences.
4. Key Takeaway: The core hexagonal principle to retain (1–2 sentences).
5. Why It Matters: Real-world business and production system impact (50–100 words).

Tutorial Structure

• Beginner (Examples 1–25) — The three zones, port interfaces, adapter classes, package structure, dependency direction, in-memory adapters, application service wiring, and the full request/response flow.
• Intermediate (Examples 26–55) — CQRS ports, event publishing, infrastructure ports (clock, logger, cache), retry and circuit-breaker in adapters, ACL between contexts, saga orchestration, and integration testing strategies.
• Advanced (Examples 56–80) — Strategic multi-hexagon design, context maps, event sourcing, observability, domain evolution, adapter replacement, anti-patterns, and a full production reference architecture.