Kotlin Fintech Starter

A production-oriented Kotlin/JVM starter project for a fintech backend service.

It is intentionally opinionated:

• Kotlin/JVM with Spring Boot
• Explicit SQL through Spring JDBC
• PostgreSQL and Flyway migrations
• Hexagonal-ish package structure: domain, application, adapter, config
• Idempotent payment authorization endpoint
• Ledger-entry persistence model
• Actuator health and Prometheus metrics
• Docker, Compose, Helm, GitHub Actions
• Kotlin Compose Multiplatform client for desktop and Android
• detekt, ktlint, Kover, CycloneDX SBOM
• ADRs, runbook, engineering standards, and roadmap

Why this project exists

This is designed as a Kotlin ramp-up and platform ownership template. It gives you a codebase you can extend while learning the language, and it gives a fintech company an immediately recognizable structure for production services.

Requirements

• JDK 21
• Docker and Docker Compose
• PostgreSQL client optional

Quick start

make db-up
make build
make run

Create a payment:

curl -i -X POST http://localhost:8080/payments \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: demo-key-12345678' \
  -d '{
    "debtorAccountId": "11111111-1111-1111-1111-111111111111",
    "creditorAccountId": "22222222-2222-2222-2222-222222222222",
    "amount": "10.00",
    "currency": "EUR"
  }'

Repeat the same request with the same idempotency key. The response should include:

Idempotent-Replay: true

Compose client

Run the backend first, then launch the desktop app:

make client-run

The client lives in composeApp/desktop-client and now uses a shared Compose Multiplatform UI for desktop and Android. It can check backend health, create idempotent payments, and fetch payments by ID. The desktop target defaults to http://localhost:8080; the Android target defaults to http://10.0.2.2:8080 for emulator use. See docs/CLIENT_APP.md.

Build the Android debug APK with:

make client-android-assemble

Install it onto a running emulator or connected phone with:

make client-android-install

If both a phone and an emulator are connected, use the explicit target:

make client-android-install-device
# or
make client-android-install-emulator

For a USB-connected phone, tunnel the backend port first so the app can use http://localhost:8080:

make client-android-reverse

Check your Android device visibility and local SDK wiring with:

make client-android-doctor

Local observability stack

docker compose up --build

The Dockerfile is multi-stage, so Compose can build the application image even if you only have Docker locally.

Services:

• App: http://localhost:8080
• Health: http://localhost:8080/actuator/health
• Prometheus metrics: http://localhost:8080/actuator/prometheus
• Prometheus: http://localhost:9090
• Grafana: http://localhost:3000 with admin / admin

Project layout

src/main/kotlin/com/ryangr0/fintechstarter
  domain/       Pure domain model and events
  application/  Use cases, ports, transaction boundary
  adapter/      HTTP, persistence, external systems
  config/       Spring wiring
composeApp/desktop-client
  Compose Multiplatform desktop and Android client
src/main/resources/db/migration
  Flyway migrations
docs
  Architecture, standards, ADRs, roadmap, runbooks
deploy/helm
  Kubernetes deployment scaffold
observability
  Prometheus and OpenTelemetry collector config

Main learning targets

1. Kotlin language: value classes, data classes, null-safety, sealed results, immutable modeling.
2. Backend: Spring Boot, validation, JDBC, transactions, Flyway.
3. Fintech: money, idempotency, ledger entries, auditability.
4. DevOps: CI, SBOM, Docker, Helm, health checks, metrics.
5. Engineering leadership: ADRs, standards, roadmap, runbook.

Next extensions

See docs/ROADMAP.md and docs/CLIENT_APP.md.