ADR-002 — Stack and lifecycle
- Status: accepted (2026-11-16)
Context
ADR-001 derives the gateway from GatewayPrismaQR, so the stack is inherited from that project. The gateway database runs on a CYRE server with SQL Server 2022. The operator asked whether SQL Server 2016 can also be supported.
Alternatives
- Inherit the GatewayPrismaQR stack as is. Chosen. Node 24 is replaced by Node 26 LTS for the UI build, because Node 24 is already in maintenance.
- Certify SQL Server 2016 as a supported target. Rejected: its extended support ended on 2026-07-14 (paid ESU only, to 2029-07-17), and certifying it needs a 2016 instance in CI.
Decision
- Target: Java 25 LTS, Spring Boot 4.1.x, Hibernate 7.4, mssql-jdbc 13.x, Flyway, React 19, Vite 8, and Node 26 LTS for the build only. SQL Server 2022 is the only certified database.
- SQL Server 2016 is "compatible, not certified". Flyway migrations use only T-SQL available
in SQL Server 2016 SP1 (no
STRING_AGG,TRIM,CONCAT_WSorGREATEST/LEAST). Nothing is tested against 2016 in CI. The facts behind this: Hibernate 7.4SQLServerDialectminimum is SQL Server 2014; Flyway v10+ removed the paid-license requirement for older database versions. (origin: agent, confirmed: 2026-11-16) -
Upgrade policy: Spring Boot 4.1 OSS support ends 2027-07-31. Move to the next Spring Boot minor line within 6 months of its release, and always before the current line's OSS end date. New dependencies require the operator's approval. (origin: agent, confirmed: 2026-11-16)
-
Console build (slice 2b):
frontend-maven-plugin1.15.1 builds the React console from Maven (npm ci, lint, test, build with Node 26.13.1 downloaded intoconsole/node/) and packs it into the gateway jar. The build needs network access to the Node and npm registries. (human decision, approved 2026-11-17) -
BootUI, development only (2026-11-17, approved by the operator):
bootui-spring-boot-starter2.3.0 (Apache-2.0, Java 17+) serves a local developer console at/bootui. It is built against Spring Boot 4.1.2 but runs on this project's 4.1.1 BOM (the parent manages its Spring Boot dependencies down to 4.1.1: a patch-level skew). It is added only by the opt-in Maven profilebootuiingateway/pom.xml, never active by default, so the default build and the release jar do not contain it, nor its transitive actuator, OpenTelemetry and ArchUnit. Reason: it shows HTTP exchanges, SQL, the environment and heap dumps, and its ownSECURITY.mdforbids production use, so it would break C2 (the municipal API key never leaves the gateway) and C3 (the legajo is never logged). Version 2.3.0 was chosen over the newer 2.5.0 (released the day before, as reported by the upstream changelog) to keep a minimum age on new dependencies. - Guards:
BootUiAbsentFromDefaultBuildTestfails the default build if BootUI, the actuator or OpenTelemetry reaches the classpath another way (thebootuiprofile excludes that one test, somvn -Pbootui verifyruns the rest of the suite).DevelopmentBuildProdGuardrefuses to start under theprodorproductionSpring profile when BootUI or the actuator is on the classpath. The profile names its jargatewayqrmunic-<version>-bootui-DEV-ONLY.jar, so it never shares the release jar's name. - Activation: in its default
AUTOmode BootUI turns on under the Spring profiledevorlocal(or withbootui.enabled=ON, or when spring-boot-devtools is on the classpath, which the gateway does not have) and turns itself off underprodorproduction. Only while it is active does it expose its fixed list of 11 actuator endpoints (health, info, beans, conditions, configprops, env, loggers, mappings, metrics, startup, scheduledtasks) on the same loopback port, without authentication. - Hardening, in the committed
local | testdocument ofapplication.yml:management.endpoints.access.default: read-only(no write operations on those endpoints) andbootui.heap-dump.capture-enabled: false(a heap dump holds the master key, the database password and the decrypted merchant keys in clear). Under thedevprofile these two settings do not apply. BootUI writes to.bootui/(heap dumps under.bootui/heap-dumps);.bootui/and*.hprofare gitignored. - How to run:
mvn -Pbootui -DskipTests package, then startgateway/target/gatewayqrmunic-<version>-bootui-DEV-ONLY.jarwith Spring profilelocal(--spring.profiles.active=local) and openhttp://localhost:8080/bootui. - Release rule: release builds use
mvn clean ...without-Pbootui, andjar tf <release jar>must list nobootui,actuatororopentelemetryentry. (human decision, approved 2026-11-17)
Consequences
- Spring Boot 4.1 has a short window: if the go-live is in early 2027, an upgrade is due within about 7 months.
- Running on SQL Server 2016 is at the customer's risk: the engine is out of vendor support.
Implementation Plan
- Copy
pom.xmland the consolepackage.jsonfrom GatewayPrismaQR; pin the Node version (enginesand the build plugin) to 26. - Flyway migrations: a review rule that rejects T-SQL newer than SQL Server 2016 SP1.
Verification
- [ ] The build uses Java 25 and Node 26 (checked in the build log).
- [ ] Integration tests pass against SQL Server 2022.
- [ ] Flyway migrations contain none of the T-SQL features listed above.