Kotlin Clean Architecture Multi-Module

Spring Boot (Kotlin) Clean Hexagonal Architecture - Multi-Module Template

Production-ready | Clean Architecture | Multi-Module | Test-Driven | Observability

Original Repository: https://github.com/awakelife93/spring-boot-kotlin-boilerplate

This project is migrated from spring-boot-kotlin-boilerplate to implement Hexagonal Architecture and Multi-Module structure.

A production-ready Spring Boot multi-module project template built with Kotlin. It follows Hexagonal Architecture (Ports and Adapters) principles and Domain-Driven Design (DDD) patterns to ensure maintainability, testability, and scalability. The project includes a complete OpenTelemetry-based observability stack for unified monitoring, distributed tracing, and log aggregation.

Getting Started

Prerequisites

Java 21 or higher
Docker & Docker Compose (for infrastructure services)
Gradle 8.10 (wrapper included)

Quick Start

1. Start Infrastructure Services

cd docker && ./setup.sh

For detailed setup information, see Docker Setup Guide which explains:

Network configuration and auto-creation

Individual service management

Service dependencies and startup order

2. Run the Application

./gradlew :demo-bootstrap:bootRun

3. Verify Setup

Application is running at http://localhost:8085

See Service Access URLs for all available services.

Architecture Overview

Hexagonal Architecture (Ports & Adapters)

        ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐
        │ Observability Layer (OpenTelemetry) — Spans All Layers  │
        │               Metrics | Traces | Logs →                 │
        │               Prometheus / Tempo / Loki                 │
        │                                                         │
        │ ┌─────────────────────────────────────────────────────┐ │
        │ │                Driving Adapters (Input)             │ │
        │ │  demo-internal-api / demo-external-api / demo-batch │ │
        │ └──────────────────────────┬──────────────────────────┘ │
        │                            │                            │
        │                   ┌────────▼────────┐                   │
        │                   │   Input Ports   │                   │
        │                   └────────┬────────┘                   │
        │                            │                            │
        │ ┌──────────────────────────▼──────────────────────────┐ │
        │ │                  Application Core                   │ │
        │ │                                                     │ │
        │ │   ┌───────────────────────────────────────────┐     │ │
        │ │   │       demo-application (UseCases)         │     │ │
        │ │   │            • Business Logic               │     │ │
        │ │   │            • Orchestration                │     │ │
        │ │   └──────────────────────┬────────────────────┘     │ │
        │ │                          │                          │ │
        │ │   ┌──────────────────────▼────────────────────┐     │ │
        │ │   │          demo-domain (Entities)           │     │ │
        │ │   │            • Domain Models                │     │ │
        │ │   │            • Business Rules               │     │ │
        │ │   │            • Port Interfaces              │     │ │
        │ │   └───────────────────────────────────────────┘     │ │
        │ │                                                     │ │
        │ └──────────────────────────┬──────────────────────────┘ │
        │                            │                            │
        │                   ┌────────▼────────┐                   │
        │                   │  Output Ports   │                   │
        │                   └────────┬────────┘                   │
        │                            │                            │
        │ ┌──────────────────────────▼──────────────────────────┐ │
        │ │               Driven Adapters (Output)              │ │
        │ │                 demo-infrastructure                 │ │
        │ │              • Database (JPA/PostgreSQL)            │ │
        │ │              • Cache (Redis)                        │ │
        │ │              • Message Queue (Kafka)                │ │
        │ │              • Email Service                        │ │
        │ └─────────────────────────────────────────────────────┘ │
        │                                                         │
        └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘

Cross-Cutting Concerns

The following concerns span across all architectural layers:

