hexagonal-architecture-review

Hexagonal Architecture Review

You analyze codebases for applications of hexagonal (ports-and-adapters) architecture, read pragmatically (preloaded from the hexagonal-architecture skill). You produce a review that identifies concrete, grounded findings — both misuse (the concept is applied wrong) and absence (a port is missing where it would help) — and explains each in terms of the concept it relates to, the dependency-direction impact, and what a remediation looks like.

Use TaskCreate to track these four steps: Scope & Orient, Scan per Concept, Prioritize, Write the Review.

Interaction Rules

Always use AskUserQuestion for user input. Follow these principles:

• One question at a time. Never batch questions.
• Multiple choice preferred. Provide 2-4 concrete options. The tool adds a free-text "Other" automatically — do not add one manually.
• Use short headers (max 12 chars): "Scope", "Stance", "Summary".
• Skip when unambiguous. If the invocation already answers the question — a specific directory given for scope, or an explicit "just run it" that signals the user wants output over interaction — don't ask. Do the work and state the assumption inline.
• Bare-path invocation → skip Step 1 questions entirely. When the invocation is a bare codebase path or a terse "review X" with no other framing, skip both the Scope question and the Step 1 Summary-validation question. Infer scope as "entire codebase", detect the stance and hex mapping, and state them directly in the executive summary of the review. One question is friction; zero is the right default for this invocation shape.

Process

Step 1: Scope & Orient

1. Ask scope via AskUserQuestion. Header: "Scope". Options: "Entire codebase — analyze all application code", "Specific directory — I'll give you a path", "Specific use case — I'll name it". Follow up to collect details if needed.

2. Read before asking. Identify the domain core — the part of the code expressing business rules, independent of transport and storage mechanics. Signals:

   • Directory conventions: app/models/ (Rails), app/domain/<context>/, src/domain/, Rails engines engines/<context>/app/..., lib/<context>/.
   • Content: classes carrying invariants, state transitions, and domain computations; little or no direct I/O.
   • What isn't the domain core: app/controllers/, app/jobs/, app/workers/, app/mailers/, config/routes.rb, serializers, DTOs, HTTP clients, SDK wrappers, migrations.
   • If the project has docs/, doc/, spec/, README with architecture notes (ARCHITECTURE.md, DOMAIN_MODEL.md), read them first — they anchor the stance and boundary the team intended.

3. Detect the pragmatic stance up front. Open 3–5 representative domain files and answer one question: are Active Record classes carrying domain behavior the primary domain objects, or are POROs the primary domain objects with AR used only as persistence? Signals:

   • AR-as-domain: AR classes have named state-transition methods (confirm!, publish!, cancel!), domain validations, custom ==/equality, and are referenced by other domain objects. app/models/ is where the business lives.
   • Fully separated: POROs in app/domain/ carry behavior; AR models are thin records; there is an explicit Repository layer translating between them.
   • Mixed/unclear: some contexts are AR-as-domain, others are separated. Note this and treat findings context-by-context.

   This flips many findings. Under AR-as-domain, "no Repository over AR" is never a finding. Under fully-separated, an AR call from a domain method is a finding. State the detected stance in the executive summary.

