Explicit Architecture: Integrating Hexagonal, Onion, Clean, and CQRS Patterns

Explicit Architecture

This article is part of a software architecture chronicle series where the author shares personal insights on software design and architecture after transitioning from teaching to full‑time development.

System Basic Modules

The author revisits the EBI (Entity‑Boundary‑Interactor) and Ports‑and‑Adapters architecture, emphasizing three fundamental code blocks: the user‑interface layer, the business‑logic core, and the infrastructure layer that connects the core to databases, search engines, or third‑party APIs.

The application core is the code that actually performs work, independent of the UI that triggers it.

Tools

Tools such as database engines, search engines, web servers, or CLI consoles are external to the core but are essential for the application. The distinction is that a CLI or web server *invokes* the application, while a database *is invoked* by the application.

Connecting Tools to the Core

Adapters (primary/driver and secondary/driven) implement ports to translate between the core and external tools. Ports are interfaces that belong to the business logic, while adapters belong to the outside world.

Ports

Ports define how the core uses a tool or how a tool uses the core, typically expressed as interfaces (or a set of interfaces and DTOs).

Primary (Driver) Adapters

These adapters wrap a port and convert input from delivery mechanisms (e.g., HTTP requests, CLI commands) into method calls on the core.

Secondary (Driven) Adapters

These adapters implement a port and are injected into the core wherever the port is required, allowing the core to remain agnostic of concrete tool implementations.

Inversion of Control

The core depends only on ports (abstractions), while adapters depend on both ports and concrete tools, achieving a dependency direction toward the center of the architecture.

Application Core Organization

The Onion architecture combines DDD layers with ports‑and‑adapters, forming concentric circles where dependencies point inward.

Application Layer

Contains use‑case services, ports, and adapters (e.g., repository, search, messaging interfaces). Commands and queries are handled here, either directly or via a command/query bus.

Domain Layer

Houses domain services, the domain model (entities, value objects, enums), and domain events. Domain services encapsulate business logic that spans multiple entities.

Components

Beyond fine‑grained code isolation, components (e.g., authentication, billing) provide coarse‑grained modularity. Each component may have its own data store or share data via read‑only queries, and components communicate through events or discovery services.

Decoupled Components

Components avoid direct references to each other, using event dispatchers or service discovery to remain loosely coupled while still sharing a minimal common kernel.

Control Flow

The flow proceeds from UI → core → infrastructure → back to core → UI. Diagrams illustrate both scenarios: without a command/query bus (controllers call services directly) and with a bus (controllers dispatch commands/queries to handlers).

Conclusion

The goal is a loosely‑coupled, highly‑cohesive codebase that can be modified quickly and safely, while remembering that these diagrams are guidelines; real architecture must be shaped by concrete business needs.

计划是没有价值的，但计划就是一切。

-------------------------------艾森豪威尔

地图不是领土。

-----------------------阿尔弗雷德Korzybski