hexwright

Design graph for hexagonal-architecture codebases. Extracts the type graph from source, checks ports-and-adapters boundaries, and renders exactly what a branch changed — structurally, not as a text diff.

(hex here is the hexagon, not hexadecimal.)

Runs as a sidecar: it never writes to the target repository.

npx hexwright extract --repo ~/work/my-service --base main --out .design
npx hexwright check   --repo ~/work/my-service            # exit 1 on violations
npx hexwright render  --repo ~/work/my-service --base main --image delta.png

Render

An image for the PR — what this branch changed, in one picture.

hexwright render --repo ~/work/my-service --base main --image delta.png

  view    what this branch added and changed
  drew    10 types · 18 relations · 0 violations
  wrote   delta.svg  (17 KB)
  wrote   delta.png  (802×614)

The default draws only what changed — nothing pre-existing. That is not a loss of information: every relation the branch introduced has both ends inside the changed set, so narrowing keeps all of them while dropping the dependencies the modified types already had. On the branch above that is 10 types instead of 61, and the image fits a PR comment at full size instead of being scaled down until the labels are unreadable.

Use --view impact when the question is who is affected rather than what was built — it adds everything that depends on a changed type (30 types, 7 domains on the same branch).

Added types get a solid orange outline, modified ones a violet dash, new relations orange. Everything unchanged stays as dimmed context. Red is reserved for boundary violations — domain hues never enter the red or orange band, so a red line always means a breach.

The delta is laid out organically: each domain is a dense block ordered Entity → Service → UseCase → Port → DTO, and the blocks are placed by how much they actually couple. A change spanning several contexts therefore draws itself as a hub with the domains that touch it around it.

There is no browser involved — the coordinates are a pure function, so the SVG is written directly and CI needs no headless Chrome. The same graph always draws the same file, which is what makes two branches comparable.

--image x.png also writes x.svg. PNG needs the optional @resvg/resvg-js; without it the SVG is still written and the command says so. GitHub does not render SVG in comments, so attach the PNG there and keep the SVG as the artifact.

Layout follows the view — organic for delta and domain:, hex for core and all (concentric rings, read as a shape). --layout organic|grid|hex overrides; grid lists domains left to right, ignoring coupling.

Related MCP server: Axon Pro

MCP

Serve the graph to a coding agent over stdio:

hexwright mcp --repo ~/work/my-service --base main

{ "mcpServers": { "hexwright": {
    "command": "npx",
    "args": ["hexwright", "mcp", "--repo", "/abs/path/to/repo", "--base", "main"] } } }

Eleven read-only tools. Every response carries the contract, role, and file location together, so the agent can act on it — or knows exactly which file to open when the graph is not enough.

get_dependencies is the one that pays off:

MediaLabelResolver [Service] media
depends on (4):
  → MediaLabelQueryPort [Port] media
      uses: personTags(mediaIds: Collection<UUID>): List<PersonTagRow>,
            placeTags(mediaIds: Collection<UUID>): List<PlaceTagRow>

Assumptions

Single-module Gradle project, Kotlin, Spring Boot, with a domain-first (package-by-feature) hexagonal layout.

The source root is found by Gradle convention — build.gradle(.kts) up to two levels deep, then <module>/src/main/kotlin. A monorepo with several Kotlin modules stops with the list and asks you to pick one:

found 3 Gradle modules with Kotlin sources (client/androidApp, media-processor, server).
hexwright assumes a single module — pass --src to pick one.

--src takes either a module path (server) or a source root (server/src/main/kotlin). If settings.gradle declares subprojects, it warns and analyzes only the selected module.

Expected package layout — the domain is the segment right after the common package prefix, which is inferred automatically:

<base>.<domain>.domain.model        Entity · VO
<base>.<domain>.domain.event        Event
<base>.<domain>.application.port.inbound   UseCase · DTO
<base>.<domain>.application.port.out       Port · DTO
<base>.<domain>.application.service        Service
<base>.<domain>.adapter.web                inbound adapter
<base>.<domain>.adapter.out                outbound adapter
<base>.common                              Shared

What it produces

nodes 701  Adapter 230 · DTO 126 · UseCase 113 · Port 60 · VO 55 · Service 46 · Entity 25
edges 2211 DEPENDS_ON 2021 · IMPLEMENTS 188 · EXTENDS 2
domains 16

delta vs main
  added 6 nodes · 15 edges   modified 4 nodes   removed 0
    + MediaLabelQueryPort [Port] media
    ~ MediaService [Service] media

violations 7
  AdminAuthController → admin.AdminAccount   inbound adapter touches Entity

--out writes two files:

• graph.json — full graph including public contracts

• graph.tsv — one line per node/edge, sorted, prefix-stripped. Commit this and git diff shows structural change in readable form.

Principles

Only relations that exist in the source. No derived or inferred edges. A reference to UserId is not a reference to User — promoting it would fabricate facts and every metric built on top would be wrong.

Deterministic classification. Component roles come from path + language construct only. No human judgement, so results are reproducible and comparable across commits.

Signature-following. When a type is only held in a local variable, its name never appears in the source. The extractor reads the callee's signature to recover the reference, so service.save(x) resolves x through Repository.findById(): Record?.

Configuration

Conventions live in a profile, not in code — profiles/hexagonal-kotlin.yml. Path fragments, component rules, and boundary rules are all declarative, so port/in vs port/inbound or infrastructure/ vs adapter/ is a config change.

Boundary rules

An Entity may be touched by, within the same domain: Service, Port, Entity, and outbound adapters (port implementations must map aggregates). Everything else is a violation:

• cross-domain Entity access — bounded context breach

• inbound adapter touching an Entity — controllers should speak DTOs

• a DTO or UseCase exposing an Entity — domain model leaked into a contract

• application/domain referencing adapter — layer back-reference

Status

Early. Kotlin extractor only; validated against one production codebase (701 nodes, 2211 edges) with output verified against a reference implementation.

Not done yet: CI wiring (post the render on every PR), and planned nodes for comparing a design against what was actually built.

MIT