Kotlin Demo Fintech Starter

This repository is now a Kotlin Multiplatform fintech starter rather than the stock template. It keeps the backend contract shared across platforms, exposes a small Ktor payment API, and ships a Compose workbench that can exercise the API from desktop, Android, and web targets.

Phase 1 Complete: Operations & Documentation foundation is now in place. See BEST_OF_BOTH_INTEGRATION_PLAN.md for the 6-phase roadmap combining baseline maturity (security, deployment, runbook) with current KMP/Ktor strengths.

Modules

• shared: payment and ledger contracts, validation helpers, and a multiplatform payments API client.
• server: Ktor service with typed routes, idempotent payment creation, JDBC repositories, Flyway migrations, and request observability.
• composeApp: Compose Multiplatform workbench for health checks, payment creation, payment fetch, and recent activity.
• iosApp: native iOS shell for the shared Compose app.

Implemented backend slice

• GET /health
• GET /metrics
• POST /payments
• GET /payments/{id}
• X-Correlation-Id request and response support
• PostgreSQL-backed production wiring with Flyway migrations

Example create request:

curl -i http://localhost:8080/payments \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: demo-payment-001' \
  -d '{
    "debtorAccountId": "11111111-1111-1111-1111-111111111111",
    "creditorAccountId": "22222222-2222-2222-2222-222222222222",
    "amount": "125.50",
    "currency": "USD"
  }'

Local run paths

Full stack with Docker

docker compose up --build

This starts:

• PostgreSQL on localhost:5432
• the Ktor app on localhost:8080

Server from Gradle

The production module defaults to these local database settings:

• DATABASE_URL=jdbc:postgresql://localhost:5432/fintech
• DATABASE_USERNAME=fintech
• DATABASE_PASSWORD=fintech

So if PostgreSQL is running locally, this is enough:

./gradlew :server:run

Compose workbench

./gradlew :composeApp:run

Other useful targets:

• Android: ./gradlew :composeApp:assembleDebug
• Web: ./gradlew :composeApp:jsBrowserDevelopmentRun
• Wasm web: ./gradlew :composeApp:wasmJsBrowserDevelopmentRun

Validation

Primary quality gate:

./gradlew clean qualityCheck --no-daemon

Focused regression command:

./gradlew :shared:jvmTest :server:test :composeApp:compileKotlinJvm --no-daemon

Convenience Makefile targets:

make help              # List all Makefile targets
make clean            # Clean build artifacts
make build            # Build all modules (no tests)
make test             # Run all tests (unit + integration)
make lint             # Run ktlint and detekt checks
make format           # Auto-format Kotlin code
make validate         # Full validation (clean build, lint, tests, coverage, SBOM)
make up               # Start Docker Compose stack (Postgres + app)
make down             # Stop Docker Compose stack
make logs             # Follow app logs
make server-run       # Run Ktor server locally
make ui-run           # Run Compose workbench (Desktop)

server:test now includes Testcontainers-backed JDBC repository integration tests, so Docker must be available when that task runs.

qualityCheck currently runs ktlint on the handwritten shared and server modules, plus detekt, coverage, and SBOM generation across the repo. This keeps the aggregate gate stable while Compose-generated resource files still produce noisy ktlint failures.

Repo docs

• Planning & Roadmap

  • docs/BEST_OF_BOTH_INTEGRATION_PLAN.md: 6-phase roadmap combining baseline strengths (security, deployment, ADRs, runbook) with current KMP/Ktor architecture
  • docs/KOTLIN_30_60_90_ROADMAP.md: platform roadmap (30-day service baseline, 31-60 persistence/CI/observability, 61-90 platform standardization)
  • docs/NEXT_15_STEPS.md: tactical execution sequence and follow-on work phases
  • docs/IMPLEMENTATION_BACKLOG.md: delivered scope and remaining gaps

• Architecture & Standards

  • docs/ARCHITECTURE.md: module structure, data flow, persistence layer, observability, error handling, deployment options
  • docs/adr/: Architectural Decision Records
    • 0001-use-ktor-instead-of-spring-boot.md: Why Ktor over Spring Boot
    • 0002-use-explicit-jdbc.md: Why explicit JDBC over ORM
    • 0003-contract-first-shared-types.md: Why contract-first KMP architecture
    • 0004-compose-multiplatform.md: Why Compose for all UI targets
    • 0005-testcontainers.md: Why Testcontainers for integration tests
  • docs/ENGINEERING-STANDARDS.md: code style, testing, API design, dependency management, security, performance practices

• Operations & Security

  • docs/SECURITY.md: security baseline, controls, Kotlin/JVM notes, dependency management, compliance
  • docs/RUNBOOK.md: health checks, common issues (database, duplicates, latency, state inconsistency), local development workflow, performance tuning, escalation

• Historical

  • docs/PORTING_BLUEPRINT.md: mapping from the original fintech app into this repo