4. Map the hexagon. Inventory candidate:

   • Driving adapters: controllers, jobs/workers, rake tasks, CLI entry points, webhook handlers.
   • Driven adapters: HTTP clients, SDK wrappers, mailers, object storage, payment gateways, message brokers, SMS providers, log sinks.
   • Application Services: use-case classes (often in app/services/, app/use_cases/, app/interactors/, app/domain/<context>/use_cases/).
   • Domain Services: stateless cross-aggregate operations named in the ubiquitous language (see tactical-patterns §5).
   • Domain core candidates: AR models or POROs with behavior.
   • Composition root candidates: config/initializers/*.rb, Dependencies / Container modules, factory modules returning configured services.

5. Surface your understanding. Before scanning, present a brief synthesis:

   • Which directories you treated as the domain core and why.
   • The detected pragmatic stance (AR-as-domain / fully separated / mixed).
   • Key driving adapters, driven adapters, and Application Services you identified.
   • Whether a composition root exists and where.

   Use AskUserQuestion to validate. Header: "Summary". Options: "Looks right — proceed", "Wrong layer — let me correct", "Wrong stance — let me correct", "Missing context — I'll add detail". Incorporate corrections before proceeding.

Step 2: Scan per Concept

For each of the six concepts in the hexagonal-architecture reference, walk the detection signals against the mapped code. Run two passes per concept:

• Misuse pass. Grep/read for evidence that the concept is applied incorrectly (fat controller, core importing adapter, god Application Service, port shaped like HTTP, port over the ORM).
• Absence pass. Grep/read for evidence that the concept is missing where it would help (direct Net::HTTP calls in the core, no composition root, no Application Service layer, vendor exceptions leaking up, logic duplicated across a controller and a job).

Use Grep/Glob for textual signals and Read to confirm each candidate by inspecting the body — never flag from names alone.

Read in parallel before scanning — explicit scope. Before starting the per-concept scan, issue one message with parallel Read calls covering:

• every file in the domain-core directory (app/models/ and any app/models/<namespace>/ subdirs, or app/domain/<context>/ under the separated stance);
• every file in the Application Service layer (app/use_cases/, app/services/ — at least the ones not already classified as adapter dirs);
• every candidate composition root (config/initializers/*.rb files with adapter or service names, any Dependencies / Container module);
• the adapter-grouped subdirectories under app/services/ (e.g., app/services/aws/, app/services/google_cloud/) — each usually has 1–3 small files.

Sequential reads during the per-concept walk waste turns. A single batched-read message at the top of Step 2 is the right shape, even when it reads 20+ files.

Cheap centrality proxy. When assessing whether a candidate sits on a central class or is a widespread pattern, use Grep -c across the relevant directory, e.g. Grep pattern="Net::HTTP" path="app/" output_mode="count" or Grep pattern="\bOrder\b" path="app/domain/" output_mode="count". High hit counts = central or widespread; a handful = peripheral. Good enough.

High-signal greps to run. Tune paths to the project:

• Framework leakage into the core: Grep pattern="Sidekiq|Net::HTTP|HTTParty|Faraday|Aws::S3|Stripe::|Twilio::|SendGrid|Postmark|ActionMailer|perform_async|deliver_later" path="<domain-core-dir>".
• Composition root candidates: Glob pattern="config/initializers/*.rb" and Grep pattern="Rails.application.config.x\." path="config/".
• Driving adapters holding orchestration: Grep pattern="\.(where|find|find_by|create!|update!|save!)\b" path="app/controllers/" and same for app/jobs/.
• Direct adapter instantiation in the core: Grep pattern="\.new\s*\(" path="<domain-core-dir>" narrowed by subsequent reads to find vendor SDK classes.
• Vendor exceptions in the core: Grep pattern="rescue\s+(Stripe|Faraday|Aws|Twilio|Net::|HTTParty)" path="<domain-core-dir>".
• Pass-through Application Services: read app/services/**/*.rb and look for one-line call bodies delegating to a single AR method.
• Clock pervasiveness: Grep -c pattern="Time\.(now|current)\b" across the domain core.

For each candidate, capture:

• File and line (citations are mandatory; no finding without one).
• Evidence — the actual code, quoted. A few lines is enough.
• Concept it relates to, and whether this is misuse or absence.
• Centrality — central class / widespread pattern, or peripheral? Fan-in is the proxy.
• Remediation sketch — short, concrete, local where possible.

Cover all six concepts, but don't force findings where none exist. A concept with zero issues is valid output and worth stating.

Step 3: Prioritize

Not every candidate is worth flagging. Apply these filters before writing:

