kotlin-boilerplate

A Kotlin boilerplate project using Spring Boot and DDD

Technology and Resources

• Kotlin 2.2+ - pre-requisite
• Java 21 - pre-requisite
• Docker - pre-requisite
• Docker Compose - pre-requisite
• Spring Boot 4.x
• PostgreSQL 16
• Flyway
• Testcontainers

Please pay attention on pre-requisite resources that you must install/configure.

How to install, run and test

Environment variables

Variable	Description	Available Values	Default Value	Required
APP_PORT	Application port	any port	8080	No
SPRING_PROFILES_ACTIVE	Active Spring profile	dev / test / prod	dev	Yes
POSTGRES_USER	PostgreSQL username	any string	boilerplate	Yes
POSTGRES_PASSWORD	PostgreSQL password	any string	—	Yes
POSTGRES_DB	PostgreSQL database name	any string	boilerplate_db	Yes
POSTGRES_PORT	PostgreSQL port	any port	5432	No

Note: copy .env.template to .env and fill in the values before running.

Commands

Command	Locally	Description
build	make build	compile the project (includes static analysis)
test	make test	run all tests
run	make run	run the application (dev profile)
lint	make lint	run detekt static analysis only (already included in build)
clean	make clean	clean build artifacts
db-up	make db-up	start PostgreSQL in background (Docker)
db-down	make db-down	stop all Docker services
db-logs	make db-logs	follow PostgreSQL container logs

Full stack Docker commands (make up, make docker-build, etc.) are available after PR-07.

Please check all available commands in the Makefile for more information.

Architecture

This project follows a pragmatic DDD layered architecture:

api → application → domain ← infra

Layer	Responsibility
domain/	Pure Kotlin — entities, value objects, repository interfaces. Zero framework dependencies.
application/	Use cases with a single execute() method. Orchestrates domain objects.
infra/	JPA entities, Spring Data repositories, RepositoryImpl bridging domain and persistence.
api/	REST controllers, request/response DTOs, global exception handler.