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

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.