Hexagonal Architecture: The Best AI Vibe Coding Guide

Posted on In Views:

Hexagonal Architecture: The Best AI Vibe Coding Guide

Boost review efficiency and code accuracy using layered architecture with AI

I finally found a development workflow that suits me best. It is highly efficient and ensures extremely high accuracy at the same time.

I think we can all agree on delegating the tedious task of coding to AI as much as possible. We humans just need to define what to do and verify the results. But I am not sure if we have noticed a problem. Humans eventually become the blocker in the whole process. AI writes code incredibly fast. We simply cannot do a complete code review. This usually results in an “always approve” situation.

This “always approve” habit is the exact reason why various bugs keep popping up. AI is great at writing code. However, it definitely does not guarantee zero mistakes.

So how can our review process keep up with the speed of AI? This is a question I have been thinking about lately.

Actually, the answer is already there. Long before AI came into the world, we already had a methodology to improve software maintainability. That methodology is layering.

Yes, layered architecture is nothing new. I have also written many articles about how to implement layered architecture and Domain-Driven Design (DDD). The most classic one is this article.

But in fact, I only favored basic layering in the past. I did not favor extreme layering strategies like hexagonal architecture. However, it is exactly the hexagonal architecture that can completely solve the current problem of inefficient reviews and excessive errors. Let us see why.

Hexagonal Architecture

This is a classic hexagonal architecture diagram. It has a few key points.

  1. Clear external dependencies. This includes the inbound interfaces (ports) flowing into the service and the outbound dependencies. All external dependencies have clear and well-defined interfaces to set the boundaries.
  2. Every external dependency has a corresponding adapter for implementation. For instance, a Postgres has a database adapter. External API calls have REST adapters.
  3. Inside the service, aside from boundary definitions, the rest is purely domain-specific business logic.

I believe even those unfamiliar with clean architecture or DDD can easily see the strengths of hexagonal boundaries from this diagram.

But the main reason I did not promote hexagonal architecture in the past is the manual labor involved. All these layers, adapters, and boundaries require manual coding one by one. This involves a massive amount of coding effort just to describe specifications instead of actually solving problems.

Therefore, at that time, hexagonal architecture would ironically become another blocker. It was not a review blocker but a coding blocker.

Let me give a classic example from my own experience. I can build three APIs in Golang with about 600 to 1000 lines of code, excluding tests. But if I use hexagonal architecture, it takes about 3000 to 4000 lines of code. This means 4–5x more effort, or even more, just for coding.

Vibe Coding Era

But times have changed now. Writing code is no longer the bottleneck. As long as we have clear and specific specifications, AI can easily generate thousands of lines of code.

That is right. Clear and specific specifications are exactly the strengths of hexagonal architecture. And the shortcomings of hexagonal architecture are perfectly covered by AI. They are a perfect match.

So what are the benefits of hexagonal architecture for us today? Let me explain using a concrete development workflow.

When we need to develop a complex microservice API, it will have many external dependencies. These include RPC between services, its own data storage, and even complex business logic.

We can manage all of these using the following development workflow. This is a specific example from a project I am currently working on. I strictly followed everything defined by hexagonal architecture.

Phase 1: Domain and Ports

  • Details: Struct fields and interface method signatures.
  • Human Focus: Check if the design is correct and if anything is missing.

Phase 2: Repository

  • Details: SQL, SQLC, and mapping.
  • Human Focus: A quick glance is enough. Tests will catch errors.

Phase 3: Infrastructure

  • Details: HTTP adapter, middleware, and Wire.
  • Human Focus: A quick glance is enough. If it compiles, it is mostly fine.

Phase 4: Service Layer

  • Details: State machine, validation, and notification.
  • Human Focus: Read line by line to ensure business rules are correct.

Phase 5: Integration Test

  • Details: 16 DB tests.
  • Human Focus: Ensure important scenarios are covered.

We can almost completely let AI write code for all phases. Each phase will correspond to a complete PR. This naturally includes a complete CI/CD process.

We can see that the scope requiring my careful review is clearly defined. It only includes phase 1 and phase 4.

Once I deeply verify in phase 1 that the interfaces of every external dependency are defined correctly, the behavior of the entire microservice is basically solid. Then, I just need to verify the internal core business logic is correct. This keeps the quality of the entire microservice at a high level.

Wrap Up

Through the strict layering of hexagonal architecture, we can easily achieve separation of concerns. We only need to focus on where we must focus. For the rest, we can trust the power of AI.

This is the core reason why I am embracing hexagonal architecture again in this era.

When we have the correct interfaces, even if errors occur, they will not be disastrous. Moreover, reviewing interfaces is relatively easy for humans.

I have been running this workflow for a while now. Facts prove that it is highly effective. It can significantly boost overall productivity. After all, we always say humans are the bottleneck of AI. I am working hard to eliminate this blocker.

Originally published on Medium