Hexagonal Architecture (Ports and Adapters) for Testable Compliance

Hexagonal Architecture, also known as Ports and Adapters (introduced by Alistair Cockburn), structures an application so that its core domain logic is completely isolated from external concerns — databases, APIs, user interfaces, messaging systems — through defined ports (interfaces) and adapters (implementations). The domain logic communicates only through these ports, meaning the core can be tested without any real infrastructure — no databases, no external services, no message brokers. For compliance-intensive applications, this architectural discipline provides a profound advantage: the compliance rules, validation logic, and regulatory constraints that live in the domain core can be exhaustively unit tested in milliseconds, producing a comprehensive automated test suite that serves as living documentation of compliance requirements.

Engineering hexagonal architectures for regulated systems requires explicit identification of the domain core as the compliance rule engine. Input adapters (REST controllers, message consumers, event handlers) translate external inputs into domain commands; the domain processes them using compliance rules; output adapters (database repositories, audit log writers, notification senders) persist results and evidence. The compliance audit log adapter is a critical output port: by making audit logging a first-class domain port, the architecture ensures that every compliance-relevant domain event is captured, regardless of which adapter implements the actual storage. This separation also means that audit storage can be upgraded (from a relational database to an immutable append-only store) without changing the compliance logic.

A key compliance benefit of hexagonal architecture is the testability of edge cases. Regulatory requirements often specify behavior at the boundaries — what happens when a transaction exactly equals a reporting threshold, when a patient consent is revoked mid-processing, when a payment fails validation at the last step of a multi-step process. In a hexagonally structured system, these edge cases can be expressed as unit tests that inject precisely crafted inputs through the domain port and assert compliance-correct outputs without requiring end-to-end integration test infrastructure. This makes it practical to achieve 95%+ coverage of compliance logic, whereas monolithic architectures with compliance logic entangled with infrastructure concerns are often untestable at this level. Automated test coverage of compliance rules can be included in audit evidence packages.

We design hexagonal architectures for regulated applications with compliance rules as the explicitly isolated domain core and audit logging as a first-class output port. Our implementations include test suites covering regulatory edge cases that are included in audit evidence packages, demonstrating that compliance logic is implemented correctly and comprehensively verified.

Compliance-Native Architecture Guide

Design principles and a structured checklist for building software that is compliant by default — not compliant by retrofit. Covers data architecture, access controls, audit trails, and vendor due diligence.