Kotlin + Spring Boot Hexagonal Architecture Guide

This skill defines the architectural conventions for a Kotlin Spring Boot modular monolith using hexagonal architecture (ports & adapters). Follow these patterns when creating or modifying any code.

Module Structure

The project is organized into strict layers with unidirectional dependencies:

presentation (REST)  →  application (Use Cases)  →  domain (Models)  →  support (Shared Kernel)

Critical rule: Presentation modules never import domain directly. All domain concepts are accessed through application layer DTOs (Command, Query, Result).

Creating a New Feature — Step by Step

When adding a new feature (e.g., "bookmark a post"), work bottom-up through the layers:

1. Domain Layer — Entity & Repository

If the feature requires a new entity, create it in domain/src/main/kotlin/{base-package}/domain/{aggregate}/.

For detailed entity patterns, value objects, repository conventions, and domain service patterns, see references/domain-patterns.md.

2. Application Layer — Use Case & Service

Create the use case interface, DTOs, and service implementation in application/src/main/kotlin/{base-package}/application/{feature}/.

For the full use case structure (Command/Query/Result naming, port/in and port/out organization, service patterns), see references/application-patterns.md.

3. Presentation Layer — Controller & DTOs

Create the controller, request/response DTOs in the target presentation module: {presentation-module}/src/main/kotlin/{base-package}/{presentation}/....

For controller patterns (Request→Command mapping, Response construction, ApiResponse wrapping), see references/presentation-patterns.md.

4. Shared Types — Support Module

If the feature introduces new enums or exception types shared across layers, add them to support/src/main/kotlin/{base-package}/support/.

For the exception hierarchy and shared type conventions, see references/support-patterns.md.

Quick Reference: File Placement

When you need to create a new file, use this table to determine the correct location:

{base-package} and {presentation-module} are placeholders — resolve them from the actual project structure (e.g., by inspecting existing packages or build.gradle.kts). A project may have multiple presentation modules (e.g., *-api for public, *-admin for back-office).

Key Conventions Summary

DTO Naming

Use Case Rules

• One use case = one action = one operator fun invoke method
• Interface in port/in/, implementation as @Service class
• Command for writes, Query for reads — never mix
• Result types returned from use cases, never domain entities

Controller Rules

• Request → Command/Query mapping via private extension functions inside the controller
• Result → Response mapping via private extension functions inside the controller
• All responses wrapped in ApiResponse

Repository Rules

• Split into CommandRepository (writes) and QueryRepository (reads)
• Interface defined in domain/{aggregate}/repository/
• Implementation using SimpleJpaRepository (command) or JPAQueryFactory (query)
• Both interface and impl live in the domain module

Transaction Rules

• @Transactional on service methods that write
• @Transactional(readOnly = true) on service methods that only read
• Transaction boundaries at the application service layer, never at controller or domain

Kotlin Idioms

• data class for DTOs, @JvmInline value class for value objects
• private set on mutable entity fields — mutations only through domain methods
• companion object { fun create(...) } factory methods on entities
• Expression bodies for single-expression functions
• val over var, immutable collections at public boundaries
• Named arguments and trailing lambdas for clarity

Agents

This skill includes specialized agents for common workflows. Read the agent instructions before delegating:

• agents/feature-scaffold.md — Scaffolds a complete vertical slice (entity → repository → use case → controller) for a new feature. Use when adding a new feature that spans all layers.
• agents/architecture-reviewer.md — Reviews code for hexagonal architecture compliance, naming convention violations, and layer dependency issues. Use after scaffolding or before PRs.