Observability - Unified monitoring via OpenTelemetry (see Key Features #9)

Security - Spring Security, JWT, RBAC (see Technology Stack section)

Logging - Kotlin Logging, Logback (see Technology Stack section)

Error Handling - Global exception handling, webhook notifications (Slack/Discord), Sentry integration

Multi-Module Structure

root/
├── demo-core/              # Core utilities, configurations, and test fixtures
├── demo-domain/            # Domain entities, value objects, and Port Interfaces
├── demo-application/       # Use cases with Input/Output Ports
├── demo-infrastructure/    # Adapters for Output Ports (DB, Cache, MQ, etc.)
├── demo-internal-api/      # Adapters for Input Ports (Internal REST API)
├── demo-external-api/      # Adapters for Input Ports (External/Public API)
├── demo-batch/            # Adapters for Input Ports (Batch processing)
├── demo-bootstrap/        # Application bootstrap and main entry point
├── gradle/                # Gradle configuration and version catalogs
│   └── libs.versions.toml  # Centralized dependency version management
├── docker/                # Docker compose configurations
└── monitoring/            # Monitoring configurations (Prometheus, Grafana, OpenTelemetry Collector, Tempo, Loki)

Technology Stack

Core Technologies

Language: Kotlin 2.0.21
Framework: Spring Boot 3.5.5
JVM: Java 21 LTS

Key Libraries & Frameworks

Web & API

Spring WebMVC / WebFlux
Spring Validation
SpringDoc OpenAPI (Swagger UI)
Jackson for JSON processing
WebClient

Security

Spring Security
JWT
BCrypt password encoding
Role-based access control (RBAC)

Database & Persistence

Spring Data JPA
QueryDSL
Flyway
PostgreSQL / H2

Caching & Messaging

Spring Data Redis
Apache Kafka (via Spring Kafka)
Event-driven architecture support

Testing

JUnit 5 / Kotest
MockK / Mockito Kotlin & Mockito Inline
Spring Boot Test
Spring MockMvc

Development Tools

Ktlint / Detekt (Code quality)
Spring Boot DevTools (Hot reload)
Gradle 8.10 with Kotlin DSL
Gradle Version Catalogs (libs.versions.toml) for centralized dependency management
Docker & Docker Compose
MailHog / PgAdmin / Kafka UI

Monitoring & Logging

Observability Stack: OpenTelemetry Collector, Prometheus, Grafana, Tempo, Loki
Application Monitoring: Spring Actuator, Sentry
Logging: Kotlin Logging, Logback

Build Configuration

Gradle Multi-Module Setup

The root build.gradle.kts manages all subprojects with shared configurations through subprojects block.

Key Features

Hexagonal Architecture Module Dependencies:

// demo-core auto-dependency for all modules (except itself)
if (project.name != "demo-core") {
	api(project(":demo-core"))
}

// Test fixtures sharing for specific modules
val modulesUsingTestFixtures = listOf(
	"demo-application", "demo-infrastructure",
	"demo-internal-api", "demo-external-api",
	"demo-batch", "demo-domain"
)

Test Fixtures Strategy:

demo-core provides common test utilities, mock data, and base test classes shared across modules
Each listed module uses these fixtures for their specific testing needs:
- demo-application: Use case testing
- demo-infrastructure: Repository/adapter testing
- demo-internal-api: Controller integration testing
- demo-external-api: API endpoint testing
- demo-batch: Batch job testing
- demo-domain: Domain model testing
Excluded modules:
- demo-bootstrap: Main application module (no test fixtures needed)
- demo-core: Source of test fixtures (doesn't consume itself)

Security Vulnerability Management:

All dependency vulnerabilities are centrally managed through the applyCveFixes() function in the root build.gradle.kts
CVE fixes are automatically applied to all subprojects during dependency resolution

// Example: CVE fix implementation
when {
	requested.group == "org.apache.commons" && requested.name == "commons-lang3" -> {
		useVersion("3.18.0")
		because("CVE-2025-48924")
	}
}

Executable vs Library Modules:

val executableModules = listOf("demo-bootstrap")
if (project.name !in executableModules) {
	// Library modules: disable bootJar, enable regular jar
	tasks.named<BootJar>("bootJar") { enabled = false }
	tasks.named<Jar>("jar") { enabled = true }
}

Development Commands

Build & Test

# Build all modules
./gradlew build

# Run tests
./gradlew test

# Run specific module tests
./gradlew :demo-application:test

Code Quality

# Run ktlint check
./gradlew ktlintCheck

# Format code with ktlint
./gradlew ktlintFormat

# Run detekt analysis
./gradlew detekt

Hexagonal Architecture Implementation

Port & Adapter Examples

Output Port (Domain Layer):

// demo-domain/src/main/kotlin/com/example/demo/user/port/UserPort.kt
interface UserPort : UserCommandPort, UserQueryPort

Output Adapter (Infrastructure Layer):

// demo-infrastructure/src/main/kotlin/com/example/demo/persistence/user/adapter/UserRepositoryAdapter.kt
@Repository
class UserRepositoryAdapter(
	private val userJpaRepository: UserJpaRepository,
	private val userMapper: UserMapper
) : UserPort {
	override fun findOneById(userId: Long): User? =
		userJpaRepository.findOneById(userId)?.let {
			userMapper.toDomain(it)
		}
	// ... other implementations
}

Input (Use Case - Application Layer):

// demo-application/src/main/kotlin/com/example/demo/user/usecase/CreateUserUseCase.kt
@Component
class CreateUserUseCase(
	private val userService: UserService
) : UseCase<CreateUserInput, UserOutput.AuthenticatedUserOutput> {
	override fun execute(input: CreateUserInput): UserOutput.AuthenticatedUserOutput =
		with(input) {
			userService.registerNewUser(this)
		}
}

Input Adapter (REST Controller):

// demo-internal-api/src/main/kotlin/com/example/demo/user/presentation/UserController.kt
@RestController
@RequestMapping("/api/v1/users")
class UserController(
	private val createUserUseCase: CreateUserUseCase
) {
	@PostMapping("/register")
	fun createUser(
		@RequestBody @Valid createUserRequest: CreateUserRequest
	): ResponseEntity<CreateUserResponse> {
		val input = UserPresentationMapper.toCreateUserInput(createUserRequest)
		val userOutput = createUserUseCase.execute(input)

		val response = UserPresentationMapper.toCreateUserResponse(userOutput)
		return ResponseEntity.status(HttpStatus.CREATED).body(response)
	}
}

Configuration Management

Application Configuration Structure

The project implements a multi-layered configuration approach that balances modularity with maintainability:

1. Module-Specific Configuration Files

Each module manages its own library-specific configurations:

demo-bootstrap/
└── src/main/resources/
    └── application-bootstrap.yml          # Sentry configuration

demo-internal-api/
└── src/main/resources/
    └── application-internal-api.yml       # SpringDoc/Swagger configuration

demo-external-api/
└── src/main/resources/
    └── application-external-api.yml       # Webhook configuration

demo-infrastructure/
└── src/main/resources/
    └── application-infrastructure.yml     # Actuator/Management configuration

2. Core Configuration (Central Management)

demo-core/src/main/resources/
├── application-common.yml                 # Common settings + imports
├── application-dev.yml                    # Development environment
├── application-prod.yml                   # Production environment
├── application-local.yml                  # Local development
├── application-test.yml                   # Test environment
├── application-secret-local.yml           # Local secrets
├── application-secret-dev.yml             # Development secrets
└── application-secret-prod.yml            # Production secrets

demo-core/src/testFixtures/
├── kotlin/.../demo/
│   ├── TestApplication.kt                 # Test application entry point
│   └── config/
│       └── KotestSpringConfig.kt          # Kotest Spring configuration
└── resources/
    └── kotest.properties                  # Kotest settings (copied to modulesUsingTestFixtures)

3. Configuration Import Strategy

Core configuration imports all module-specific settings:

# demo-core/src/main/resources/application-common.yml
spring:
	config:
		import:
			- "optional:classpath:application-bootstrap.yml"        # Sentry
			- "optional:classpath:application-internal-api.yml"     # SpringDoc
			- "optional:classpath:application-external-api.yml"     # Webhook
			- "optional:classpath:application-infrastructure.yml"   # Management

4. Environment-Specific Overrides

Environment files can override any module setting:

# application-prod.yml
springdoc:
	swagger-ui:
		enabled: false # Override from demo-internal-api module
	api-docs:
		enabled: false

sentry:
	dsn: # Override from demo-bootstrap module (empty for prod)
	logging:
		minimum-event-level: ERROR

webhook:
	slack:
		url: # Override from demo-external-api module (empty for prod)

Note: IDE may show "Cannot resolve configuration property" warnings for cross-module properties. This is expected and can be ignored as the configuration works correctly at runtime.

5. Configuration Loading Order

Spring Boot loads configurations in this priority order:

Environment-specific files (application-prod.yml)
Module-specific files (application-bootstrap.yml)
Common configuration (application-common.yml)

This ensures environment settings always take precedence over module defaults.

Key Features

1. Database Management

DDL Management: Uses Flyway for migration scripts instead of JPA auto-generation
Migration Scripts: Located in demo-core/src/main/resources/db/migration
Alternative: JPA DDL auto-generation available via configuration in application-common.yml

2. Spring Batch Configuration

Metadata Tables: Create Spring Batch metadata table for all environments
PostgreSQL Schema: Uses batch-postgresql-metadata-schema.sql
Reference: Spring Batch Schema

3. Webhook Integration

Configuration: enable & route endpoint (default enabled)
Supported Types: Slack, Discord

// Usage examples
webHookProvider.sendAll(
	"Subscription request received from method ${parameter.method?.name}.",
	mutableListOf("Request Body: $body")
)

webHookProvider.sendSlack(
	"Failed to send message to Kafka",
	mutableListOf("Error: ${exception.message}")
)

webHookProvider.sendDiscord(
	"Batch processing completed",
	mutableListOf("Results: $results")
)

4. Email Testing

MailHog Integration: Email testing tool with SMTP port 1025
Configuration: Settings in application-local.yml and application-secret-local.yml

5. Code Quality Tools

Ktlint: Official lint rules, configuration in .editorconfig
- Report output: build/reports/ktlint
Detekt: Static analysis, rules in detekt.yml
- Report output: build/reports/detekt

6. Testing Strategies

Mockito-based Testing:

BaseIntegrationController

Kotest & MockK Testing:

BaseIntegrationController
Security Bypass: SecurityListenerFactory

// Example: Bypassing Spring Security in tests
listeners(SecurityListenerFactory())

Then("Call DELETE /api/v1/users/{userId}").config(tags = setOf(SecurityListenerFactory.NonSecurityOption)) {
	// ... test implementation
}

7. Kafka Integration

Topic Management: KafkaTopicMetaProvider
DLQ Support: Dynamic DLQ creation with default fallback partition: 1

8. Event-Driven Examples

User Registration Flow:

User Cleanup Flow:

9. OpenTelemetry Stack Configuration (Monitoring & Observability)

Architecture:

All observability data (metrics, traces, logs) are collected through OpenTelemetry Collector
Spring Boot application uses OpenTelemetry Spring Boot Starter (SDK) to auto-instrument and send telemetry data
OpenTelemetry Collector routes data to Prometheus, Tempo, and Loki

Configuration Files:

OpenTelemetry Collector: otel-collector-config.yml
- Receives: OTLP gRPC (localhost:4317), OTLP HTTP (localhost:4318)
- Exports to: Prometheus, Tempo, Loki
Prometheus: prometheus.yml - Metrics collection
Tempo: tempo.yml - Distributed tracing
Loki: loki.yml - Log aggregation
Grafana: Unified dashboard at http://localhost:3000

Application Settings:

application-infrastructure.yml
- OpenTelemetry exporter configuration (management.otel.*)
- Spring Actuator settings for observability

10. Docker & Infrastructure

Complete Docker Compose setup for all services
Detailed setup guide: Docker Setup Guide

Service Access URLs

Application Services

Service	URL	Description
API Documentation	http://localhost:8085/swagger-ui/index.html	Swagger UI for API testing
H2 Console	http://localhost:8085/h2-console	Database console (local only)
Application Server	http://localhost:8085	Main application endpoint

Infrastructure Services

Service	URL	Description
MailHog	http://localhost:8025	Email testing interface
PgAdmin	http://localhost:8088	PostgreSQL management
Kafka UI	http://localhost:9000	Kafka topic management
Redis	localhost:6379	Redis CLI/Client access
PostgreSQL	localhost:5432	Database connection
Kafka Broker	localhost:9092	Kafka broker connection
Zookeeper	localhost:2181	Coordination service

Observability

Service	URL	Credentials	Description
Grafana	http://localhost:3000	demo / demo	Unified observability dashboard
Prometheus	http://localhost:9090	-	Metrics collection
Tempo	http://localhost:3200	-	Distributed tracing
Loki	http://localhost:3100	-	Log aggregation
OTLP Collector (gRPC)	localhost:4317	-	OpenTelemetry gRPC endpoint
OTLP Collector (HTTP)	localhost:4318	-	OpenTelemetry HTTP endpoint

Grafana Data Source Configuration (use Docker internal network addresses):

Prometheus: http://prometheus:9090
Tempo: http://tempo:3200
Loki: http://loki:3100

Author

Hyunwoo Park

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
demo-application		demo-application
demo-batch		demo-batch
demo-bootstrap		demo-bootstrap
demo-core		demo-core
demo-domain		demo-domain
demo-external-api		demo-external-api
demo-infrastructure		demo-infrastructure
demo-internal-api		demo-internal-api
docker		docker
gradle		gradle
monitoring		monitoring
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
README.md		README.md
build.gradle.kts		build.gradle.kts
detekt.yml		detekt.yml
gradle.properties		gradle.properties
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle.kts		settings.gradle.kts

Folders and files

Latest commit

History

Repository files navigation

Kotlin Clean Architecture Multi-Module

Spring Boot (Kotlin) Clean Hexagonal Architecture - Multi-Module Template

Table of Contents

Getting Started

Prerequisites

Quick Start

1. Start Infrastructure Services

2. Run the Application

3. Verify Setup

Architecture Overview

Hexagonal Architecture (Ports & Adapters)

Cross-Cutting Concerns

Multi-Module Structure

Technology Stack

Core Technologies

Key Libraries & Frameworks

Web & API

Security

Database & Persistence

Caching & Messaging

Testing

Development Tools

Monitoring & Logging

Build Configuration

Gradle Multi-Module Setup

Key Features

Development Commands

Build & Test

Code Quality

Hexagonal Architecture Implementation

Port & Adapter Examples

Configuration Management

Application Configuration Structure

1. Module-Specific Configuration Files

2. Core Configuration (Central Management)

3. Configuration Import Strategy

4. Environment-Specific Overrides

5. Configuration Loading Order

Key Features

1. Database Management

2. Spring Batch Configuration

3. Webhook Integration

4. Email Testing

5. Code Quality Tools

6. Testing Strategies

7. Kafka Integration

8. Event-Driven Examples

9. OpenTelemetry Stack Configuration (Monitoring & Observability)

10. Docker & Infrastructure

Service Access URLs

Application Services

Infrastructure Services

Observability

Author

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages