Sequence Diagrams: Spring Boot 4.1 Upgrade¶
- PRD: PRD-spring-boot-4-upgrade
- ADR: 0033-spring-boot-4-upgrade
- Spec: spec-spring-boot-4-upgrade
- Status: Done
The upgrade adds no new flow. These diagrams show the existing flows whose internals change: which component now does the work (Jackson 3, jjwt-orgjson, Boot 4 modules), and where the spec's rules and edge cases apply.
1. Startup on the prod VM (Boot 4.1)¶
The JVM starts with the runtime flags from the server-side startServer.sh (the prod copy may differ from the repo's api/startServer.sh, which runs java $JAVA_OPT -jar funny-app-1.0.0.jar; --enable-preview is set in pom.xml for the compiler and surefire). Liquibase must find nothing to apply, and the JWT/JSON classes are warmed up before Tomcat accepts traffic (spec FR-2, FR-5, Rule 6, EC-9).
sequenceDiagram
autonumber
participant SH as startServer.sh (JVM flags)
participant BOOT as Spring Boot 4.1 (main thread)
participant LQ as Liquibase (Boot 4 module)
participant DB as PostgreSQL
participant JWT as JwtProvider.warmUp()
participant TC as Tomcat
participant ACT as /actuator/health
SH->>BOOT: java $JAVA_OPT -jar funny-app-1.0.0.jar
BOOT->>LQ: auto-configure (spring.liquibase.*)
LQ->>DB: read DATABASECHANGELOG
DB-->>LQ: all changesets applied by 3.5 build
LQ-->>BOOT: 0 pending changesets (Rule 6)
BOOT->>JWT: @PostConstruct warmUp()
JWT->>JWT: Jwts.builder()...compact() (org.json writer init)
JWT->>JWT: parser.parseSignedClaims() (org.json reader init)
Note over JWT: class init on main thread, not on virtual threads (EC-9)<br/>any Exception is caught and logged as a warning, startup is never blocked
BOOT->>TC: start connector :8081
TC-->>BOOT: accepting requests
ACT-->>SH: UP
2. Authenticated request with a token issued before the upgrade¶
A user who logged in on 3.5 calls an API after the deploy. The JSON claims are now parsed by org.json instead of Jackson 2 (spec Rule 5, EC-1, EC-2).
sequenceDiagram
autonumber
actor U as User
participant FE as Browser (webapp)
participant F as JWT filter (Security 7 chain)
participant JP as JwtProvider.verifyToken()
participant OJ as jjwt-orgjson reader
participant C as Controller (/v1/funny-app/...)
participant MVC as Spring MVC JsonMapper (Jackson 3)
U->>FE: open app (token from 3.5 in storage)
FE->>F: GET /v1/funny-app/... Authorization: Bearer <3.5 token>
F->>JP: verifyToken(token)
JP->>OJ: parse header + claims JSON
OJ-->>JP: claims {id, email, role, permissions, cv?}
JP->>JP: signature check with JWT_SECRET (unchanged)
JP->>JP: convertValue: id→Long, permissions→int, cv→int or 0
JP-->>F: UserDetailDto (same as on 3.5)
F->>C: request with SecurityContext
C-->>MVC: ResultObjectInfo<T>
MVC-->>FE: 200 JSON (same fields/values, order may differ)
FE-->>U: page renders as before
3. Expired or tampered token¶
The failure path keeps the same sub-codes and body format (spec EC-3, FR-4).
sequenceDiagram
autonumber
participant FE as Browser (webapp)
participant F as JWT filter
participant JP as JwtProvider.verifyToken()
participant UE as UnauthorizedException.toJson()
FE->>F: request with expired or tampered token
F->>JP: verifyToken(token)
alt expired
JP-->>F: throw UnauthorizedException("TOKEN_EXPIRED", 602)
else bad signature / malformed
JP-->>F: throw UnauthorizedException("TOKEN_INVALID", 601)
end
F->>UE: toJson() with shared Jackson 3 mapper config
UE-->>F: {"status":"FAILED","error":{... "timestamp":"dd-MM-yyyy hh:mm:ss"}}
F-->>FE: 401 + same body as 3.5
4. Request body deserialization rules¶
How the Jackson 3 mapper configured in FR-4 handles a client request body (spec Rules 3–4, EC-4, EC-5, EC-6).
sequenceDiagram
autonumber
participant FE as Browser (webapp)
participant MVC as Spring MVC JsonMapper (Jackson 3, FR-4 config)
participant C as Controller
participant CA as @ControllerAdvice
FE->>MVC: POST/PATCH body JSON
alt null for primitive field
MVC->>C: field = 0 / false (FAIL_ON_NULL_FOR_PRIMITIVES=false)
C-->>FE: 200 as on 3.5
else unknown property
MVC->>C: property ignored (FAIL_ON_UNKNOWN_PROPERTIES=false)
C-->>FE: 200 as on 3.5
else trailing tokens after root value
MVC-->>CA: HttpMessageNotReadableException (Jackson 3 default)
CA-->>FE: 400 ResultErrorInfo (accepted change, Rule 4)
end
5. Parsing an external payload with a code-built mapper¶
The classes that built their own ObjectMapper now use the shared Jackson 3 settings, so a provider adding fields does not break parsing (spec FR-4, EC-5). This example uses yt-dlp; YouTube API, GitHub webhook and ChatGPT follow the same pattern.
sequenceDiagram
autonumber
participant W as VideoImportWorker
participant Y as YtDlpClientImpl
participant P as yt-dlp process
participant M as JsonMapper (shared FR-4 settings)
W->>Y: fetchMetadata(url)
Y->>P: yt-dlp -J --skip-download [--cookies file] -- url
P-->>Y: JSON (may contain new fields)
Y->>M: readTree
alt malformed output
M-->>Y: JacksonException (unchecked, was JsonProcessingException)
Y-->>W: ImportException(EXTRACTOR_ERROR)
else null, not an object, or no id
M-->>Y: JsonNode without id
Y-->>W: ImportException(code mapped from stderr)
else valid
M-->>Y: JsonNode (unknown fields ignored)
Y-->>W: VideoMetadata
end
6. Deploy and rollback¶
The upgrade ships as one artifact. Rollback means redeploying the previous 3.5 artifact; no database step is needed (spec NFR Availability, Rule 6). In funnyapp-ci.yml the test job gates both docker and deploy; the deploy job copies the JAR to the VM and runs the deploy script over SSH.
sequenceDiagram
autonumber
actor O as Owner
participant GH as GitHub Actions (funnyapp-ci.yml)
participant REG as Docker Hub / Helm values.yaml
participant VM as Prod VM
participant APP as funny-app 4.1
participant DB as PostgreSQL
O->>GH: push main (after approval)
GH->>GH: build job: mvn package -DskipTests → funny-app-1.0.0.jar
GH->>GH: test job: mvn verify (JsonContractTest) + Sonar
GH->>GH: separate step: LINE coverage ≥ api/.coverage-threshold (90%)
par docker job (needs test)
GH->>REG: push image prod-N, bump api/.funny-app.version and Helm values.yaml tag
and deploy job (needs test)
GH->>VM: SCP funny-app-1.0.0.jar
GH->>VM: SSH: run deploy script
end
VM->>APP: start (diagram 1)
APP->>DB: Liquibase: 0 pending
O->>APP: prod smoke test (login, MFA, stream, import, admin, SSE)
alt smoke test fails or app hangs
O->>VM: redeploy previous 3.5 JAR
VM->>DB: no migration to revert
VM-->>O: 3.5 back within 10 min
else all pass
O-->>O: watch 7 days for incidents
end