In this guide (6 items)

Architecture Diagrams & Patterns

Diagram Catalog

FOR ALL AI AGENTS: Project-agnostic reference for hexagonal architecture diagrams and patterns. Use as reference when understanding module dependencies, data flows, and design patterns. Do NOT modify the architectural patterns shown here without explicit approval.

Diagram-level decisions (new bounded context split, new adapter category, change of dependency direction in a diagram) require an ADR per adr.md. Diagrams illustrate the current state; ADRs explain why it is that way.

Project-agnostic: placeholders com.example.platform (package) and platform-service (service name) used throughout. Replace with your project’s actual values when applying patterns.

Document Version: 2.0 Last Updated: 2026-06-10 Purpose: Index of hexagonal architecture diagrams, patterns, and conventions.

Why this split

The previous monolithic diagrams.md (2151 LOC) exceeded the comfortable single-read window for AI agents. Content is now sliced by concern. Each file is self-contained for the topic it covers and links back here.

Themed Files

File	Scope	LOC
arch-overview.md	High-level architectural pattern, hexagonal implementation layers, module structure (directory tree).	~270
ports-and-commands.md	Port naming conventions, port definition guidelines, command pattern, command mapper, three-layer mapping chain.	~320
data-flows.md	Full request lifecycle (Create Organization example), commands vs domain entities comparison, transformation chain.	~290
patterns-catalog.md	Architectural patterns (hexagonal, CQRS, outbox), behavioral patterns (CoR, strategy, command), structural patterns (decorator, adapter, facade).	~480
c4-diagrams.md	Package dependency, runtime component, event flow (transactional outbox).	~190
best-practices.md	Port/command/entity/use-case/adapter design rules, short/medium/long-term improvements, file locations, decision guide, troubleshooting.	~620

Reading Order

Discovering the architecture (new team member, first read):

arch-overview.md — what the layers are and why.
c4-diagrams.md — visual high-level structure.
ports-and-commands.md — naming + contracts.
data-flows.md — concrete request walk-through.
patterns-catalog.md — catalog of recurring patterns.
best-practices.md — design rules + improvement roadmap.

Implementing a new feature (AI assistant or developer):

arch-overview.md §3 — module structure (where the file goes).
ports-and-commands.md — name and define the port + command.
data-flows.md §6.1 — model the request flow end-to-end.
patterns-catalog.md — pick the pattern that fits.
best-practices.md — checklists per layer.

Picking a pattern:

Cross-cutting concern (metrics, cache, logging) → patterns-catalog.md §7.2 (Chain of Responsibility / Decorator).
Reliable event publish → patterns-catalog.md §7.1 (Transactional Outbox).
Algorithm selection at runtime → patterns-catalog.md §7.2 (Strategy).
External system adaptation → patterns-catalog.md §7.3 (Adapter).

Companion Guides

hexagonal-architecture.md — narrative rules (binding) for hexagonal architecture.
ddd.md — domain modeling building blocks.
adr.md — capture decisions that diverge from these patterns.
arch-doc-spec.md — board-grade deliverable using these diagrams.
latex-architecture-docs.md — PDF rendering pipeline.

Conventions

Diagram tools used across the themed files:

Mermaid — default for flow, sequence, class diagrams (renders natively in GitHub, Markdown, HTML).
PlantUML — used when Mermaid lacks a notation (component, deployment, archimate). Configured via Gradle plugin per gradle.md §4.5.
Structurizr DSL — C1/C2/C3 (System Context, Container, Component) when authoring a full board deliverable per arch-doc-spec.md.
ASCII art — used inside this catalog for tree structures and quick references.

Notation:

→ denotes a runtime call or data flow.
─► denotes a dependency direction in package diagrams (always points inward in hexagonal).
▷ denotes an interface implementation.

File placement — every file referenced in the catalog uses placeholder com.example.platform. When applying:

Domain: domain/src/main/{lang}/com/example/platform/domain/
Application: application/src/main/{lang}/com/example/platform/{port|usecase|command|mapper}/
Infrastructure: infrastructure/{entry-points|driven-adapters}/.../src/main/{lang}/com/example/platform/infrastructure/...
Bootstrap: bootstrap/src/main/{lang}/com/example/platform/{Main|config}/

Maintenance

When updating any themed file:

Keep file scope tight — if content fits another file better, move it.
Update this index’s table-of-contents LOC count if a file grows >50%.
Sanity-check cross-links (arch-overview.md may link to data-flows.md and vice versa).
New diagrams go in the most-specific themed file; the index never holds diagrams.
Project-specific names MUST NOT appear — use com.example.platform / platform-service placeholders.

Backup of the monolithic predecessor lives at ~/.claude/backups/diagrams-pre-split-*.md.