jvm-core

name	jvm-core
description	Shared reference for the JVM cluster: the language × framework decision (Kotlin vs Java; Spring Boot vs Quarkus vs Ktor), the build/test/coverage toolchain, the persistence choice (JPA/Hibernate vs Exposed), and the patterns → TDD → security → verification lifecycle. USE WHEN choosing a JVM stack, wiring persistence, or planning the test/security/release loop every JVM spoke shares.
cluster	jvm
version	1.0.0

JVM Core

Shared model for the jvm cluster. The framework, persistence, testing, security, and verification spokes all depend on these decisions — keep them consistent here so no spoke contradicts another.

1. The decision this cluster turns on: language × framework

Every JVM service starts with two choices, and they cascade into which spokes apply:

Language ──┐
           ├──> Framework ──> Patterns + TDD + Security + Verification spokes
Persistence┘

• Language — Kotlin (null-safe, coroutines, DSLs → kotlin-patterns) or Java (immutable-by-default, streams, records → java-coding-standards). Pick one per module.

• Framework — the heart of the decision:

  Framework	Pick it when	Spokes
  Spring Boot	Mature ecosystem, broad library support, team familiarity, JVM-mode services	springboot-patterns, springboot-tdd, springboot-security, springboot-verification
  Quarkus 3.x LTS	Native images, fast startup/low memory, event-driven (Camel), Kubernetes-first	quarkus-patterns, quarkus-tdd, quarkus-security, quarkus-verification
  Ktor	Lightweight Kotlin-native server, coroutine-first, minimal magic	kotlin-ktor-patterns
  none / library / KMP	Pure Kotlin/Java lib or shared UI	kotlin-patterns, compose-multiplatform-patterns

• Persistence — JPA/Hibernate for Java/Spring Boot (jpa-patterns) or JetBrains Exposed for Kotlin (kotlin-exposed-patterns). Don't run both in one module.

Rule: one language + one framework + one persistence layer per service. Crossing streams (Spring patterns inside a Quarkus module, JPA next to Exposed) is the main failure mode.

2. Shared conventions

• Kotlin — prefer immutability (val), express absence with nullable types not null hacks, model states with sealed classes/enums, build readable APIs with DSLs. → kotlin-patterns
• Java — final fields, Optional for absence (not as a field), streams for transforms, checked vs unchecked exceptions deliberate, constructor injection. → java-coding-standards
• Concurrency — Kotlin uses structured concurrency + Flow (kotlin-coroutines-flows); Java/Spring uses @Async/reactive, Quarkus uses Mutiny/reactive — keep async in the framework's idiom.
• Validation — validate every external input at the boundary (request DTOs, command args); never trust caller data. This is shared across all four *-security and *-patterns spokes.
• Layering — controller/resource → service → repository; keep persistence types out of the web layer. → springboot-patterns, quarkus-patterns.

3. Version / tooling matrix

Concern	Kotlin stack	Spring Boot stack	Quarkus stack
Language	Kotlin (latest stable)	Java 17+ (LTS)	Java 17+ (LTS)
Framework	Ktor / KMP	Spring Boot 3.x	Quarkus 3.x LTS
DI	Koin	Spring context	CDI (Arc)
Persistence	Exposed + HikariCP + Flyway	JPA/Hibernate	Panache (JPA/Hibernate)
Test runner	Kotest + MockK	JUnit 5 + Mockito + MockMvc + Testcontainers	JUnit 5 + Mockito + REST Assured
Coverage	Kover	JaCoCo	JaCoCo
Messaging	—	Spring events / async	Apache Camel
Build	Gradle (Kotlin DSL)	Gradle / Maven	Gradle / Maven (+ native)

Serialization: kotlinx.serialization (Kotlin/Ktor); Jackson (Spring Boot / Quarkus JSON).

4. The lifecycle every stack shares

patterns ──> TDD ──> security ──> verification

1. Patterns — architecture + conventions for the chosen framework.
2. TDD — write tests first (*-tdd / kotlin-testing); aim for meaningful coverage, not a number.
3. Security — authn/authz, input validation, CSRF, secrets, headers, dependency scanning (*-security).
4. Verification — build → static analysis → tests+coverage → security scan → (Quarkus: native compile) → diff review before PR/release (*-verification).

5. Shared guardrails

• One stack per module: don't mix Spring Boot and Quarkus, or JPA and Exposed, in one service.
• Tests first: features/bugfixes go through the *-tdd / kotlin-testing loop before merge.
• Security is not optional: run the matching *-security spoke; validate all external input.
• Gate releases: nothing ships until the matching *-verification loop is green.
• Kotlin null-safe, Java immutable-by-default: lean on the language's safety guarantees.
• Spring Boot vs Quarkus: choose Spring Boot for ecosystem breadth and team familiarity; choose Quarkus for native images, fast startup, low memory, and event-driven/Kubernetes-first services. Choose Ktor when you want a lightweight, coroutine-first Kotlin server.