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.xmlwithspring-boot-starter-parent4.1.x,maven.compiler.release25, Flyway, mssql-jdbc, ArchUnit, JaCoCo, PIT.spring.threads.virtual.enabled=true.console/with Vite + React 19 + TypeScript; Node version pinned in.nvmrc.
Verification¶
- [ ]
mvn -vand 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.