ADR-003: Java/Spring Boot Version Standardization
ADR-003: Java/Spring Boot Version Standardization
Status
Proposed — Pending engineering team review
Context
All Gen 2 services run Java 21 / Spring Boot 3.5.4 except the content service which runs Java 24. Gen 1 services (being retired) used Java 11 / Spring Boot 2.4-2.6. Shared libraries (core-lib 0.0.67-69, messages 0.0.48-73) have version drift across services.
Decision
Standardize all services on Java 21 LTS / Spring Boot 3.x (latest stable) and align shared library versions.
Specific Actions
- Downgrade content service from Java 24 to Java 21 LTS (non-LTS versions risk support gaps)
- Align core-lib to latest version (0.0.69) across all services
- Align messages lib to latest version (0.0.73) across all services
- Enhance core-lib with idempotency support in MessageHandler and circuit breakers for external calls
- Maintain Spring Boot 3.x — upgrade to latest patch as they release
Why Java 21 LTS (Not Java 24)
| Criterion | Java 21 | Java 24 |
|---|---|---|
| LTS support | Yes (Sept 2023 — Sept 2031) | No (non-LTS) |
| Already used by | 28+ services | 1 service (content) |
| Spring Boot support | Full | Experimental |
| Library compatibility | Proven | Potential issues |
Hypothesis Background
Primary: Java 21 LTS with aligned shared libraries provides a stable, maintainable foundation (H13 L1).
Alternative 1: Upgrade all services to Java 24 (latest). - Rejected: Non-LTS release, shorter support cycle, potential library compatibility issues.
Alternative 2: Allow mixed Java versions per service. - Rejected: Operational complexity (different base images, testing matrix), core-lib compatibility risk.
Falsifiability Criteria
- If Java 21 cannot support a required feature (e.g., new JVM capability needed) → evaluate Java 25 LTS when available
- If Spring Boot 3.x reaches EOL before migration completes → upgrade to next Spring Boot major version
Evidence Quality
| Evidence | Assurance |
|---|---|
| 28+ services on Java 21/SB 3.5.4 | L2 (verified from build files) |
| core-lib works across versions 0.0.67-69 | L1 (H13) |
| Content service Java 24 is anomaly | L2 (verified) |
Overall: L1
Bounded Validity
- Scope: All Gen 2 backend services
- Expiry: Re-evaluate at Java 25 LTS release (expected Sept 2025)
- Review trigger: If Spring Boot 4.x requires Java 25+
Consequences
Positive: Uniform base images, simplified CI/CD, consistent debugging, shared library compatibility guaranteed. Negative: Content service loses Java 24 features (if any were used). Must test all services after core-lib alignment. Mitigated by: Java 24 features used by content service (if any) likely available via preview flags on Java 21, or are convenience features not business-critical.
Decision date: 2026-01-30 Review by: 2026-07-30