Saltar a contenido

ADR-001 — Stack: Spring Boot 4.1 direct on Java 25, SQL Server, React console

Status

Accepted (human, 2026-10-01: "Spring Boot 4.1 directo"; 2026-10-02: central server runs SQL Server 2022 on Windows Server).

Context

  • The value of the gateway is in the money path (27 s complete intention, automatic compensation, reversals), not in CRUD.
  • Both reference gateways were generated with JHipster (4.14 and 8.1) and ended up with 1,000–1,500-line controllers, entities exposed on public endpoints and migrations out of sync with the database.
  • It runs on the same central server as GatewayQR (SPEC §3.0), which today runs a Java 8 WAR against SQL Server.
  • No fixed go-live (the 2026-10-16 pilot date was dropped on 2026-10-02); the expected operating life is several years.

Alternatives

Option Pros Cons
Spring Boot 4.1 direct, hexagonal (chosen) Architecture fits the money path; same pattern as BeneficiosCenter Console built by hand
JHipster 9 CRUD, users and admin generated Layered generation fights hexagonal design; history of drift in both sibling repos

Decision

  • JDK: Eclipse Temurin 25 LTS (supported until 2031-09-30).
  • Framework: Spring Boot 4.1.x (Spring Framework 7, Jackson 3), Spring MVC with virtual threads for the bounded POS wait. OSS support for 4.1 ends 2027-07-31: plan the upgrade to the next minor line before that date.
  • Persistence: Spring Data JPA + Flyway on SQL Server 2022 (mainstream support until 2028-01-11, extended until 2033-01-11).
  • Runtime host: Windows Server, as a Windows service next to GatewayQR (separate service, port and log folder).
  • Console: React 19 + Vite + TypeScript, built with Node 24 LTS (supported until 2028-04-30), same look and patterns as the BeneficiosCenter console.
  • Build: Maven 3.9.

Consequences

  • Java 25 must be installed side by side with GatewayQR's Java 8 on the central server; separate service, port and logs.
  • A Spring Boot minor upgrade is a scheduled task before 2027-07-31.
  • SQL Server 2022 stays supported for the whole expected life of the pilot and first years of operation.

Implementation Plan

  • pom.xml with spring-boot-starter-parent 4.1.x, maven.compiler.release 25, Flyway, mssql-jdbc, ArchUnit, JaCoCo, PIT.
  • spring.threads.virtual.enabled=true.
  • console/ with Vite + React 19 + TypeScript; Node version pinned in .nvmrc.

Verification

  • [ ] mvn -v and the build run on Java 25.
  • [ ] The application starts against the central SQL Server version with Flyway migrations applied from an empty database.
  • [ ] ArchUnit test enforces that the domain does not depend on Spring, JPA or Jackson.