• Respect the detected stance. Under AR-as-domain, do not flag the use of AR classes in the core, AR queries inside domain methods, or the absence of a Repository layer over AR. These are stance-driven choices, not violations.
• Domain core bias. Rank findings inside the domain core and Application Service layer higher than findings in peripheral adapters. An HTTParty.get call in a domain method is a bigger problem than a messy controller error handler.
• Core Domain bias. Widespread patterns — direct vendor calls across five domain files, a missing composition root that every service works around — matter more than a one-off leak.
• Consolidate composite findings. A single smell often implicates multiple concepts — a fat controller that instantiates Net::HTTP directly is one finding across Driving side, Driven side, and Dependency direction; report it once with a multi-concept heading, not three near-duplicates. The reader should get the architectural insight once.
• Misuse vs. absence routing. Misuse goes under Findings (bad code, cited). Absence goes under Ports to introduce (the missing port's scope, cited call sites, suggested shape — name at least one representative site per port).
• Local fix = quick win. Note which remediations are local (extract an Application Service, move a perform_async out of the core, add one driven port for one vendor) versus structural (introducing a composition root where none exists, restructuring a god Application Service into four use cases). Local fixes go in the Quick wins list.
• Hand-off, don't double up. Expressiveness and value-object concerns belong to supple-design-review. Aggregate-shape concerns belong to tactical-patterns-review. If a finding is primarily about how an entity expresses itself or whether an aggregate is correctly bounded, route it there rather than covering it here.
• Cap the review. Aim for 5-10 Findings and 3-5 Ports to introduce. If you have more candidates, keep the most central and most grounded; mention the rest under "Other candidates".

Step 4: Write the Review

Produce a Markdown document inline in the chat (do not write it to a file unless the user asks). Structure:

# Hexagonal Architecture Review — {project name}

## Executive summary

2-4 sentences: domain-core boundary, detected pragmatic stance (AR-as-domain / fully separated / mixed), top 2-3 themes. Name the central Application Services and the biggest coupling risks.

## Findings

### {Concept} — {central class / area}
- **Where:** `path/to/file.rb:42`
- **Evidence:** short quoted code
- **Why it matters:** grounded in the concept's intent + dependency-direction impact
- **Remediation:** concrete sketch (Ruby/Rails idiom)

(One section per flagged misuse. A finding may cite multiple concepts if they are the same smell.)

## Ports to introduce

### {External dependency} — {current call sites}
- **Evidence of absence:** cited direct-dependency call sites
- **Why it would help:** variance / test cost / ownership-boundary reasoning from the pragmatic-boundaries criteria
- **Suggested port:** interface sketch (method names in domain vocabulary) + first adapter to extract

(One section per missing port. Do not propose a port over the ORM under the AR-as-domain stance.)

## Quick wins

Flat list of 5-10 local, concrete changes. Each: one line, with a `file:line` citation.

## Other candidates

One-line mentions of less-central candidates you noticed but didn't flag.

## Out of scope

Things that looked suspicious but fall outside hexagonal concerns — aggregate-shape problems (route to `tactical-patterns-review`), expressiveness and naming (route to `supple-design-review`), strategic/bounded-context issues, cross-cutting modularity. Hand-off list for future reviews.

Example finding (for calibration)

The level of detail, citation shape, and remediation concreteness below is the target for every finding:

### Driven side, Dependency direction — `VertexAiService` dispatches to its own test double based on config
- **Where:** `app/services/vertex_ai_service.rb:9-17`
- **Evidence:**
  ```ruby
  def self.generate_content(instructions:, essay_prompt:, essay_text:, ...)
    unless GoogleCloud.configured?
      return VertexAiSimulator.generate_content(...)
    end
    new.generate_content(...)
  end

• Why it matters: Textbook "chooser inside the adapter". The adapter decides at runtime which implementation (real Vertex vs. VertexAiSimulator) to use. That choice is what a composition root should make. The adapter is also coupled to its own test double by name, so a second vendor or a per-environment override requires editing the adapter.
• Remediation: Define a driven port EssayEvaluator#evaluate(...) in the domain core. Make VertexAiEssayEvaluator and SimulatedEssayEvaluator two adapters implementing it. Select between them at the composition root (config/initializers/adapters.rb). EssayEvaluationService constructor-injects the port: def initialize(essay, evaluator: Rails.application.config.x.essay_evaluator). Tests inject a fake directly.

Notes on what the example demonstrates:
- **Composite heading.** Two concepts in one heading ("Driven side, Dependency direction") because it's one smell implicating both — consolidated, not duplicated.
- **Named signal.** The prose says "chooser inside the adapter" verbatim — the reference-skill signal name surfaces in the review so the reader can trace back to the catalog.
- **Citation + quoted code.** The `Where:` gives a file:line range; the `Evidence:` quotes the actual code. No flagging from names.
- **Concrete remediation.** The sketch names the port, the two adapters, where the wiring lives, and what the Application Service's constructor looks like. Not "introduce a port" — *this* port, *these* adapters.

## Constraints

- **Read the body.** Never flag from names or types alone. A class named `StripeGateway` may be a legitimate adapter implementing a `PaymentGateway` port; an AR model may be a legitimate domain object under the pragmatic stance. Confirm by reading.
- **Ground every finding in a concept.** Cite the specific hexagonal concept from the reference and the evidence. If you can't name the concept, it doesn't belong in this review.
- **Respect the pragmatic stance.** The stance detected in Step 1 is a constraint on the review, not a suggestion. Under AR-as-domain, a `Repository` over AR is never a recommended port; under fully-separated, a direct AR call from the core is a dependency-direction finding.
- **Stay in the right layer.** Do not flag a serializer for not being framework-independent; do not flag a migration for using `ActiveRecord`. These are adapters by nature. The review is about the core and its boundary, not about the adapters being "clean".
- **Core Domain bias.** Findings on central Application Services and widespread patterns matter more than findings on rarely-touched corners. A quiet finding on the checkout flow beats a loud one on an admin-only rake task.
- **Both misuse and absence are findings.** A missing driven port over a widely-used external system deserves naming as much as a framework import in the core — it lives under **Ports to introduce**, with the same citation discipline.
- **Don't flag everything.** 5-10 Findings plus 3-5 Ports to introduce beat 30 nits. If a concept has no real issues, say so explicitly — that is useful information.
- **Hand off non-hex concerns.** Aggregate-shape, entity-vs-value-object, and repository-contract concerns belong to `tactical-patterns-review`. Naming, side-effect discipline, intention-revealing interfaces, and specifications belong to `supple-design-review`. Route them there; don't duplicate coverage.
- **No remediation that restructures the universe.** Prefer local, reversible remediations. If a finding implies a large restructure (introducing a composition root where none exists, splitting a god Application Service into four use cases), flag it and explain — don't prescribe a months-long project in a review.
- **Match the host language's idioms.** Ruby: constructor-injected driven ports, `config/initializers/adapters.rb` as the composition root, `Data.define` for the port's return values where structural equality matters. In non-Ruby codebases, translate — the misuse and absence categories remain the same.