Engineering & Architecture Documentation
Comprehensive architectural blueprints, microservices domain models, security governance, database persistence baselines, and verification standards for the national land administration platform.
Table of Contents
Cadastral Information System (CIS)¶
Welcome to the engineering documentation portal for the Cadastral Information System (CIS) platform.
CIS is an enterprise cadastral land management and user access governance solution built with modern Java 25, Spring Boot 4.1.2, Spring Security (OAuth2 / OIDC), Oracle 23, Redis, RustFS (S3 Object Storage), SFTP/FTP data interchange, and Camunda/Workflow processing engines.
Architecture at a Glance¶
The CIS platform is architected around specialized backend services, designed for separation of concerns, strict boundary security, and high-throughput cadastral data processing.
[!NOTE] For the comprehensive end-to-end request flow, detailed security trust boundaries, and per-module specifications, see the System Architecture Guide.
Subsystem Topology¶
The internal domain topology coordinates the 6 core cadastral modules inside cis-api, embedded query and template libraries, and long-running BPMN execution in cis-workflow:
System Communication Flow¶
| Step / Flow | Source | Target | Protocol / Transport | Security & Credentials | Description |
|---|---|---|---|---|---|
| 1. Client Ingress | Browser / Client | cis-bff (:8080) |
HTTPS | Encrypted Session Cookie (HttpOnly, SameSite=Lax) |
User interacts with UI; cookies shield access tokens from XSS. |
| External Ingress | Surveyors / Partners | FTP/SFTP (:2121/:2022) |
FTP / SFTP over SSH | Dedicated SFTP User Credentials & SSH Keys | Upload of bulk shapefiles, raw surveyor coordinates, and deed archives. |
| 2. Auth & Login | cis-bff (:8080) |
cis-auth (:8085) |
OAuth 2.1 / OIDC | Authorization Code Flow with PKCE (S256) |
Authenticates users, validates LDAP/WebAuthn, issues signed JWTs. |
| Directory Auth | cis-auth (:8085) |
OpenLDAP (:10389) |
LDAPv3 over TCP | Service Bind Account | Verifies internal staff credentials and group memberships. |
| 3. API Proxy | cis-bff (:8080) |
cis-api (:8089) |
HTTP REST | Authorization: Bearer <JWT> |
Proxies cadastral queries, reservation, and lodgement requests. |
| 4. Workflow Proxy | cis-bff (:8080) |
cis-workflow (:8090) |
HTTP REST | Authorization: Bearer <JWT> |
Proxies user task lists, approvals, and process transitions. |
| 5. Process Sync | cis-api (:8089) |
cis-workflow (:8090) |
REST / BPMN | Internal Mutual Auth / Bearer | Triggers stage escalations, SLA checks, and status changes. |
| Database I/O | cis-api / workflow |
Oracle 23 (:1521) |
JDBC (HikariCP) | Encrypted DB Credentials | Persists spatial records, land registers, and audit events. |
| Caching & Sync | cis-bff / api |
Redis 7.4 (:6379) |
RESP over TCP | Redis Auth Password | Distributed sessions, token revocation blacklist, and ShedLock. |
| Object Storage | cis-api (:8089) |
RustFS S3 (:9000) |
AWS S3 REST API | AWS Access Key & Secret Key | Stores and retrieves survey diagrams, deeds, and PDF dockets. |
| Batch Ingestion | cis-api (:8089) |
FTP/SFTP (:2121/:2022) |
SFTP Client (JSch) | SFTP Service Account | Automated polling and ingestion of surveyor batch files. |
| Email Relay | cis-emailer (in cis-api) |
Mailpit (:1025) |
SMTP | Standard SMTP | Dispatches customer receipts, approval notices, and certificates. |
| SMS Dispatch | cis-api (:8089) |
SMS Gateway (HTTP) |
REST API (POST) | API Key / Token Authentication | Sends instant SMS status notifications and OTP verification alerts. |
| Stamping Service | cis-api (:8089) |
Stamping Service (:8000) |
HTTP REST | Internal Service Token | Digital watermarking and official seal generation for cadastral plans. |
[!TIP] For in-depth domain specifications of the 6 core business modules inside
cis-api(Information System, Reservation, Lodgement, Relodgement, Maintenance, and Archival & HRA), see the cis-api Deep Dive.
Documentation Quick Links¶
| Section | Description |
|---|---|
| Getting Started | Prerequisites, local setup with Docker, and building services |
| Architecture | Subproject roles, runtime topology, and inter-service communication |
| Security & Authentication | OIDC / OAuth2 token flows, Passkeys (WebAuthn), and BFF pattern |
| Database & Persistence | Oracle 23 schema baseline, Flyway migrations, and JPA query optimization |
| Testing & Quality | RestTestClient, Testcontainers (Oracle, Redis, LDAP), and Jacoco standards |
| Operations & Deployment | Bitbucket CI/CD pipelines, Docker tagging, and Mailpit setup |
| Requirements | Business workflows (cancellation, exercision, maintenance) |
| Engineering Audits | Compiler warnings remediation, startup benchmarks, and security audits |
| PDF & Single HTML Export | Complete unified documentation book formatted for PDF download or single HTML export |
Core Technologies¶
- Language Runtime: Java 25
- Framework: Spring Boot 4.1.2 (Spring Framework 7)
- Build System: Gradle 8.10+
- Security: Spring Authorization Server (OIDC 1.0, OAuth 2.1, Passkeys / WebAuthn)
- Data Stores: Oracle Database 23 Free / Enterprise, Redis 7.4 Alpine
- Object Storage: RustFS (High-performance S3-compatible storage with Web Console on port 9000/9001)
- File Transfer: FTP / SFTP Server (Port 2121 / 2022) for bulk surveyor files & shapefiles
- External Integrations: SMS Gateway (Applicant mobile alerts), Stamping Service (Port 8000 watermarking), Mailpit / SMTP (Port 1025)
- Directory Service: OpenLDAP / Microsoft Active Directory (Port 10389)
- Documentation: MkDocs Material (Hermetic, repo-sandboxed)
Getting Started
Getting Started¶
This guide provides everything needed to bootstrap, configure, build, and run the CIS platform locally.
Prerequisites¶
Before starting, verify the following tools are installed on your host workstation:
| Prerequisite | Recommended Version | Verification Command |
|---|---|---|
| JDK (Java) | Java 25 (OpenJDK / Eclipse Temurin) | java -version |
| Docker Engine | Docker Desktop 24+ / Docker CE with Compose v2 | docker compose version |
| Git | 2.40+ | git --version |
| Python | 3.10+ (for local sandboxed docs) | python --version |
[!NOTE] Gradle is managed directly by the repository wrapper (
./gradlewor.\gradlew.bat). You do not need a separate global Gradle installation.
Onboarding Pathway¶
- Local Setup: Configure environment files (
.env.dev), start supporting containers (Oracle, Redis, LDAP, Mailpit), and understand port assignments. - Build & Test: Compile services, run offline Gradle builds, execute Testcontainers integration tests, and inspect JaCoCo coverage reports.
- IDE Setup: Configure IntelliJ IDEA or VS Code for Lombok, MapStruct annotation processing, and profile management.
Local Development Setup¶
CIS services rely on infrastructure services (Oracle 23, Redis 7, OpenLDAP, Mailpit) orchestrated via Docker Compose.
1. Environment Configuration¶
CIS uses environment variable separation across runtime profiles (dev, uat, prod):
- Root .env.dev: Controls Docker Compose port bindings and volume mounts.
- Service .env.dev: Controls Spring Boot properties for each respective service.
Ensure you have a .env.dev created in the repository root from .env.dev.example (or existing dev template).
2. Starting Local Companion Infrastructure¶
You can launch the backing data stores and companion services without running the Spring Boot applications inside containers:
# Start Oracle Database, Redis, OpenLDAP, and Mailpit
docker compose --env-file=.env.dev up -d oracle-db redis cis-ldap mailpit
Port Allocation Reference¶
| Deployable Service | Host Port | Protocol / Purpose |
|---|---|---|
| cis-bff | 8080 |
Backend-For-Frontend Reverse Proxy & Browser Gateway |
| cis-auth | 8085 |
OAuth2 / OIDC Authorization Server |
| cis-api | 8089 |
Core Cadastral REST APIs (Embeds cis-search & cis-emailer) |
| cis-workflow | 8090 |
Workflow Execution Engine |
| Oracle DB | 1521 |
Database Listener (SID: XE / PDB: FREEPDB1) |
| Redis | 6379 |
Token Blacklist & Session Store |
| OpenLDAP | 10389 |
LDAP Directory Service (Host: 10389 -> Container: 389) |
| Mailpit Web UI | 8025 |
Mock SMTP Mailbox Browser |
| Mailpit SMTP | 1025 |
Local SMTP Server |
[!NOTE] - Local File Storage: In local development (
devprofile), file uploads are written directly to local disk (app.file-storage.storage-location: runtime/uploads), so running an S3 object store like RustFS is not required locally. RustFS is utilized in server deployments (UAT / Production). - Embedded Submodules:cis-searchandcis-emailerare internal library modules compiled directly intocis-api(implementation project(":cis-search")andimplementation project(":cis-emailer")). They do not expose standalone HTTP/REST ports.
3. Running Services Locally¶
You can launch any service using the Spring Boot Gradle plugin or your IDE:
# Run cis-auth (port 8085)
.\gradlew.bat :cis-auth:bootRun --args="--spring.profiles.active=dev"
# Run cis-bff (port 8080)
.\gradlew.bat :cis-bff:bootRun --args="--spring.profiles.active=dev"
# Run cis-api (port 8089)
.\gradlew.bat :cis-api:bootRun --args="--spring.profiles.active=dev"
# Run cis-workflow (port 8090)
.\gradlew.bat :cis-workflow:bootRun --args="--spring.profiles.active=dev"
Once running:
- BFF login entrypoint: http://localhost:8080/bff/auth/authorize?clientId=cis-bff-internal-client
- OIDC Discovery: http://localhost:8085/.well-known/openid-configuration
- Mailpit UI: http://localhost:8025
Building & Testing¶
This document outlines the standard Gradle commands and testing strategies across CIS modules.
1. Compilation & Full Builds¶
The project uses Gradle 8.10+ wrapper for reproducible builds.
# Compile all sources (offline mode supported)
.\gradlew.bat compileJava --offline
# Full build skipping test suite execution
.\gradlew.bat build -x test --offline
2. Running Test Suites¶
CIS test suites are categorized into:
- Unit & Slice Tests: Fast tests running in memory with @WebMvcTest or RestTestClient.
- Integration Tests: Comprehensive authentic tests utilizing Docker Testcontainers for Oracle 23, Redis 7.4, and OpenLDAP.
# Run tests for a specific module
.\gradlew.bat :cis-auth:test
.\gradlew.bat :cis-bff:test
.\gradlew.bat :cis-api:test
# Run all tests across the repository
.\gradlew.bat test
[!TIP] Running tests that use Testcontainers requires Docker to be running locally. Testcontainers will automatically spin up isolated containers and tear them down after test completion.
3. Code Coverage with JaCoCo¶
Coverage is monitored via JaCoCo across all subprojects.
# Generate JaCoCo coverage report for a specific module
.\gradlew.bat :cis-bff:jacocoTestReport
# Output report: cis-bff/build/reports/jacoco/test/html/index.html
# Generate unified aggregate coverage report across the entire repository
.\gradlew.bat jacocoRootReport
# Output report: build/reports/jacoco/jacocoRootReport/html/index.html
Coverage Targets¶
- Target Line Coverage: > 90%
- Target Instruction Coverage: > 90%
- All new controllers must use Spring's modern
RestTestClientasserting HTTP status, headers, and body structures via AssertJ.
IDE Setup & Configuration¶
CIS projects make extensive use of code generation via Lombok and MapStruct. Proper IDE configuration ensures smooth compile-on-save and auto-completion.
IntelliJ IDEA Setup¶
1. Enable Annotation Processing¶
MapStruct and Lombok generate code during compilation:
1. Open Settings / Preferences (Ctrl + Alt + S).
2. Navigate to Build, Execution, Deployment > Compiler > Annotation Processors.
3. Check Enable annotation processing.
4. Set Store generated sources relative to: Module content root.
2. Configure JDK 25¶
- Navigate to File > Project Structure > Project.
- Set SDK to Java 25.
- Set Language Level to 25.
3. Gradle Runner Configuration¶
- Navigate to Settings > Build, Execution, Deployment > Build Tools > Gradle.
- Under Build and run using:, select Gradle (Default).
- Under Run tests using:, select Gradle (Default).
- Set Gradle JVM: Project SDK (25).
Visual Studio Code Setup¶
If working in VS Code, install the recommended extensions:
- Extension Pack for Java (vscjava.vscode-java-pack)
- Gradle for Java (vscjava.vscode-gradle)
- Spring Boot Extension Pack (vmware.vscode-spring-boot)
- Lombok Annotations Support (gayanm.ms-vscode-lombok)
Add the following to .vscode/settings.json:
Architecture
System Architecture¶
The Cadastral Information System (CIS) is an integrated national land management platform designed for strict perimeter security, multi-role cadastral workflows, and high-throughput spatial land transaction processing.
System Architecture Diagram¶
Below is the verified end-to-end system architecture representing all active application tiers, security boundaries, internal services, persistence engines, and external integrations:
End-to-End Request Lifecycle & Flow¶
Every request within CIS follows a deterministic 4-stage lifecycle ensuring strict defense-in-depth, token privacy, stateless microservice processing, and decoupled asynchronous storage:
Subsystem Topology & Domain Architecture¶
The internal domain topology coordinates the 6 core cadastral modules inside cis-api, embedded query and template libraries, and long-running BPMN execution in cis-workflow:
System Communication Flow¶
| Step / Flow | Source | Target | Protocol / Transport | Security & Credentials | Description |
|---|---|---|---|---|---|
| 1. Client Ingress | Browser / Client | cis-bff (:8080) |
HTTPS | Encrypted Session Cookie (HttpOnly, SameSite=Lax) |
User interacts with UI; cookies shield access tokens from XSS. |
| External Ingress | Surveyors / Partners | FTP/SFTP (:2121/:2022) |
FTP / SFTP over SSH | Dedicated SFTP User Credentials & SSH Keys | Upload of bulk shapefiles, raw surveyor coordinates, and deed archives. |
| 2. Auth & Login | cis-bff (:8080) |
cis-auth (:8085) |
OAuth 2.1 / OIDC | Authorization Code Flow with PKCE (S256) |
Authenticates users, validates LDAP/WebAuthn, issues signed JWTs. |
| Directory Auth | cis-auth (:8085) |
OpenLDAP (:10389) |
LDAPv3 over TCP | Service Bind Account | Verifies internal staff credentials and group memberships. |
| 3. API Proxy | cis-bff (:8080) |
cis-api (:8089) |
HTTP REST | Authorization: Bearer <JWT> |
Proxies cadastral queries, reservation, and lodgement requests. |
| 4. Workflow Proxy | cis-bff (:8080) |
cis-workflow (:8090) |
HTTP REST | Authorization: Bearer <JWT> |
Proxies user task lists, approvals, and process transitions. |
| 5. Process Sync | cis-api (:8089) |
cis-workflow (:8090) |
REST / BPMN | Internal Mutual Auth / Bearer | Triggers stage escalations, SLA checks, and status changes. |
| Database I/O | cis-api / workflow |
Oracle 23 (:1521) |
JDBC (HikariCP) | Encrypted DB Credentials | Persists spatial records, land registers, and audit events. |
| Caching & Sync | cis-bff / api |
Redis 7.4 (:6379) |
RESP over TCP | Redis Auth Password | Distributed sessions, token revocation blacklist, and ShedLock. |
| Object Storage | cis-api (:8089) |
RustFS S3 (:9000) |
AWS S3 REST API | AWS Access Key & Secret Key | Stores and retrieves survey diagrams, deeds, and PDF dockets. |
| Batch Ingestion | cis-api (:8089) |
FTP/SFTP (:2121/:2022) |
SFTP Client (JSch) | SFTP Service Account | Automated polling and ingestion of surveyor batch files. |
| Email Relay | cis-emailer (in cis-api) |
Mailpit (:1025) |
SMTP | Standard SMTP | Dispatches customer receipts, approval notices, and certificates. |
| SMS Dispatch | cis-api (:8089) |
SMS Gateway (HTTP) |
REST API (POST) | API Key / Token Authentication | Sends instant SMS status notifications and OTP verification alerts. |
| Stamping Service | cis-api (:8089) |
Stamping Service (:8000) |
HTTP REST | Internal Service Token | Digital watermarking and official seal generation for cadastral plans. |
[!TIP] For exhaustive domain specifications of the 6 core business modules inside
cis-api, see cis-api Deep Dive.
Subproject Ecosystem Matrix¶
| Subproject / Component | Responsibility | Primary Stack | Dependencies |
|---|---|---|---|
cis-auth |
Identity Provider & OAuth2 / OIDC Authorization Server | Spring Authorization Server, Nimbus JOSE, LDAP, Redis, Oracle | Oracle, Redis, LDAP |
cis-bff |
Backend-for-Frontend & Reverse Proxy | Spring Boot Web, Spring Security OAuth2 Client, Redis Session Store | cis-auth, cis-api, Redis |
cis-api |
Cadastral domain entities, REST APIs, land parcel management | Spring Boot Web, Spring Data JPA, Hibernate, Oracle JDBC | Oracle DB, cis-workflow, RustFS, SFTP |
cis-workflow |
Long-running BPMN business processes, transitions, and approvals | Spring Boot, Flowable / Camunda workflow engine | Oracle DB, cis-api |
cis-emailer |
Asynchronous email formatting, notification dispatch, and attachments | Spring Boot Mail, Flying Saucer PDF, Thymeleaf, JavaMailSender | Mailpit / SMTP Server |
cis-search |
High-performance full-text search indexing and spatial queries | Solr / Elasticsearch / Spring Data Search | Search Cluster |
| RustFS S3 | S3-compatible high-performance object and blob storage | RustFS Server & Console, S3 API | Persistent Volume Storage |
| FTP / SFTP Server | Secure external bulk shapefile, scan, and surveyor coordinates ingestion | Apache MINA / OpenSSH SFTP Daemon (Ports 2121, 2022) | Local / Network Filesystem |
| SMS Gateway | Instant SMS notifications and OTP dispatch to applicants & surveyors | HTTP REST Client | External Telco / SMS Provider |
| Stamping Service | Dedicated plan watermarking, cryptographic digital signing, and seals | Python / Java Microservice (Port 8000) | cis-api REST callers |
Architectural Principles¶
- Defense-in-Depth & Boundary Security:
cis-bffacts as the exclusive public ingress point for user browsers.- Browser sessions hold an HTTP-only, SameSite encrypted session cookie.
- OIDC Bearer tokens (
access_token,refresh_token) never leak to the client browser. - Stateless Business Processing:
cis-apiandcis-workflowoperate purely as stateless OAuth2 Resource Servers verifying cryptographically signed JWT tokens issued bycis-auth.- Dedicated Object Storage (RustFS):
- Cadastral documents, reservation acknowledgement receipts, scan attachments, and batch dockets are stored as blobs in RustFS via S3 API (
:9000), rather than bloating the relational database tables with BLOBs. - Resilient Asynchronous Ingestion (FTP / SFTP):
- External land surveyor batch submissions, GIS shapefiles, and large deed scan archives are transferred via secure SFTP/FTP endpoints on ports 2022/2121, decouled from synchronous REST API timeouts.
- Database Federation:
- Schemas are partitioned logically; migrations are governed strictly via Flyway scripts.
Runtime Topology & Configuration Capture¶
Overview¶
- Services in scope: Spring Boot
cis-api(Jetty on${SERVER_PORT:8089}) and the Angular frontend bundles (cis-external,cis-internal,cis-workflow-studio) to be published behind nginx. - Execution model:
cis-apiruns as a single JVM with ShedLock, Redis-backed caching, SMTP, LDAP, and multiple HTTP(S)/FTP integrations. Frontend artifacts are static Angular builds served via nginx with SPA rewrites.
cis-api Runtime Inputs¶
- Process basics: Bootable jar launched with
JAVA_OPTS="-XX:+UnlockExperimentalVMOptions -XX:+UseCGroupMemoryLimitForHeap -XX:+UseG1GC"(see Dockerfile). HTTP port supplied viaSERVER_PORT. - Core configuration:
.env.exampleenumerates datasource, Redis, SMTP, LDAP, workflow, stamping, FTP, and DigitalOcean Spaces values. Spring profiles map toapplication-*.yaml(dev,uat,dalrrd) with Oracle + Redis defaults and LDAP credentials. - Secrets location: Local keystores (
jwt.jks,/cis-api/src/main/resources/keystore/) and LDAP bind details already live undersrc/main/resources; production secrets must be injected at runtime (env vars or mounted files) rather than committed. - File system touch points:
/data/uploads↔APP_STORAGE_LOCATION/app/logsfor Logback appenders- Optional keystores/public keys bound into
/app/config(documented indocs/docker/cis-api.md) - External dependencies: Oracle DB, Redis (7.x), OpenLDAP / Active Directory, RustFS S3 Object Storage (
:9000), SMTP gateway (Mailpit in dev), FTP server, workflow/stamping HTTP APIs. ShedLock currently uses Redis vianet.javacrumbs.shedlock-provider-redis-spring.
Angular + nginx Notes¶
- Source located in
CIS-WEB-ANGULAR/CIS/cis-web/with Angular CLI projects per sub-app (cis-external,cis-internal,cis-workflow-studio). - Legacy nginx added compression, caching headers, and SPA fallback; exact rules pending infra export. Build artifacts land in
dist/<app>afternpm ci && npm run build --prod.
Outstanding Information Needed¶
- nginx configuration: need the current
/etc/nginx/conf.d/*.confor equivalent to port existing headers, caching, and proxy rules. - Production environment variables: confirm authoritative values for Oracle/Redis/LDAP, plus non-standard JVM flags (heap sizing, GC logging) if different from defaults.
- Secrets management process: clarify whether Docker secrets, Vault, or Kubernetes secrets will supply sensitive values.
- Inbound networking: document load balancer ports, TLS termination points, and any mutual TLS/whitelisting requirements for the
cis-apicontainer.
Modules
Module: cis-api (Core Cadastral Engine)¶
cis-api is the foundational transactional core of the Cadastral Information System (CIS). Running on Java 25 with Spring Boot 4.1.2, it encapsulates the statutory land administration domains, spatial property registration, survey examination, and historical records preservation.
1. Domain Architecture Overview¶
cis-api acts as a stateless OAuth2 Resource Server listening on port 8089. It validates RS256 cryptographically signed JSON Web Tokens (JWT) forwarded by cis-bff and orchestrates seven major business domain modules:
graph TD
classDef domain fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px,color:#1B5E20;
classDef lib fill:#E0F7FA,stroke:#00838F,stroke-width:1.5px,color:#006064;
API[cis-api Core Application :8089]
subgraph BUSINESS_MODULES["Core Cadastral Business Modules"]
INFO["1. Information System & Data Viewer"]:::domain
RESERV["2. Reservation Engine"]:::domain
LODGE["3. Lodgement Engine"]:::domain
EXAM["4. Examination Engine<br/>(Phase 1 & Phase 2 Examination)"]:::domain
RELODGE["5. Relodgement Engine"]:::domain
MAINT["6. Maintenance Engine"]:::domain
ARCH["7. Archival & Historical Records (HRA)"]:::domain
end
subgraph EMBEDDED_LIBS["Embedded Submodules"]
SEARCH["cis-search<br/>(Spatial & Lucene Search)"]:::lib
EMAIL["cis-emailer<br/>(PDF Generation & Email Notifications)"]:::lib
end
API --> INFO
API --> RESERV
API --> LODGE
API --> EXAM
API --> RELODGE
API --> MAINT
API --> ARCH
INFO -.->|Search Queries| SEARCH
INFO -.->|Dispatch Mails| EMAIL
RESERV -.->|Acknowledgement Notices| EMAIL
LODGE -.->|Batch Handoff| EXAM
LODGE -.->|Proforma Invoices| EMAIL
EXAM -.->|Defect Queries| RELODGE
EXAM -.->|Query & Outcome Letters| EMAIL
EXAM -.->|Approved Dockets| ARCH
RELODGE -.->|Amended Batches| EXAM
RELODGE -.->|Acknowledgement Notices| EMAIL
MAINT -.->|Outcome Letters| EMAIL
ARCH -.->|Catalog Indexing| SEARCH
ARCH -.->|PlanSafe Strongroom Tracking| EMAIL
2. Deep Dive: Core Business Modules¶
Module 1: Information System & Data Viewer — Lifecycle Management¶
The Information System & Data Viewer is the public-facing and professional discovery gateway of the Cadastral Information System (CIS). It enables registered land surveyors, conveyancers, government planners, and citizens to discover, inspect, simulate statutory fees, purchase, and extract authoritative cadastral diagrams, beacon coordinates, ownership records, and spatial layers.
1.1 Complete End-to-End Lifecycle Vector Architecture¶
Below is the verified end-to-end 6-stage lifecycle architecture of the Information System:
1.2 Chronological Stage-by-Stage Lifecycle Walkthrough¶
%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '14px', 'fontFamily': 'Roboto', 'lineColor': '#066636' }}}%%
flowchart LR
classDef stage fill:#E8F5E9,stroke:#066636,stroke-width:2px,color:#003319;
classDef action fill:#FFFFFF,stroke:#3b82f6,stroke-width:1.5px,color:#1e3a8a;
classDef complete fill:#F3E8FF,stroke:#7E22CE,stroke-width:2px,color:#581C87;
S1["1. Search & Discovery<br/>(Parcel / Erf / Farm / Scheme)"]:::stage
S2["2. Spatial Data Viewer<br/>(Overlay Layers & Beacons)"]:::stage
S3["3. Cart & Quota<br/>(Alpha / Diagram / Spatial)"]:::stage
S4["4. Fee Simulator & Proforma<br/>(Statutory Tariffs & PDF)"]:::stage
S5["5. Checkout Settlement<br/>(Payment / Exemption Hook)"]:::stage
S6["6. S3 Packaging & Dispatch<br/>(ZIP Stream & Notification)"]:::complete
S1 --> S2 --> S3 --> S4 --> S5 --> S6
Stage 1: Multi-Criteria Search & Discovery Engine¶
- Objective: Rapidly identify cadastral land parcels, survey records, and spatial units across millions of national records.
- Core Mechanisms:
- Parcel Search (
ParcelSearchService): Queries parcels by administrative hierarchy (Province, Major Region, Minor Region, Erf Number, Portion Number, Farm Name, Agricultural Holding). - Sectional Title Search (
SectionalSearchService): Locates sectional schemes by scheme name, filing year, registration number, or unit number. - SG Number Search (
NumberSearchService): Direct lookups by statutory Surveyor-General Diagram number (e.g.,SG Dsg No 1234/2024), General Plan (GP), Compilation number, or Lease record. - Street Address Search (
StreetSearchService): Cross-references municipal street numbers and road centerlines with underlying cadastral polygons. - NGI Geodetic Search (
NgiSearchService): Discovers national geodetic beacons, trigonometrical stations, and GPS benchmarks.
- Parcel Search (
- Query Acceleration with
cis-search:- Utilizes embedded Lucene indices synchronized with the
SearchContextenum (PARCEL,FARM,SECTIONAL_TITLE,NGI) to achieve sub-second response times without cross-network RPC latency.
- Utilizes embedded Lucene indices synchronized with the
Stage 2: Interactive Spatial Data Viewer & Coordinate Inspection¶
- Objective: Allow users to visually verify spatial boundaries, neighboring cadastre, servitudes, and beacon coordinates prior to procurement.
- Core Capabilities (
DataViewerResource,DataViewerService):- Layer Configuration (
DataViewerConfiguration): Retrieves active spatial layers categorized by statutory hierarchy (Erven,Farm Portions,Servitudes,Mining Rights,Municipal Reserves). - Spatial SQL Projection (
DataViewerCustomImpl): Executes dynamic spatial geometry queries (CustomQueryResultSetProjection) to project bounding polygons and beacon coordinates directly onto client web map controls. - Session Audit Logging (
DataViewerLog): Automatically logs the requesting user ID, spatial bounding box coordinates, zoom scale, and access timestamp to enforce audit accountability.
- Layer Configuration (
Stage 3: Shopping Cart Assembly & Quota Management¶
- Objective: Aggregate requested documents and data extracts, determine statutory item classifications, and evaluate user quota allowances.
- Granular Item Data Models (
CartItems):- AlphaNumeric Data (
CartItemAlphaNumericData): Official land registry ownership records, parent title deed references, and registered endorsements. - Survey Diagram Documents (
CartItemDiagramData): High-resolution digital scans and PDF copies of official Surveyor-General diagrams. - Spatial Data Exports (
CartItemSpatialData): Machine-readable ESRI Shapefiles, DXF CAD files, and ASCII beacon coordinate tables. - Certified Copies (
CartItemCertificateData): Statutorily certified cadastral extracts required for legal proceedings or deeds office registration.
- AlphaNumeric Data (
- Quota & Staging Engine (
CartStage,CartStageData):- Items are staged in transient
CartStagerecords. - The engine evaluates whether the user represents an exempt statutory entity (e.g., Municipal Planner, Department of Rural Development) or an account holder with free monthly quota balances.
- Items are staged in transient
Stage 4: Fee Simulation & Proforma Invoicing¶
- Objective: Mathematically compute authoritative statutory tariffs, apply VAT, and generate formal proforma invoice documentation.
- Tariff Calculation Mechanics (
FeeSimulatorService):- Resolves item costs dynamically via
InvoiceItemCostProjectionbased on data classification, output format (PDF vs Shapefile), and page count. - Eliminates client-side price tampering by computing all financial line items exclusively on the backend.
- Resolves item costs dynamically via
- Proforma Invoice Compilation (
InvoiceResource,InvoiceService):- Creates an official
InvoicePerformaentity associated with a unique transaction reference andworkflowId. - Flying Saucer (XHTML-to-PDF) compiles a formal tax invoice document featuring statutory headers, breakdowns, and payment EFT reference codes.
- Triggers
InvoiceNotificationviacis-emailerto dispatch the proforma invoice directly to the customer's email.
- Creates an official
Stage 5: Order Checkout & Workflow State Promotion¶
- Objective: Validate payment settlement (or statutory exemption) and promote the transient staging cart to an active fulfillment order.
- Checkout Processing (
CartResource.checkout):- Ingests
CheckoutVmcarrying the payment confirmation token, credit card gateway receipt, or official statutory fee waiver certificate. - Invokes
CartResource.addToFinalCart(addCartHook):- Migrates items from
CartStageto permanentCartandCartItemstables. - Assigns a formal tracking number (
CIS-INF-YYYY-NNNNNN). - Cleans up transient staging tables (
/api/cart/empty).
- Migrates items from
- Promotes the
cis-workflowbusiness process state toPAID/DISPATCH_READY.
- Ingests
Stage 6: S3 Document Packaging & Multi-Channel Dispatch¶
- Objective: Assemble requested cadastral files from secure object storage, compress into a secure ZIP container, and fulfill delivery across digital channels.
- Automated Packaging Pipeline (
DispatchResource,GlobalDispatchService):- Object Storage Retrieval: Fetches raw diagram PDFs and shapefiles directly from RustFS S3 (
Port 9000). - Zero-Disk-Leak Streaming: Uses Java's
ZipOutputStreamto stream the compresseddocs.ziparchive directly to the client or storage destination without creating temporary files on the container filesystem. - Secure Download Token: Generates an encrypted, time-limited token granting access to the assembled archive.
- Object Storage Retrieval: Fetches raw diagram PDFs and shapefiles directly from RustFS S3 (
- Multi-Channel Fulfillment:
- Email Delivery:
cis-emailerdispatches completion notifications with secure download links via Mailpit / SMTP (Port 1025). - SFTP Push: For bulk corporate orders or external data partners,
uploadDocsOnFtpautomatically pushes batch archives directly to the SFTP Server (Port 2022). - Applicant SMS: Enqueues an instant tracking SMS via the SMS Gateway confirming that the cadastral documents are ready for download.
- Email Delivery:
1.3 Detailed Sequence Interaction Diagram¶
The sequence diagram below details the chronological request-reply interaction across all tiers during an Information System transaction:
sequenceDiagram
autonumber
actor User as Citizen / Professional Surveyor
participant BFF as cis-bff (:8080)
participant API as cis-api (:8089)
participant Search as cis-search (In-Memory)
participant WF as cis-workflow (:8090)
participant S3 as RustFS S3 (:9000)
participant Mail as Mailpit / SMTP (:1025)
participant DB as Oracle Database 23 (:1521)
%% 1. Search Phase
User->>BFF: POST /api/search/parcel (Erf 104, Pretoria)
BFF->>API: Forward with Bearer JWT
API->>Search: Execute spatial Lucene query (SearchContext.PARCEL)
Search->>DB: Query relational parcels & beacons
DB-->>API: Return ParcelErfProjection
API-->>User: Search Results (Available Diagram PDFs & Shapefiles)
%% 2. Cart & Quota Phase
User->>BFF: POST /api/cart/add (CartStageDataDto)
BFF->>API: Add Item to Stage
API->>DB: Persist transient CartStage & CartStageData
API-->>User: Cart Stage Updated (Item count: 1)
%% 3. Invoicing Phase
User->>BFF: POST /api/invoice/save (Request Proforma)
BFF->>API: Generate Invoice Data
API->>API: FeeSimulatorService: Compute statutory tariff
API->>DB: Persist InvoicePerforma record
API->>Mail: Dispatch Proforma Invoice PDF to customer
API-->>User: Proforma Invoice Generated (Invoice #INV-2026-089)
%% 4. Checkout Phase
User->>BFF: POST /api/cart/checkout (CheckoutVm: Proof of Payment)
BFF->>API: Execute Checkout Hook
API->>DB: Finalize Cart & promote CartStage -> Cart
API->>WF: Transition state to PAID (Trigger AutoDispatchWorkflow)
WF-->>API: Workflow State = DISPATCH_READY
API-->>User: Checkout Successful (Order #ORD-2026-4412)
%% 5. Fulfillment Phase
WF->>API: Trigger GlobalDispatchService
API->>S3: Retrieve Diagram PDFs & Shapefiles (S3 API :9000)
S3-->>API: Binary file streams
API->>API: ZipOutputStream: Stream into docs.zip
API->>S3: Store final assembled docs.zip
API->>Mail: Send completion email with secure download token
API-->>User: Order Fulfilled (Download link active)
1.4 State Machine: Cart & Order Progression¶
stateDiagram-v2
[*] --> BROWSE: User searches land records
BROWSE --> STAGED: Item added to cart (CartStage)
STAGED --> STAGED: Modify items / Add bulk
STAGED --> PROFORMA_ISSUED: Checkout initiated (Fee simulator executed)
PROFORMA_ISSUED --> SETTLED: Payment confirmed or statutory exemption verified
PROFORMA_ISSUED --> CANCELLED: Stale stage cleanup / User empties cart
SETTLED --> FINALIZED: addCartHook promotes CartStage to permanent Cart
FINALIZED --> PACKAGING: GlobalDispatchService fetches S3 blobs
PACKAGING --> COMPLETED: docs.zip assembled, email sent, SMS dispatched
COMPLETED --> [*]
1.5 Information System REST API Reference Matrix¶
| HTTP Verb | Endpoint | Handler Method | Request Body / Params | Primary Role / Description |
|---|---|---|---|---|
POST |
/api/search/parcel |
SearchResource.searchParcel |
ParcelSearchVm |
Queries land parcels by Erf, Portion, Farm, or Allotment. |
POST |
/api/search/sectional |
SearchResource.searchSectional |
SectionalSearchVm |
Queries sectional title schemes and registered unit numbers. |
POST |
/api/search/number |
SearchResource.searchNumber |
NumberSearchVm |
Direct lookup by SG Diagram, GP, or compilation reference. |
GET |
/api/data-viewer/getObjectType |
DataViewerResource.getType |
None | Lists distinct spatial layer categories available for display. |
POST |
/api/data-viewer/execute/query |
DataViewerResource.executeCustomQuery |
DataViewerRequestVm |
Projects spatial geometry and beacon coordinates for map display. |
GET |
/api/cart/ |
CartResource.getCartDetails |
userId |
Retrieves active user cart and staged procurement items. |
POST |
/api/cart/add |
CartResource.addToCart |
CartStageDataDto |
Adds an alphanumeric, diagram, or spatial item to staging cart. |
POST |
/api/cart/checkout |
CartResource.checkout |
CheckoutVm |
Executes order checkout, payment validation, and exemption checks. |
POST |
/api/invoice/items/cost |
InvoiceResource.getInvoiceItemCosting |
InvoiceItemCostVm |
Computes dynamic statutory tariff fees via FeeSimulatorService. |
GET |
/api/invoice/generate |
InvoiceResource.generatePdf |
workflowId |
Compiles official Flying Saucer PDF tax invoice docket. |
GET |
/api/dispatch/downloadDispatchDocs |
DispatchResource.downloadZippedDocs |
workflowId |
Streams assembled docs.zip package via ZipOutputStream. |
POST |
/api/dispatch/sendDispatchEmail/{id} |
DispatchResource.sendDispatchEmail |
workflowId |
Dispatches completion notification with secure download token. |
Module 2: Reservation Engine — Statutory Algorithms & Lifecycle Architecture¶
The Reservation Engine is the statutory land administration engine of the Cadastral Information System (CIS). Prior to conducting an on-the-ground physical survey, a Professional Land Surveyor (PLS) must obtain authoritative, unique, and statutorily reserved parcel identifiers (Erf numbers, Farm portion numbers, Leasehold identifiers) from the Surveyor-General (SG).
The engine enforces strict statutory numbering sequences, validates parent property records against the national land cadastre, manages multi-step draft survey progression, generates cryptographic barcode acknowledgement dockets, enforces SLA retention periods, and handles surveyor-to-surveyor ownership transfers.
2.1 Complete End-to-End Lifecycle Vector Architecture¶
Below is the verified end-to-end 6-stage lifecycle architecture of the Reservation Engine, illustrating draft progression, the 12 statutory algorithms, dual staging/final execution pipelines, barcode dockets, and automated lifecycle monitors:
2.2 Chronological Stage-by-Stage Lifecycle Walkthrough¶
%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '14px', 'fontFamily': 'Roboto', 'lineColor': '#1e3a8a' }}}%%
flowchart LR
classDef stage fill:#EFF6FF,stroke:#1E40AF,stroke-width:2px,color:#1E3A8A;
classDef algo fill:#FEF3C7,stroke:#D97706,stroke-width:2px,color:#78350F;
classDef complete fill:#ECFDF5,stroke:#047857,stroke-width:2px,color:#064E3B;
S1["1. Surveyor Draft Wizard<br/>(Multi-Step Auto-Save)"]:::stage
S2["2. Parent Parcel Scrutiny<br/>(Cadastre Boundary Audit)"]:::stage
S3["3. Algorithmic Preview<br/>(AlgoOutputType.STAGING)"]:::algo
S4["4. Scrutiny & Lodgement<br/>(QC Checklist & Checkout)"]:::stage
S5["5. SG Approval & Commit<br/>(AlgoOutputType.FINAL)"]:::complete
S6["6. Lifecycle Monitoring<br/>(SLA Timers & Expiry)"]:::complete
S1 --> S2 --> S3 --> S4 --> S5 --> S6
Stage 1: Surveyor Application & Multi-Step Draft Wizard¶
- Objective: Allow professional surveyors to incrementally draft complex land transactions spanning multiple statutory actions without risk of session data loss.
- Core Capabilities (
ReservationDraftService,ReservationDraftStepsService):- Draft Persistence: Surveyors initiate a reservation docket (
ReservationDraft) linked to their professional council accreditation ID. - Step-Level Isolation (
ReservationDraftSteps): Complex survey schemes (e.g., closing a public lane and consolidating it with five adjoining erven) are constructed as distinct, sequential steps. - Outcome Chaining (
isCopyOutcomeOfPrevious = true): The engine enables outputs of step \(N\) (e.g., newly formed parcels from a Street Closure) to be fed directly as inputs into step \(N+1\) (e.g., Consolidation) viaaddDraftStepByOutcomeIdsandaddDraftRequestByOutcomeIds.
- Draft Persistence: Surveyors initiate a reservation docket (
Stage 2: Parent Parcel Designation & Validation Scrutiny¶
- Objective: Validate the legal existence, parent ownership, and administrative boundary integrity of the land parcels subject to reservation.
- Cadastral Validation Mechanics (
ProcessReservationAlgo,LodgementValidationService):- Queries the core land registry to ensure the parent Erf or Farm portion is currently in an
ACTIVEun-cancelled state. - Verifies that the parcel is not currently locked by an existing pending survey reservation or expropriation caveat.
- Resolves administrative boundaries: Province -> Registration Division -> Major Region (Municipality) -> Minor Region (Township/Allotment Area).
- Queries the core land registry to ensure the parent Erf or Farm portion is currently in an
Stage 3: Algorithmic Preview Execution (AlgoOutputType.STAGING)¶
- Objective: Allow the surveyor to execute reservation algorithms in simulation mode, inspecting provisional parcel numbers and remainder designations before statutory commitment.
- Staging Mechanics (
ReservationAlgoFactory):- When
processReservationDraftAlgois called withAlgoOutputType.STAGING:- The factory resolves the concrete algorithm corresponding to the statutory
ReservationReason. - The algorithm computes provisional numbers, remaining balances, and parent-child linkages in memory.
- Transient records are written to
ReservationDraftOutcomemarked asSTAGED. - Crucially, the persistent global parcel sequence counters in the database are not incremented, preventing sequence gaps if the surveyor modifies the proposal.
- The factory resolves the concrete algorithm corresponding to the statutory
- When
Stage 4: Examiner Scrutiny, Checklists & Lodgement Checkout¶
- Objective: Enforce cadastral compliance checklists, assemble applicant affidavits, and execute formal lodgement checkout.
- Scrutiny & Checkout Pipeline (
ReservationResource.saveDraftCheckout):- Evaluates mandatory statutory questions (
ReservationDraftChecklist): municipal planning approval references, environmental authorization flags, and consent endorsements. - Surveyors upload supporting documentation (town planning consent dockets, draft sketches) directly to RustFS S3 (
Port 9000). - Invokes
saveDraftCheckoutto promote the draft into a formal reservation docket:- Transitions draft state to
SUBMITTED. - Dispatches a process execution event to
cis-workflow(Port 8090), placing the dossier into the Surveyor-General scrutiny work queue.
- Transitions draft state to
- Evaluates mandatory statutory questions (
Stage 5: Surveyor-General Approval, Final Number Commitment & Barcode Docket¶
- Objective: Authorize reservation, commit irrevocable statutory parcel numbers, and generate legally certified acknowledgement letters.
- Final Execution & Docket Generation (
AlgoOutputType.FINAL,ReservationAcknowledgementLetterService):- Upon examination officer sign-off in
cis-workflow, the engine triggersProcessReservationAlgowithAlgoOutputType.FINAL. - Pessimistic Lock & Sequence Commitment:
- Obtains an exclusive database lock on the township/farm sequence counter.
- Allocates official statutory parcel numbers (e.g.,
Erf 1052 Pretoria,Portion 44 of Farm Hartebeestpoort 410-JR). - Emits permanent records into
ReservationDraftOutcomeand core cadastral master tables.
- Certified Acknowledgement Letter:
- Generates an official Surveyor-General Acknowledgement Letter PDF via Flying Saucer.
- Embeds Code128 / QR barcodes encoding the reservation reference, assigned parcel numbers, allocation timestamp, and SG digital signature.
- Archives the generated PDF in RustFS S3 and delivers it to the surveyor via
cis-emailer(Mailpit,Port 1025).
- Upon examination officer sign-off in
Stage 6: Active Lifecycle Management, Automated Expiry & Ownership Transfer¶
- Objective: Enforce statutory reservation expiration timelines, issue proactive warning notifications, and facilitate surveyor transfers.
- Lifecycle Governance Mechanics:
- Automated Expiry Scheduler (
ReservationExpiryNotification,TaskReminderService):- Statutory parcel reservations remain valid for a legally mandated period (e.g., 24 months).
- A scheduled daemon periodically scans active reservations against system SLA clocks.
- Dispatches 60-day and 30-day proactive expiry reminder emails to the land surveyor.
- If unlodged upon deadline arrival, the engine triggers
EXPIREDstatus, freeing the reserved numbers back into the cadastral registry.
- Surveyor-to-Surveyor Transfer (
ReservationTransferOutcomeLetterService):- If a developer transfers land development rights to a new professional surveyor, the engine facilitates a formal cession workflow.
- Requires formal consent documentation, updates surveyor ownership references, generates an official Transfer Outcome Letter, and records an unalterable audit log.
- Automated Expiry Scheduler (
2.3 The 12 Statutory Land Administration Algorithms (Deep Dive)¶
The CIS Reservation Engine implements 12 distinct statutory land administration algorithms in package com.dw.ngms.cis.service.reservation.algo.*. Each algorithm enforces specific cadastral rules mandated by the Land Survey Act:
| Algorithm Name | Statutory Reason Code | Target Cadastral Domain | Calculation Mechanics & Number Allocation Rules | Remainder / Balance Preservation |
|---|---|---|---|---|
| Subdivision | SUBDIVISION |
Erven, Farms, Agricultural Holdings, Leases | Splits a parent parcel into \(N\) new child portions. Reads highest existing portion number for parent and assigns sequential integers \((max + 1) \dots (max + N)\). | Preserves un-subdivided remainder balance as Portion 0 (Remainder of Erf/Farm). |
| Consolidation | CONSOLIDATION |
Contiguous Erven, Farms | Merges two or more contiguous parcels into a single unified cadastral entity. Queries township registry and assigns the next highest unallocated Erf/Farm number. | Extinguishes all parent parcel numbers; marks parent records as superseded upon lodgement. |
| Excision | EXCISION |
Agricultural Holdings | Excises agricultural holding land out of an Agricultural Holdings Register and converts it into urban township erven under town planning schemes. | Records excision certificate references; adjusts holding balance or extinguishes holding entity. |
| Creation of Town | CREATION_OF_TOWN |
New Township Establishment | Allocates complete numbering sequence for a newly proclaimed township: Erven \(1 \dots N\), including parks, municipal erven, and institutional sites. | Establishes new township registry; links all child erven to the mother farm portions being built upon. |
| Extension of Township | EXTENSION_OF_TOWNSHIPS |
Township Extension Phases | Allocates additional erven for an existing proclaimed township (Phase 2, 3, etc.). Identifies the highest registered Erf number across all prior phases and begins from \((max + 1)\). | Maintains uninterrupted continuous numerical sequence across all township extensions. |
| Creation of Farm | CREATION_OF_FARMS |
Rural Cadastre / State Releases | Establishes a brand new farm entity within a Registration Division (e.g., Farm 950-JR). Allocates Portion 0 as the mother parcel. |
Assigns Registration Division code, initial mother boundary, and province reference. |
| Lease Erven | LEASE_ERVEN |
Long-Term Registered Leases | Allocates statutory leasehold parcel numbers (prefixed with L or distinct lease sequences) over an existing parent parcel without fee alienating the underlying freehold ownership. |
Underlying parent parcel remains intact and active; lease polygon is registered as a subordinate right. |
| Public Place Closure | PUBLIC_PLACE_CLOSURE |
Parks, Public Squares | Formally closes a municipal public open space, park, or civic square. Converts the closed space into one or more registrable Erf numbers. | Updates municipal vesting schedule; requires formal gazette proclamation reference. |
| Street Closure | STREET_CLOSURE |
Road Reserves, Lanes | Closes existing public road reserves, street lanes, or pedestrian walkways. Allocates provisional numbers to closed street strips for consolidation with adjoining owners. | Amalgamates closed road strips with contiguous erven or assigns standalone Erf numbers. |
| Re-Designation | RE_DESIGNATION |
Cadastral Unit Classification | Changes the statutory cadastral designation of a parcel (e.g., converting a Farm Portion absorbed into an urban boundary into an Erf number, or vice versa). | Maintains full historical cross-reference link between old designation and new statutory identifier. |
| Relay-Out | RELAYOUT |
Approved General Plans | Re-configures the internal parcel boundary layout of an approved General Plan (GP) before physical deeds registration has occurred. | Cancels prior provisional parcel numbers within the GP perimeter and assigns a re-indexed layout sequence. |
| State Land | STATELAND |
National & Provincial State Land | Administers statutory parcel reservations, subdivisions, and land disposals specifically governing state-owned property and communal land tenures. | Enforces ministerial consent validations and specialized state land registry prefixes. |
2.4 Multi-Step Draft Progression & Step Outcome Chaining¶
Real-world cadastral developments rarely involve a single isolated statutory action. A typical mixed-use urban development requires multiple interdependent steps:
%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '13px', 'fontFamily': 'Roboto' }}}%%
flowchart TD
classDef step fill:#EFF6FF,stroke:#2563EB,stroke-width:2px,color:#1E40AF;
classDef outcome fill:#FEF3C7,stroke:#D97706,stroke-width:1.5px,color:#78350F;
classDef final fill:#ECFDF5,stroke:#059669,stroke-width:2px,color:#065F46;
subgraph Step1["Step 1: Street Closure (PUBLIC_ROAD_CLOSURE)"]
P1["Input: Public Road Reserve<br/>(Church Street Strip)"]:::step
A1["Algorithm: StreetClosure"]:::step
O1["Outcome 1: Closed Street Strip<br/>(Provisional Erf 1050)"]:::outcome
P1 --> A1 --> O1
end
subgraph Step2["Step 2: Consolidation (CONSOLIDATION)"]
P2A["Input A: Closed Street (Erf 1050)"]:::step
P2B["Input B: Adjoining Property (Erf 104)"]:::step
A2["Algorithm: Consolidation"]:::step
O2["Outcome 2: Unified Consolidated Parcel<br/>(Provisional Erf 1051)"]:::outcome
O1 -.->|isCopyOutcomeOfPrevious = true| P2A
P2B --> A2
P2A --> A2
A2 --> O2
end
subgraph Step3["Step 3: Subdivision (SUBDIVISION)"]
P3["Input: Consolidated Erf 1051"]:::step
A3["Algorithm: Subdivision (3 Portions)"]:::step
O3A["Portion 1 of Erf 1051"]:::final
O3B["Portion 2 of Erf 1051"]:::final
O3C["Remainder of Erf 1051"]:::final
O2 -.->|isCopyOutcomeOfPrevious = true| P3
P3 --> A3
A3 --> O3A
A3 --> O3B
A3 --> O3C
end
Programmatic Mechanics of Chaining¶
ReservationDraftSteps: Each step in the wizard has an integerstepNoand a designatedReservationReason.- Outcome Staging: When Step 1 runs,
ProcessReservationAlgoinserts staged records intoReservationDraftOutcomewithstepNo = 1. - Automated Inheritance (
isCopyOutcomeOfPrevious): - When Step 2 is configured with
isCopyOutcomeOfPrevious = true,ReservationDraftService.addDraftStepByOutcomeIdscopies the outcome identifiers from Step 1 directly into the inputReservationDraftRequestlist for Step 2. - This ensures complete mathematical and legal continuity across chained surveyor applications.
2.5 Dual Execution Pipeline: STAGING vs FINAL¶
The reservation engine uses a dual execution mode defined by the AlgoOutputType enum:
%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '14px', 'fontFamily': 'Roboto' }}}%%
flowchart LR
classDef staging fill:#FFFBEB,stroke:#F59E0B,stroke-width:2px,color:#92400E;
classDef final fill:#F0FDF4,stroke:#16A34A,stroke-width:2px,color:#166534;
subgraph STAGING_PIPELINE["STAGING Execution Pipeline (Ephemeral Preview)"]
ReqS["Surveyor clicks 'Generate Preview'"]:::staging
CallS["processReservationDraftAlgo(STAGING)"]:::staging
CompS["Compute Next Sequential Numbers"]:::staging
PersS["Persist to ReservationDraftOutcome<br/>(Status = STAGED)"]:::staging
LockS["NO DB Sequence Lock Acquired<br/>(Global counters remain unchanged)"]:::staging
ReqS --> CallS --> CompS --> PersS --> LockS
end
subgraph FINAL_PIPELINE["FINAL Execution Pipeline (Statutory Commitment)"]
ReqF["Examiner clicks 'Approve Reservation'"]:::final
CallF["processReservationDraftAlgo(FINAL)"]:::final
LockF["Acquire Exclusive DB Sequence Lock"]:::final
IncrF["Increment Global Township/Farm Counter"]:::final
PersF["Write Permanent Reservation Records"]:::final
DocF["Generate Barcode Letter & QR Code"]:::final
ReqF --> CallF --> LockF --> IncrF --> PersF --> DocF
end
AlgoOutputType.STAGING:- Used during draft editing. Surveyors can recalculate numbers multiple times as plans evolve.
- Writes provisional outcomes to
ReservationDraftOutcome. If the draft is discarded, no database cleanup of statutory sequence tables is necessary. AlgoOutputType.FINAL:- Invoked exclusively by
cis-workflowupon formal Examiner approval. - Acquires a pessimistic database lock, increments the official statutory sequence counter, and guarantees that assigned parcel numbers are permanent and unalterable.
2.6 Detailed Sequence Interaction Diagram¶
The sequence diagram below details the chronological interaction across all architectural tiers during an end-to-end statutory reservation lifecycle:
sequenceDiagram
autonumber
actor PLS as Land Surveyor (PLS)
participant BFF as cis-bff (:8080)
participant API as cis-api (:8089)
participant Algo as ReservationAlgoFactory
participant WF as cis-workflow (:8090)
participant DB as Oracle Database 23 (:1521)
participant S3 as RustFS S3 (:9000)
participant Mail as Mailpit / SMTP (:1025)
%% 1. Draft Initiation
PLS->>BFF: POST /api/reservation/draft (Create Draft Docket)
BFF->>API: Forward with Bearer JWT
API->>DB: Persist ReservationDraft & Steps
DB-->>API: Return draftId = 5041
API-->>PLS: Draft Initialized
%% 2. Staging Algorithmic Preview
PLS->>BFF: POST /api/reservation/processDraftAlgo (draftId, STAGING)
BFF->>API: Execute Staging Algorithm
API->>Algo: resolve(SUBDIVISION).process(draftData, STAGING)
Algo->>DB: Read max portion from Cadastre (Erf 104 -> Max Portion = 3)
Algo-->>API: Return Provisional Portions 4, 5 and Remainder
API->>DB: Persist transient ReservationDraftOutcome (STAGED)
API-->>PLS: Staged Numbers Displayed for Review
%% 3. Lodgement & Workflow Trigger
PLS->>BFF: POST /api/reservation/saveDraftCheckout (Checklist & Documents)
BFF->>API: Process Checkout & Submission
API->>S3: Store Town Planning Consents & Sketches
API->>WF: Initiate Process (WF-RES-2026-901)
WF-->>API: Status = PENDING_EXAMINATION
API-->>PLS: Reservation Dossier Lodged
%% 4. Examiner Scrutiny & Approval
Note over WF,API: SG Cadastral Examiner Scrutinizes Boundary & Legal Compliance
WF->>API: Trigger Statutory Approval Callback
API->>Algo: resolve(SUBDIVISION).process(draftData, FINAL)
Algo->>DB: Lock Sequence Counter & Commit Portions 4, 5
API->>API: ReservationAcknowledgementLetterService.generatePdf()
API->>S3: Upload Barcode Acknowledgement Letter PDF
API->>Mail: Dispatch Acknowledgement Email with PDF Docket
API-->>PLS: Statutory Reservation Approved & Number Letter Issued
2.7 State Machine: Statutory Reservation Parcel Lifecycle¶
stateDiagram-v2
[*] --> DRAFT: Surveyor initiates reservation draft
DRAFT --> DRAFT: Add steps / configure algorithms
DRAFT --> STAGED_PREVIEW: Execute AlgoOutputType.STAGING
STAGED_PREVIEW --> DRAFT: Modify parcel parameters
STAGED_PREVIEW --> SUBMITTED: Surveyor lodges draft & completes checklist
SUBMITTED --> UNDER_EXAMINATION: Ingested into cis-workflow
UNDER_EXAMINATION --> QUERIED: Examiner requests clarification
QUERIED --> UNDER_EXAMINATION: Surveyor submits rectified dockets
UNDER_EXAMINATION --> REJECTED: Statutory non-compliance / overlap
UNDER_EXAMINATION --> APPROVED: Examiner endorses reservation
APPROVED --> ACTIVE: Final numbers committed & Barcode Letter issued
ACTIVE --> TRANSFERRED: Cession of reservation to alternate PLS
ACTIVE --> INCORPORATED: Physical survey lodged & registered in deeds
ACTIVE --> EXPIRED: SLA timer elapsed without survey lodgement
EXPIRED --> [*]
REJECTED --> [*]
INCORPORATED --> [*]
2.8 Reservation Engine REST API Reference Matrix¶
The table below catalogs the primary REST endpoints exposed by ReservationResource (com.dw.ngms.cis.web.rest.reservation.ReservationResource):
| HTTP Verb | Endpoint | Handler Method | Request Body / Parameters | Statutory Function / Description |
|---|---|---|---|---|
POST |
/api/reservation/draft |
createDraft |
ReservationDraftDto |
Initializes a new multi-step reservation application docket. |
GET |
/api/reservation/draft/{draftId} |
getDraft |
draftId |
Retrieves complete draft state including steps, requests, and outcomes. |
POST |
/api/reservation/draft/step |
addDraftStep |
ReservationDraftStepsDto |
Appends a sequential statutory step to an active reservation draft. |
POST |
/api/reservation/draft/step/byOutcomeIds |
addDraftStepByOutcomeIds |
StepOutcomeChainDto |
Chains outputs of previous step as inputs to a new statutory step. |
POST |
/api/reservation/processDraftAlgo |
processReservationDraftAlgo |
draftId, AlgoOutputType |
Executes algorithmic reservation in either STAGING or FINAL mode. |
POST |
/api/reservation/saveDraftCheckout |
saveDraftCheckout |
ReservationCheckoutVm |
Validates checklists, locks draft, and triggers cis-workflow lodgement. |
GET |
/api/reservation/pending |
getPendingReservations |
Pageable |
Queries pending reservation applications awaiting examiner scrutiny. |
POST |
/api/reservation/approve |
approveReservation |
ReservationApprovalVm |
SG Examiner endpoint: triggers FINAL number commit and barcode PDF. |
GET |
/api/reservation/downloadAckLetter/{id} |
downloadAckLetter |
reservationId |
Streams the certified PDF acknowledgement letter with QR/Barcodes. |
POST |
/api/reservation/transfer |
transferReservation |
ReservationTransferDto |
Executes surveyor-to-surveyor reservation cession and issues letter. |
POST |
/api/reservation/reDesignation |
reDesignateParcel |
ReDesignationRequestDto |
Executes parcel re-designation with historical audit linkage. |
GET |
/api/reservation/expiry/check |
checkExpiringReservations |
None | Triggered by scheduler: identifies reservations nearing statutory SLA lapse. |
Module 3: Lodgement Engine — Statutory Survey Intake & Docket Architecture¶
The Lodgement Engine governs the formal submission, parent property verification, sectional title scheme modeling, fee calculation, batch issuance, and document packaging of cadastral survey records prepared by Professional Land Surveyors (PLS).
It bridges the statutory gap between provisional parcel reservations (Module 2) and formal examination scrutiny (Module 4).
3.1 Complete End-to-End Lifecycle Vector Architecture¶
Below is the verified end-to-end 6-stage lifecycle architecture of the Lodgement Engine, detailing reservation inheritance, multi-category document intake, Sectional Title scheme ingestion, participation quota calculations, batch numbering, and proforma tax invoicing:
3.2 Chronological Stage-by-Stage Lifecycle Walkthrough¶
%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '14px', 'fontFamily': 'Roboto', 'lineColor': '#1e40af' }}}%%
flowchart LR
classDef stage fill:#EFF6FF,stroke:#1E40AF,stroke-width:2px,color:#1E3A8A;
classDef scheme fill:#EEF2FF,stroke:#4338CA,stroke-width:2px,color:#312E81;
classDef complete fill:#ECFDF5,stroke:#047857,stroke-width:2px,color:#064E3B;
S1["1. Draft & Reservation Link<br/>(Import Outcome Parcels)"]:::stage
S2["2. Survey Records Upload<br/>(Diagrams, Plans, S3)"]:::stage
S3["3. Sectional Title & PQ<br/>(Units, Floors & Quotas)"]:::scheme
S4["4. Fee Simulator & Proforma<br/>(Statutory Tariffs & PDF)"]:::stage
S5["5. Payment & QC Checklists<br/>(Settlement Scrutiny)"]:::stage
S6["6. Batch Issue & Handoff<br/>(Batch No & Level 1 Queue)"]:::complete
S1 --> S2 --> S3 --> S4 --> S5 --> S6
Stage 1: Lodgement Draft Initiation & Statutory Reservation Inheritance¶
- Objective: Establish an official lodgement docket and inherit pre-reserved parcel numbers and administrative records from Module 2.
- Core Capabilities (
LodgementDraftService,LodgementDraftStepsService):- Draft Docket Creation: Surveyors initiate a
LodgementDraftrecord linked to their authenticated professional user ID. - Statutory Linkage (
addStepsByReservationRef):- Ingests the Surveyor-General approved reservation reference (e.g.,
SG-RES-2026-00412). - Retrieves all underlying
ReservationOutcomerecords (reserved parcel numbers, LPI strings, parent designations). - Automatically populates sequential
LodgementDraftSteprecords withstepType = LODGEDand creates correspondingLodgementDraftRequestentities. - Validates that the reservation reference has not expired according to statutory SLA timers.
- Ingests the Surveyor-General approved reservation reference (e.g.,
- Draft Docket Creation: Surveyors initiate a
Stage 2: Multi-Category Survey Records & Spatial Data Ingestion¶
- Objective: Ingest the complete physical and digital dossier required by the Land Survey Act into high-performance object storage.
- Document Ingestion Mechanics (
LodgementResource.uploadReservationRequestDoc,LodgementDraftAnnexure):- Streams files directly into RustFS S3 (
Port 9000) without local disk persistence leaks. - Supports statutory document categories:
- Survey Diagrams (SG Dsg): Single or multi-page surveyor diagram PDFs detailing boundary beacons and line tables.
- General Plans (GP): Multi-sheet layout plans for extensive township establishments and large agricultural subdivisions.
- Working Plans & Field Books: Raw observational field notes, total station observation logs, and traverse closure sheets.
- Beacon Coordinate CSVs / ASCII Data: Machine-readable coordinate tables for automated mathematical scrutiny.
- Planning Consents (Annexures): Municipal SPLUMA authorizations, Environmental Impact Assessment (EIA) records, and consent affidavits.
- Streams files directly into RustFS S3 (
Stage 3: Sectional Title (ST) Scheme Modeling & Participation Quota (PQ) Calculation¶
- Objective: Model complex multi-tier architectural schemes and compute legally binding Participation Quotas.
- Sectional Scheme Architecture (
LodgementSchemeService,PqCalculatorService):- If the survey represents a Sectional Title development under the Sectional Titles Act, the surveyor models:
StScheme: Master scheme metadata, local authority jurisdiction, and registered name.SchemeBuilding: Physical building structures, blocks, and architectural elevations.SchemeSection: Individual residential apartments, commercial offices, or industrial units with defined floor areas (\(m^2\)).SchemeEUA: Exclusive Use Areas (garages, private gardens, parking bays) and associated legend designations.SectionalTitleCrossSection: Height profiles, cross-sections, and common property boundaries.
- Automated PQ Apportionment: Invokes
PqCalculatorService.calculate(schemeId)to compute mathematical quotas to 4 decimal places, enforcing \(\sum PQ = 100.0000\%\).
- If the survey represents a Sectional Title development under the Sectional Titles Act, the surveyor models:
Stage 4: Fee Simulation & Proforma Tax Invoicing¶
- Objective: Dynamically determine statutory examination tariffs and generate official proforma invoice documentation.
- Tariff Mechanics (
LodgementFeeSimulatorService,LodgementPerformaInvoiceGenerationService):- Computes examination fees based on the number of newly created parcels, portions, sectional title sections, and document page counts.
- Compiles a formal tax proforma invoice PDF via Flying Saucer containing the Department of Agriculture, Land Reform and Rural Development (DALRRD) tax headers, statutory banking details, and EFT reference codes.
- Triggers
cis-emailerto dispatch the proforma invoice PDF directly to the surveyor.
Stage 5: Payment Settlement Scrutiny & Mandatory Quality Checklists¶
- Objective: Validate financial settlement (or statutory fee exemption) and enforce surveyor compliance affidavits.
- Settlement & Scrutiny Mechanics (
LodgementDraftPayment,QcChecklistService):- Surveyors record payment details via
POST /lodgement/addPayment, uploading EFT receipts or official government fee waiver certificates. - Evaluates statutory quality control responses (
QcChecklistResponse), requiring the surveyor to attest that beacons have been physically placed and mathematical closures conform to statutory standards.
- Surveyors record payment details via
Stage 6: Statutory Batch Issuance, SG Document Number Allocation & Examination Handoff¶
- Objective: Commit the lodgement submission into an official provincial examination batch and allocate statutory document identifiers.
- Batch Promotion Mechanics (
LodgementDraftService.issueBatch):- Provincial Batch Numbering:
- Invokes
allocateNextBatchNumber(provinceId). - Generates the official batch reference text:
<batchNo>/<year>(e.g.,412/2026). - Persists record to
LodgementBatchwithisExamined = 0.
- Invokes
- SG Document Numbering:
- Iterates through all lodged documents and allocates sequential document numbers via
getMaxDocumentNumber(provinceId, docType). - Generates official statutory document text:
<prefix><docNo>/<year>(e.g.,Dsg 89/2026). - Emits records into
LodgementBatchSgDocument.
- Iterates through all lodged documents and allocates sequential document numbers via
- Acknowledgement Letter & Workflow Handoff:
- Generates an official Barcode Acknowledgement Letter PDF (
LodgementAcknowledgementLetterService). - Dispatches a process event to
cis-workflow(Port 8090), handing the batch over to the Examination Engine (Module 4).
- Generates an official Barcode Acknowledgement Letter PDF (
- Provincial Batch Numbering:
3.3 Deep Dive: Sectional Title (ST) Schemes & Participation Quota (PQ) Engine¶
The Sectional Title submodule in cis-api (com.dw.ngms.cis.service.lodgment.scheme.* and PqCalculatorService) models multi-story sectional properties and enforces strict statutory Participation Quota mathematics:
%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '13px', 'fontFamily': 'Roboto' }}}%%
flowchart TD
classDef scheme fill:#EEF2FF,stroke:#4338CA,stroke-width:2px,color:#312E81;
classDef comp fill:#EFF6FF,stroke:#2563EB,stroke-width:1.5px,color:#1E40AF;
classDef calc fill:#FEF3C7,stroke:#D97706,stroke-width:2px,color:#78350F;
SCHEME["StScheme<br/>(Scheme Name, Filing Year, Mother Erf)"]:::scheme
subgraph ARCHITECTURE["Architectural Hierarchy"]
BLDG["SchemeBuilding<br/>(Block Plans & Floors)"]:::comp
SEC["SchemeSection<br/>(Unit 1..N, Floor Areas m²)"]:::comp
EUA["SchemeEUA<br/>(Exclusive Use Areas: Garages, Yards)"]:::comp
CROSS["CrossSectionDetails<br/>(Structural Elevations)"]:::comp
end
subgraph PQ_ENGINE["Participation Quota (PQ) Engine (PqCalculatorService)"]
CLASS["Classify Section Types<br/>(Residential vs Non-Residential vs Mixed)"]:::calc
FORMULA["Apply Statutory Quota Formula:<br/>PQ % = (Section Area / Total Area) * 100"]:::calc
ROUND["Enforce 4 Decimal Precision<br/>(RoundingMode.HALF_UP)"]:::calc
BALANCE["Invariant Check:<br/>Sum of all PQ = 100.0000%"]:::calc
end
SCHEME --> ARCHITECTURE
BLDG --> SEC
BLDG --> EUA
BLDG --> CROSS
SEC --> PQ_ENGINE
CLASS --> FORMULA --> ROUND --> BALANCE
Participation Quota Mathematical Formulation¶
Under the Sectional Titles Act, the participation quota determines each unit owner's share in the common property, voting rights in the body corporate, and municipal rates apportionment:
| Variable / Parameter | Mathematical Definition | Statutory Cadastral Significance |
|---|---|---|
| \(\text{PQ}_i\) | Participation Quota for section \(i\) | Recorded to 4 decimal places (RoundingMode.HALF_UP). |
| \(\text{Floor Area}_i\) | Floor area of section \(i\) (\(m^2\)) | Extracted directly from SchemeSection.getFloorArea(). |
| \(\sum_{k=1}^N \text{Floor Area}_k\) | Aggregate floor area (\(m^2\)) | Sum of all registered sections within the scheme. |
| Invariant Check | \(\sum_{i=1}^N \text{PQ}_i = 100.0000\%\) | Strict validation: if aggregate sum \(\ne 100.0000\%\), lodgement is blocked. |
- Residential Developments: The formula is evaluated strictly on relative floor area.
- Mixed-Use Developments: The scheme defines a
nonResidentialPercentage(e.g., 30% Commercial retail, 70% Residential apartments).PqCalculatorServiceapportionates the sub-quotas across residential and commercial sections independently so that the aggregate total strictly equals \(100.0000\%\).
3.4 Statutory Batch Issuance & SG Document Allocation Mechanics¶
When LodgementResource.issueBatch is executed, cis-api transitions transient draft structures into irrevocable statutory examination records:
sequenceDiagram
autonumber
actor PLS as Land Surveyor
participant API as cis-api (:8089)
participant Repo as LodgementBatchRepository
participant DocRepo as LodgementBatchSgDocumentRepository
participant DB as Oracle Database 23 (:1521)
PLS->>API: POST /lodgement/issueBatch (draftId)
API->>Repo: allocateNextBatchNumber(provinceId)
Repo->>DB: Sequence Nextval for Province Batch Counter
Repo-->>API: batchNo = 412
API->>DB: INSERT INTO LodgementBatch (batchNumberText = '412/2026', isExamined = 0)
loop For Each Lodged Document (Dsg, GP, Working Plan)
API->>DocRepo: getMaxDocumentNumber(provinceId, docTypeItemId)
DocRepo-->>API: maxDocNumber = 88
API->>DB: INSERT INTO LodgementBatchSgDocument (docNumberText = 'Dsg 89/2026')
API->>DB: UPDATE LodgementDraftDocument SET sgDocumentId = 89
end
API-->>PLS: Batch Issued (412/2026) & SG Document Numbers Assigned
3.5 Detailed Sequence Interaction Diagram¶
The sequence diagram below details the complete request-reply flow across all architectural tiers during survey lodgement:
sequenceDiagram
autonumber
actor PLS as Land Surveyor (PLS)
participant BFF as cis-bff (:8080)
participant API as cis-api (:8089)
participant S3 as RustFS S3 (:9000)
participant WF as cis-workflow (:8090)
participant DB as Oracle Database 23 (:1521)
participant Mail as Mailpit / SMTP (:1025)
%% 1. Initiation
PLS->>BFF: POST /api/lodgement/saveDraft
BFF->>API: Forward with Bearer JWT
API->>DB: Persist LodgementDraft
API->>API: addStepsByReservationRef(refNo)
API->>DB: Import ReservationOutcomes into LodgementDraftSteps
API-->>PLS: Draft Initialized & Reserved Steps Linked
%% 2. File Upload
PLS->>BFF: POST /api/lodgement/uploadReservationRequestDoc (Multipart)
BFF->>API: Stream Survey Plans & Shapefiles
API->>S3: PutObject (RustFS S3 :9000)
S3-->>API: Blob URI & Checksum
API->>DB: Persist LodgementDraftDocument
API-->>PLS: Document Upload Verified
%% 3. Invoicing
PLS->>BFF: POST /api/lodgement/processInvoice (draftId)
BFF->>API: Fee Simulation Request
API->>API: LodgementFeeSimulatorService.calculate()
API->>DB: Persist InvoicePerforma
API->>Mail: Dispatch Proforma Tax Invoice PDF
API-->>PLS: Invoice Issued (INV-2026-0412)
%% 4. Issue Batch
PLS->>BFF: POST /api/lodgement/issueBatch (draftId)
BFF->>API: Final Batch Promotion
API->>DB: Commit LodgementBatch (412/2026) & SG Document Numbers
API->>API: LodgementAcknowledgementLetterService.generatePdf()
API->>S3: Upload Barcode Ack Letter PDF
API->>WF: Initiate Examination Workflow Process
WF-->>API: Workflow State = PENDING_LEVEL_1_EXAMINATION
API-->>PLS: Lodgement Complete (Ack Letter Ready)
3.6 State Machine: Lodgement Batch & Document Progression¶
stateDiagram-v2
[*] --> DRAFT_INTAKE: Surveyor creates lodgement draft
DRAFT_INTAKE --> RESERVATION_LINKED: addStepsByReservationRef()
RESERVATION_LINKED --> DOCUMENTS_STAGED: Upload diagrams, plans & shapefiles
DOCUMENTS_STAGED --> SCHEME_MODELING: Sectional Title units & PQ calculated
SCHEME_MODELING --> PROFORMA_ISSUED: Tariff computed & invoice dispatched
PROFORMA_ISSUED --> SETTLED: Proof of payment / exemption uploaded
SETTLED --> BATCH_ISSUED: issueBatch() assigns Batch No & SG Doc IDs
BATCH_ISSUED --> PENDING_EXAMINATION: Ingested into cis-workflow queue
PENDING_EXAMINATION --> [*]
3.7 Lodgement Engine REST API Reference Matrix¶
The table below catalogs primary REST endpoints exposed by LodgementResource and LodgementSchemeResource:
| HTTP Verb | Endpoint | Handler Method | Request Body / Parameters | Statutory Function / Description |
|---|---|---|---|---|
POST |
/api/lodgement/saveDraft |
saveLodgementDraft |
LodgementDraftDto |
Initializes or updates a survey lodgement application draft. |
GET |
/api/lodgement/draft/{draftId} |
getLodgementDraft |
draftId |
Retrieves complete draft state, steps, and document summaries. |
POST |
/api/lodgement/addStepsByResRef |
addStepsByReservationRef |
referenceNo, draftId |
Inherits pre-reserved outcomes from Module 2 into lodgement steps. |
POST |
/api/lodgement/uploadReservationRequestDoc |
uploadReservationRequestDoc |
Multipart LodgementDraftDocumentDto |
Ingests survey diagrams, general plans, and coordinate tables to S3. |
POST |
/api/lodgement/addAnnexure |
saveLodgementDocument |
Multipart LodgementDraftAnnexureDto |
Attaches town planning SPLUMA consents and legal affidavits. |
POST |
/api/lodgement/scheme/saveScheme |
saveScheme |
SchemeSchemeDto |
Models Sectional Title master scheme, mother erf, and local authority. |
POST |
/api/lodgement/scheme/saveBuilding |
saveSchemeBuilding |
SchemeBuildingDto |
Records architectural buildings, floor plans, and cross-sections. |
POST |
/api/lodgement/scheme/saveSection |
saveSchemeSection |
SchemeSectionDto |
Ingests individual sectional units, floor areas (\(m^2\)), and unit types. |
POST |
/api/lodgement/scheme/calculatePQ |
calculatePQ |
schemeId |
Invokes PqCalculatorService to apportion statutory participation quotas. |
POST |
/api/lodgement/processInvoice |
processInvoice |
draftId |
Computes dynamic statutory examination tariffs. |
GET |
/api/lodgement/generatePerformaInvoice |
generatePdf |
draftId |
Compiles official DALRRD Flying Saucer tax proforma invoice PDF. |
POST |
/api/lodgement/addPayment |
addPayment |
LodgementDraftPaymentDto |
Records EFT settlement receipt or statutory exemption certificate. |
POST |
/api/lodgement/issueBatch |
issueBatch |
LodgementBatchDto |
Assigns provincial batch number (batchNo/year), SG doc numbers, and triggers workflow. |
GET |
/api/lodgement/getLdgDraftAcknowledement |
getLodgementDraftAcknowledgementLetter |
draftId |
Streams certified PDF acknowledgement letter with barcodes. |
Module 4: Examination Engine — Technical Cadastral Scrutiny & Statutory Stamping¶
The Examination Engine is the core statutory quality assurance and legal verification bastion of the Cadastral Information System (CIS). Mandated by the Land Survey Act, no land parcel, sectional title scheme, or general plan can be registered in the Deeds Office without formal technical examination, coordinate verification, caveat clearance, and official digital stamping by the Surveyor-General (SG).
The engine operates a distributed two-tier examination workflow coordinated via ShedLock schedulers, executes automated mathematical coordinate consistency algorithms, checks legal caveats, and applies cryptographically verifiable digital approval seals.
4.1 Complete End-to-End Lifecycle Vector Architecture¶
Below is the verified end-to-end 6-stage lifecycle architecture of the Examination Engine, illustrating automated ShedLock queue allocation, Phase 1 mathematical coordinate scrutiny, Phase 2 senior quality review, caveat clearance, and digital stamping:
4.2 Chronological Stage-by-Stage Lifecycle Walkthrough¶
%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '14px', 'fontFamily': 'Roboto', 'lineColor': '#7e22ce' }}}%%
flowchart LR
classDef stage fill:#FAF5FF,stroke:#7E22CE,stroke-width:2px,color:#581C87;
classDef math fill:#FEF3C7,stroke:#D97706,stroke-width:2px,color:#78350F;
classDef query fill:#FFF7ED,stroke:#EA580C,stroke-width:2px,color:#9A3412;
classDef complete fill:#ECFDF5,stroke:#047857,stroke-width:2px,color:#064E3B;
S1["1. Automated Intake<br/>(ShedLock Scheduler)"]:::stage
S2["2. Math Consistency<br/>(ΔY, ΔX & Gauss Area)"]:::math
S3["3. Phase 1 Checklists<br/>(Docket Tree & QC)"]:::stage
S4["4. Scrutiny Verdict<br/>(Query vs Phase 2)"]:::query
S5["5. Phase 2 Senior Audit<br/>(Caveat & Legal Review)"]:::stage
S6["6. SG Digital Stamping<br/>(Seal, Signature & S3)"]:::complete
S1 --> S2 --> S3 --> S4 --> S5 --> S6
Stage 1: Automated Batch Intake & Distributed ShedLock Task Allocation¶
- Objective: Automatically ingest pending survey batches emitted by Module 3 and allocate them across examination officers without race conditions.
- Scheduling Mechanics (
ExaminationFirstLavelScheduler,LodgementBatchRecordsHandler):- Utilizes distributed ShedLock locking (
@SchedulerLock(name = "examination_first_label_scheduler")) across cluster nodes. - Scans
LodgementBatchfor records withisExamined = 0. - Allocates dossiers to first-level cadastral examiners based on provincial jurisdiction, workload balance, and survey complexity.
- Marks batch records as under scrutiny and populates the Level 1 Examiner work queue (
/examination/firstLevelListing).
- Utilizes distributed ShedLock locking (
Stage 2: Mathematical Coordinate Consistency Algorithm Scrutiny¶
- Objective: Automate the mathematical verification of survey beacons, boundary lines, coordinate differences, polygon misclosures, and area tolerances.
- Algorithm Mechanics (
ConsistencyCheckAlgorithm):- Ingests beacon coordinates and line tables (
SgdataParcelLineGranular) uploaded by the surveyor. - Evaluates coordinate deltas (\(\Delta Y, \Delta X\)), line lengths, and bearings against national coordinate reference systems (Lo meridians / WGS84).
- Calculates Gauss polygon trapezoidal assessed area and verifies that the difference between surveyor-declared area and assessed area falls within Land Survey Act statutory limits.
- Computes total perimeter and linear misclosure \(\sqrt{(\sum \Delta Y)^2 + (\sum \Delta X)^2}\). If misclosure exceeds Class A (Urban) or Class B (Rural) thresholds, emits
ConsistencyCheckException.
- Ingests beacon coordinates and line tables (
Stage 3: Phase 1 Quality Control Checklists & Hierarchical Docket Scrutiny¶
- Objective: Perform comprehensive technical scrutiny covering statutory boundary rules, beacon descriptions, and planning consents.
- Scrutiny Capabilities (
DocketTreeBuilderService,QcChecklistService):- Docket Tree Builder: Structures the multi-page submission into an interactive hierarchy (
DocketTree\(\rightarrow\)DocketGroupNode\(\rightarrow\)DocketGroupRoleNode\(\rightarrow\)DocketAttributeNode). - Statutory Checklists: Examiners execute 40+ mandatory compliance checks covering beacon witness marks, road reserve alignments, servitude widths, and boundary continuity.
- Docket Tree Builder: Structures the multi-page submission into an interactive hierarchy (
Stage 4: Phase 1 Examination Verdict — Formal Query vs Phase 2 Promotion¶
- Objective: Issue statutory query notes to the land surveyor or promote technically sound batches to senior review.
- Workflow Branching:
- If Defects or Inconsistencies Detected:
- Examiner issues formal Query Notes detailing mathematical or boundary discrepancies.
- Compiles a Query Notice PDF via
RelodgementLetterGenerationService. - Transitions batch state to
QUERIEDand routes into Module 5 (Relodgement Engine).
- If Technical Scrutiny Passes:
- Examiner endorses Phase 1 compliance.
- Batch transitions to
PHASE_1_APPROVEDand is automatically promoted to the Senior Examiner Queue.
- If Defects or Inconsistencies Detected:
Stage 5: Phase 2 Senior Examiner Quality Assurance & Cadastral Caveats Scrutiny¶
- Objective: Senior cadastral officer audit, legal conflict detection, and caveat clearance.
- Senior Review Pipeline (
ExaminationSecondLabelScheduler,SgCaveats):- Coordinated by distributed scheduler
examination_second_label_scheduler. - Cadastral Caveat Verification: Queries
SgCaveatsto ensure that no pending land expropriations, court interdicts, boundary disputes, or restitution claims exist on the subject land. - Cross-Boundary Conflict Scans: Performs spatial collision scans against contiguous approved parcels in
cis-search. - Senior examiner signs off on the quality review dossier.
- Coordinated by distributed scheduler
Stage 6: Surveyor-General Digital Stamping, Statutory Sign-off & Cadastre Promotion¶
- Objective: Apply official Surveyor-General approval seals, certify legal diagrams, and promote parcels to the master land registry.
- Stamping & Master Promotion Mechanics (
StampingService,ExaminationStamping):- Digital Stamping Microservice:
- Calls the digital stamping service (
Port 8000). - Embeds the official SG coat of arms seal, statutory approval text, approval date, and SG digital signature directly onto the approved diagram PDF.
- Calls the digital stamping service (
- Master Record Promotion:
- Archives the digitally stamped PDF in RustFS S3 (
Port 9000). - Promotes provisional parcel records in
SgdataParcelsfrom provisional toAPPROVED/ACTIVE. - Updates parent property remainder balances in
SgdataParentChild. - Dispatches completion notifications and certified docket download links to the surveyor via
cis-emailer.
- Archives the digitally stamped PDF in RustFS S3 (
- Digital Stamping Microservice:
4.3 Deep Dive: Mathematical Consistency Algorithm (ConsistencyCheckAlgorithm)¶
ConsistencyCheckAlgorithm (com.dw.ngms.cis.service.examination.consistency.ConsistencyCheckAlgorithm) automates the statutory mathematical verification of cadastral boundary coordinates:
%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '13px', 'fontFamily': 'Roboto' }}}%%
flowchart TD
classDef input fill:#EFF6FF,stroke:#2563EB,stroke-width:1.5px,color:#1E40AF;
classDef calc fill:#FEF3C7,stroke:#D97706,stroke-width:2px,color:#78350F;
classDef test fill:#F3E8FF,stroke:#7E22CE,stroke-width:2px,color:#581C87;
classDef pass fill:#ECFDF5,stroke:#059669,stroke-width:2px,color:#065F46;
classDef fail fill:#FEF2F2,stroke:#DC2626,stroke-width:2px,color:#991B1B;
IN["Input: SgdataParcelLineGranular<br/>(Beacon Coordinates Y, X)"]:::input
subgraph STEP1["1. Coordinate Difference & Bearing Calculus"]
DYDX["calculateDyDx():<br/>ΔY = Y(to) - Y(from)<br/>ΔX = X(to) - X(from)"]:::calc
DIST["Distance = √(ΔY² + ΔX²)<br/>Bearing = atan2(ΔY, ΔX)"]:::calc
PERIM["calculatePerimeter():<br/>Perimeter = ∑ Distance"]:::calc
DYDX --> DIST --> PERIM
end
subgraph STEP2["2. Assessed Area Calculus"]
GAUSS["calculateAssessedArea():<br/>Area = 0.5 * |∑ (Yi + Yi+1) * (Xi+1 - Xi)|"]:::calc
AREATOL["calculateAreaTolerance():<br/>Statutory tolerance based on parcel class"]:::calc
GAUSS --> AREATOL
end
subgraph STEP3["3. Misclosure Calculus"]
MISC["calculateClosureTolerance():<br/>Misclosure = √((∑ΔY)² + (∑ΔX)²)<br/>Allowable = K * √(Perimeter)"]:::calc
end
IN --> STEP1
STEP1 --> STEP2
STEP2 --> STEP3
subgraph VERDICT["4. Statutory Verdict Determination"]
CHECK{"Misclosure ≤ Tolerance<br/>AND<br/>|Declared - Assessed| ≤ AreaTol?"}:::test
PASS["ConsistencyCheckStatus.SUCCESS<br/>(Coordinates Statutorily Valid)"]:::pass
FAIL["ConsistencyCheckStatus.FAILED<br/>(Emits ConsistencyCheckException)"]:::fail
end
STEP3 --> CHECK
CHECK -->|Yes| PASS
CHECK -->|No| FAIL
Mathematical Formulation & Algorithmic Verification¶
ConsistencyCheckAlgorithm executes three sequential mathematical operations on surveyor-submitted beacon coordinates (SgdataParcelLineGranular):
1. Coordinate Differences, Line Distances & Bearings¶
| Metric | Programmatic Method | Formula / Implementation | Statutory Role |
|---|---|---|---|
| Coordinate Delta (\(\Delta Y, \Delta X\)) | calculateDyDx() |
\(Y_{\text{to}} - Y_{\text{from}}\), \(X_{\text{to}} - X_{\text{from}}\) | Evaluates easting/northing displacement per boundary segment. |
| Segment Length | calculatePerimeter() |
\(\sqrt{\Delta Y^2 + \Delta X^2}\) | Verifies physical boundary distance between consecutive beacons. |
| Line Bearing | calculateAngle() |
\(\operatorname{atan2}(\Delta Y, \Delta X)\) | Verifies statutory angular direction from true south. |
| Total Perimeter | calculatePerimeter() |
\(\sum \text{Distance}\) | Sum of all perimeter boundary segments for tolerance scaling. |
2. Gauss Trapezoidal Polygon Area Formulation¶
| Variable / Function | Definition | Calculation Logic |
|---|---|---|
calculateAssessedArea() |
Gauss coordinate polygon area (\(m^2\)) | Computed mathematically from ordered \((Y, X)\) beacon coordinates. |
inputArea |
Surveyor-declared diagram area | Declared area extracted from uploaded survey diagram docket. |
calculateAreaTolerance() |
Maximum permissible area error | Land Survey Act statutory limit based on parcel size and class. |
| Area Verification Rule | \|inputArea - assessedArea\| <= areaToleranceLimit |
If area discrepancy exceeds tolerance, ConsistencyOutcome fails. |
3. Linear Coordinate Misclosure & Closure Tolerance¶
| Cadastral Survey Class | Tolerance Constant (\(C\)) | Maximum Permissible Linear Misclosure | Applicable Land Category |
|---|---|---|---|
| Class A (Urban Cadastre) | \(C = 0.015\) | \(0.015 \times \sqrt{\text{Perimeter}}\) meters | Urban erven, township stands, commercial parcels. |
| Class B (Rural Cadastre) | \(C = 0.030\) | \(0.030 \times \sqrt{\text{Perimeter}}\) meters | Agricultural holdings, rural farm portions, state land. |
| Verification Rule | \(\text{Misclosure} \le \text{Closure Tolerance}\) | Emits ConsistencyCheckStatus.SUCCESS if within limit, else FAILED. |
4.4 Two-Tier Examination Workflows & ShedLock Schedulers¶
CIS enforces strict segregation of duties between initial technical examination and senior administrative quality approval:
| Feature / Responsibility | Phase 1: Technical Scrutiny | Phase 2: Senior Quality Review |
|---|---|---|
| Scheduler Class | ExaminationFirstLavelScheduler |
ExaminationSecondLabelScheduler |
| Distributed ShedLock Key | examination_first_label_scheduler |
examination_second_label_scheduler |
| Queue Filter Criteria | isExamined = 0 (Unexamined batches) |
isExamined = 1 AND isSecondLevel = 0 |
| Target Role / Actor | Cadastral Examination Officer | Senior Examiner / Deputy Surveyor-General |
| Primary Scrutiny Focus | Mathematical consistency, coordinate closure, beacon accuracy, docket completeness. | Boundary disputes, caveat clearances, legal consistency, town planning authorizations. |
| Permitted Outcomes | Technical Approval (promote to Phase 2) OR Query Notice (reject to PLS). | Final Statutory SG Approval OR Query Escalation. |
4.5 Digital Stamping Microservice & Statutory Seal Pipeline¶
Upon final Surveyor-General approval, cis-api invokes StampingService to transform the uncertified diagram PDF into a legally registered, sealed cadastral document:
sequenceDiagram
autonumber
actor SG as Surveyor-General Officer
participant API as cis-api (:8089)
participant StampSvc as Stamping Service (:8000)
participant S3 as RustFS S3 (:9000)
participant DB as Oracle Database 23 (:1521)
participant Mail as Mailpit (:1025)
SG->>API: POST /examination/docs/signed (batchId, workflowId)
API->>DB: Query Approved LodgementBatchSgDocuments
loop For Each Diagram PDF
API->>S3: Retrieve Raw Diagram PDF
S3-->>API: Raw PDF Binary Stream
API->>StampSvc: POST /api/stamp (PDF + Stamp Metadata)
Note over StampSvc: Embeds Official SG Coat of Arms Seal,<br/>Approval Date, SG Name & Digital Signature
StampSvc-->>API: Digitally Stamped Diagram PDF
API->>S3: PutObject (Overwrites with Stamped Diagram)
API->>DB: Record ExaminationStamping Audit Log
end
API->>DB: Update SgdataParcels (Status = APPROVED)
API->>Mail: Dispatch Approval Notice with Stamped Docket to PLS
API-->>SG: Statutory Examination Complete & Parcels Registered
4.6 State Machine: Cadastral Examination Docket State Transitions¶
stateDiagram-v2
[*] --> PENDING_ALLOCATION: Lodgement Batch Issued (isExamined = 0)
PENDING_ALLOCATION --> LEVEL_1_ASSIGNED: ExaminationFirstLavelScheduler assigns examiner
LEVEL_1_ASSIGNED --> MATH_CONSISTENCY_CHECK: ConsistencyCheckAlgorithm executed
MATH_CONSISTENCY_CHECK --> LEVEL_1_SCRUTINY: Mathematical closures pass
MATH_CONSISTENCY_CHECK --> QUERIED: Misclosure exceeds tolerance
LEVEL_1_SCRUTINY --> LEVEL_1_APPROVED: Examiner verifies checklists & docket tree
LEVEL_1_SCRUTINY --> QUERIED: Boundary or documentation defects detected
QUERIED --> RELODGEMENT_QUEUE: Routed to Module 5 (Relodge)
LEVEL_1_APPROVED --> LEVEL_2_ASSIGNED: ExaminationSecondLabelScheduler assigns Senior Officer
LEVEL_2_ASSIGNED --> CAVEAT_SCRUTINY: SgCaveats & interdicts checked
CAVEAT_SCRUTINY --> FINAL_APPROVED: Senior Officer endorses batch
CAVEAT_SCRUTINY --> QUERIED: Legal conflict detected
FINAL_APPROVED --> DIGITALLY_STAMPED: StampingService embeds SG seals & signs PDF
DIGITALLY_STAMPED --> MASTER_CADASTRE_ACTIVE: SgdataParcels promoted to live registry
MASTER_CADASTRE_ACTIVE --> [*]
4.7 Examination Engine REST API Reference Matrix¶
The table below catalogs primary REST endpoints exposed by ExaminationResource:
| HTTP Verb | Endpoint | Handler Method | Request Body / Parameters | Statutory Function / Description |
|---|---|---|---|---|
POST |
/api/examination/firstLevelListing |
getFirstLabelListing |
ExaminationListingVm |
Retrieves worklist queue for Phase 1 Technical Examiners. |
POST |
/api/examination/triggerFirstLevel |
triggerManually |
ExaminationFirstLavelTriggerTaskVm |
Manually triggers Level 1 examiner task assignment. |
POST |
/api/examination/secondLevelListing |
getSecondLabelListing |
ExaminationListingVm |
Retrieves worklist queue for Phase 2 Senior Examiners. |
POST |
/api/examination/triggerSecondLevel |
triggerSecondLabel |
ExaminationSecondLavelTriggerTaskVm |
Manually triggers Level 2 senior examiner task assignment. |
GET |
/api/examination/doc/consistencySummary |
consistencySummary |
sgDocumentId |
Executes ConsistencyCheckAlgorithm and returns \(\Delta Y, \Delta X\), closure and area analysis. |
GET |
/api/examination/doc/areaDetails |
getAreaCalculatedDetails |
sgDocumentId |
Returns Gauss assessed area vs surveyor-declared diagram area. |
POST |
/api/examination/doc/data/upload |
uploadCsvData |
Multipart CSV / ASCII | Ingests raw coordinate beacon and parcel boundary line tables. |
GET |
/api/examination/docket/getTreeConfig |
getConfiguration |
docketId |
Builds and returns interactive hierarchical DocketTree. |
POST |
/api/examination/doc/stamp |
addStamp |
ExaminationStampingDto |
Applies digital SG approval seal and signature stamp to diagram PDF. |
POST |
/api/examination/doc/outcome |
addExamOutcome |
ExaminationOutcomeDto |
Records Phase 1 or Phase 2 examiner verdict (Approve, Query, Reject). |
GET |
/api/examination/docs/signed |
signedDocuments |
batchId, workflowId |
Promotes examined batch to master registry and finalizes SG sign-off. |
Module 5: Relodgement Engine — Examiner Query Resolution & Differential Scrutiny¶
The Relodgement Engine governs the formal statutory defect resolution and resubmission workflow when a cadastral survey submission is queried or returned by a Surveyor-General examiner in Module 4.
Rather than forcing the surveyor to recreate a survey dossier from scratch, the engine establishes an immutable parent-child draft lineage (parentDraftId, firstParentDraftId), generates differential comparison trees (LodgementTree), executes targeted differential boundary coordinate re-scrutiny, and fast-tracks the amended batch directly back to the original assigned examiner in cis-workflow.
5.1 Complete End-to-End Lifecycle Vector Architecture¶
Below is the verified end-to-end 6-stage lifecycle architecture of the Relodgement Engine, detailing defect intake, parent-child draft lineage, differential tree modeling, fee adjustments, and fast-track examiner re-routing:
5.2 Chronological Stage-by-Stage Lifecycle Walkthrough¶
%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '14px', 'fontFamily': 'Roboto', 'lineColor': '#d97706' }}}%%
flowchart LR
classDef stage fill:#FEFCE8,stroke:#D97706,stroke-width:2px,color:#78350F;
classDef action fill:#EFF6FF,stroke:#2563EB,stroke-width:2px,color:#1E40AF;
classDef complete fill:#ECFDF5,stroke:#047857,stroke-width:2px,color:#064E3B;
S1["1. Query Receipt & Notice<br/>(Examiner Query Notes PDF)"]:::stage
S2["2. Relodge Docket Init<br/>(Child Draft & Lineage)"]:::action
S3["3. Tree Diff & Rectification<br/>(LodgementTree & S3 Upload)"]:::stage
S4["4. Differential Scrutiny<br/>(Math & Tariff Delta)"]:::stage
S5["5. Relodge Batch Commit<br/>(Operations.RELODGE)"]:::complete
S6["6. Fast-Track Examiner Sign<br/>(Original Examiner Worklist)"]:::complete
S1 --> S2 --> S3 --> S4 --> S5 --> S6
Stage 1: Examiner Query Notice & Defect Citations Receipt¶
- Objective: Ingest specific technical, mathematical, or procedural defects identified during Module 4 examination and place the survey batch in a legally governed query state.
- Query Notice Pipeline (
RelodgementLetterGenerationService,getRelodgementLetter):- When a Level 1 or Level 2 examiner rejects a batch,
cis-workflowsets batch status toQUERIED(StatusItemId = 1528L). - Compiles an official Query Notes PDF containing itemized examiner comments (e.g., coordinate misclosure exceeding Class A limits, unclosed parcel lines, missing municipal consent endorsements).
- Dispatches the query notice to the surveyor via
cis-emailerand starts the statutory response SLA timer (e.g., 60 statutory days to rectify).
- When a Level 1 or Level 2 examiner rejects a batch,
Stage 2: Child Relodgement Draft Docket Creation & Lineage Preservation¶
- Objective: Initialize a child relodgement draft that inherits all approved historical context while preserving an unalterable audit trail.
- Lineage Mechanics (
RelodgementService.addRelodge):- Surveyor triggers
POST /api/relodgement/addRelodge. - Creates a new
LodgementDraftrecord withisActive = 1. - Links
parentDraftIdto the immediate queried submission andfirstParentDraftIdto the root lodgement, preserving complete submission genealogy across multiple query iterations. - Automatically copies applicant metadata, professional surveyor council numbers, delivery methods, and statutory file references.
- Surveyor triggers
Stage 3: Hierarchical LodgementTree Comparison & Rectification¶
- Objective: Present the surveyor with an interactive differential tree comparing original documents against queried items, allowing targeted uploads of rectified files.
- Tree Comparison Engine (
RelodgementService.getLodgementTree):- Builds a hierarchical
LodgementTreestructured as:Root\(\rightarrow\)LodgementDraftStep\(\rightarrow\)LodgementSgNo\(\rightarrow\)Document. - Differentiates items by granular status:
- Status 1528 (
QUERIED): Original document flagged with examiner defects. - Status 1928 (
LODGED): Newly uploaded replacement diagram, corrected coordinate table, or supplementary consent affidavit.
- Status 1528 (
- Streams rectified replacement files into RustFS S3 (
Port 9000) and associates them withsgDocumentId.
- Builds a hierarchical
Stage 4: Differential Boundary Validation & Tariff Re-Calculation¶
- Objective: Validate only the modified boundary vectors without forcing re-examination of unchanged parcels, and compute fee deltas.
- Differential Validation Mechanics:
- Re-runs
ConsistencyCheckAlgorithmspecifically on amended polygon lines (SgdataParcelLineGranular). - Evaluates whether revised beacon coordinates resolve the original linear misclosure and polygon area discrepancies.
- Fee Adjustments (
LodgementFeeSimulatorService):- If the rectified plan alters parcel counts or portion boundaries, dynamically recalculates examination tariffs and issues a supplementary proforma invoice. Minor technical corrections incur no additional statutory fees.
- Re-runs
Stage 5: Relodgement Batch Commitment & Lifecycle Event Dispatch¶
- Objective: Seal the amended survey dossier, update document statuses, and dispatch legal acknowledgement dockets.
- Batch Re-Submission (
RelodgementService.relodgeBatch):- Surveyor submits
LodgementOperationswith actionRELODGE. - Updates document statuses from
QUERIEDto activeLODGED. - Generates an official Relodgement Acknowledgement Letter PDF (
RelodgementAcknowledgementNotification) bearing barcodes and re-filing timestamps. - Dispatches process event to
cis-workflow(Port 8090).
- Surveyor submits
Stage 6: Fast-Track Routing to Original Examiner & Statutory Approval¶
- Objective: Bypass initial triage queues and route the rectified batch directly back to the desk of the examiner who authored the original query.
- Intelligent Workflow Routing:
cis-workflowuses the parent batch metadata to assign the task directly to the original examiner's active worklist.- The examiner reviews only the differential comparison diff (
LodgementTree), verifying that each itemized query citation has been satisfied. - Upon endorsement, the batch bypasses Phase 1 triage and routes directly to statutory digital stamping (
StampingService) and master cadastre promotion.
5.3 Detailed Sequence Interaction Diagram¶
sequenceDiagram
autonumber
actor PLS as Land Surveyor (PLS)
participant BFF as cis-bff (:8080)
participant API as cis-api (:8089)
participant S3 as RustFS S3 (:9000)
participant WF as cis-workflow (:8090)
participant DB as Oracle Database 23 (:1521)
participant Exam as Assigned SG Examiner
%% 1. Query Notification
WF->>API: Query Callback (Batch 412/2026 QUERIED)
API->>DB: Set Status = 1528 (QUERIED)
API-->>PLS: Examiner Query Notice PDF Issued
%% 2. Relodge Creation
PLS->>BFF: POST /api/relodgement/addRelodge (parentDraftId = 5041)
BFF->>API: Initialize Child Relodgement Draft
API->>DB: INSERT INTO LodgementDraft (parentDraftId, firstParentDraftId)
DB-->>API: childDraftId = 5099
API-->>PLS: Relodgement Draft Ready
%% 3. Tree Diff & File Upload
PLS->>BFF: GET /api/relodgement/getLodgementTree?draftId=5099
API-->>PLS: Return LodgementTree (Itemized Defects)
PLS->>BFF: POST /api/lodgement/updateDoc (Rectified Diagram PDF)
BFF->>API: Upload Replacement File
API->>S3: PutObject (RustFS S3 :9000)
API->>DB: Link new document to sgDocumentId
API-->>PLS: Document Replacement Staged
%% 4. Re-Submission & Fast Track Routing
PLS->>BFF: POST /api/relodgement/relodge (LodgementOperations.RELODGE)
BFF->>API: Execute Batch Relodgement
API->>DB: Update Status to 1928 (LODGED)
API->>WF: Re-activate Workflow (Direct Route to Examiner)
WF->>Exam: Push directly into Examiner's Assigned Queue
API-->>PLS: Relodgement Acknowledgement Issued
5.4 State Machine: Relodgement Query & Re-Submission Progression¶
stateDiagram-v2
[*] --> BATCH_QUERIED: Module 4 Examiner issues Query Notes
BATCH_QUERIED --> CHILD_DRAFT_CREATED: PLS clicks 'Relodge' (addRelodge)
CHILD_DRAFT_CREATED --> TREE_INSPECTION: getLodgementTree() builds diff
TREE_INSPECTION --> DOCUMENTS_RECTIFIED: Corrected diagrams & tables uploaded
DOCUMENTS_RECTIFIED --> DIFFERENTIAL_VALIDATION: ConsistencyCheckAlgorithm re-run
DIFFERENTIAL_VALIDATION --> RELODGE_COMMITTED: relodgeBatch(RELODGE) executed
DOCUMENTS_RECTIFIED --> ABANDONED: cancelBatch(CANCEL) executed
ABANDONED --> CANCELLED_TERMINAL: Sequences freed & docket closed
RELODGE_COMMITTED --> FAST_TRACK_EXAMINER: Directly assigned to original reviewer
FAST_TRACK_EXAMINER --> APPROVED_STAMPED: Queries resolved & diagram signed
FAST_TRACK_EXAMINER --> BATCH_QUERIED: Secondary query issued
APPROVED_STAMPED --> [*]
CANCELLED_TERMINAL --> [*]
5.5 Relodgement Engine REST API Reference Matrix¶
| HTTP Verb | Endpoint | Handler Method | Request Body / Parameters | Statutory Function / Description |
|---|---|---|---|---|
POST |
/api/relodgement/addRelodge |
addRelodgeEntity |
LodgementDraftDto |
Initializes child relodgement draft linked to parent draft ID. |
POST |
/api/relodgement/updateRelodge |
updateRelodge |
LodgementDraftDto |
Updates child relodgement draft attributes and delivery options. |
GET |
/api/relodgement/getLodgementTree |
getLodgementTree |
draftId |
Builds hierarchical differential tree contrasting queried vs amended records. |
POST |
/api/relodgement/relodge |
relodgeBatch |
LodgementOperations |
Commits rectified submission and re-triggers workflow to original examiner. |
POST |
/api/relodgement/cancel |
cancelBatch |
LodgementOperations |
Abandons queried survey application, deactivating draft and freeing numbers. |
POST |
/api/relodgement/deleteStep |
deleteStep |
stepId |
Deletes a queried statutory step, recalculating survey topology and fees. |
Module 6: Maintenance Engine — Statutory Cadastral Alterations & Outcome Notices¶
The Maintenance Engine governs post-approval statutory changes to already registered cadastral land parcels, general plans, and territorial boundaries. Unlike new land surveys (Modules 2, 3, and 4), maintenance actions represent statutory administrative proclamations under municipal planning legislation (e.g., SPLUMA), High Court interdicts, land restitution orders, and provincial gazettes.
The engine administers 12 statutory alteration categories (MaintenanceReason), manages multi-step maintenance drafts, enforces procedural compliance checklists, and generates certified Flying Saucer outcome notice PDFs dispatched directly to the Registrar of Deeds and municipal authorities.
6.1 Complete End-to-End Lifecycle Vector Architecture¶
Below is the verified end-to-end 6-stage lifecycle architecture of the Maintenance Engine, illustrating alteration initiation, gazette proclamation uploads, statutory checklists, SG officer scrutiny, and deeds outcome dockets:
6.2 Chronological Stage-by-Stage Lifecycle Walkthrough¶
%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '14px', 'fontFamily': 'Roboto', 'lineColor': '#0d9488' }}}%%
flowchart LR
classDef stage fill:#F0FDFA,stroke:#0D9488,stroke-width:2px,color:#134E4A;
classDef action fill:#EFF6FF,stroke:#2563EB,stroke-width:2px,color:#1E40AF;
classDef complete fill:#ECFDF5,stroke:#047857,stroke-width:2px,color:#064E3B;
S1["1. Alteration Initiation<br/>(MaintenanceReason)"]:::stage
S2["2. Steps & Gazette Upload<br/>(Legal Evidence & Plans)"]:::action
S3["3. Checklists & Tariffs<br/>(Procedural Audit & PDF)"]:::stage
S4["4. Lodgement Checkout<br/>(Settlement & Workflow)"]:::stage
S5["5. SG Officer Scrutiny<br/>(Statutory Examination)"]:::complete
S6["6. Outcome Notice Issued<br/>(Deeds & Municipal Notice)"]:::complete
S1 --> S2 --> S3 --> S4 --> S5 --> S6
Stage 1: Maintenance Application Initiation & Reason Selection¶
- Objective: Initiate an official cadastral maintenance docket linked to a specific statutory legal trigger.
- Core Capabilities (
MaintenanceDraftService.saveDraft,MaintenanceReason):- Municipal town planners, conveyancers, or professional surveyors initiate a
MaintenanceDraft. - Enforces selection of an authoritative statutory
MaintenanceReason:EXCISION(2486L): Carving agricultural holding land into urban township cadastre.PUBLIC_PLACE_CLOSURE(2489L): Municipal closure of public parks, squares, or civic amenities.STREET_CLOSURE(2490L): Permanent closure of road reserves, public lanes, or pedestrian ways.STREET_NAME(2492L): Municipal proclamation altering public street names.CANCELLATION_ALL_PARCELS(2487L): Complete cancellation of an approved General Plan or diagram.TYPE_PARTIAL_CANCELLATION_GP(2827L): Partial cancellation of specific erven within an approved GP.NOTARIAL_SERVITUDE(9907L): Registration of powerline, pipeline, or right-of-way notarial servitudes.
- Municipal town planners, conveyancers, or professional surveyors initiate a
Stage 2: Steps Configuration & Gazette Proclamation Ingestion¶
- Objective: Detail the cadastral units subject to alteration and attach certified legal proclamations.
- Evidence Ingestion Mechanics (
MaintenanceDraftSteps,MaintenanceDraftDocument):- Surveyors construct sequential
MaintenanceDraftStepsdetailing the mother parcel, child portions, and deeds registration division. - Uploads mandatory evidentiary dockets directly to RustFS S3 (
Port 9000):- Official Provincial Gazette publication notices.
- Certified Municipal Council resolution minutes.
- High Court orders or land claims court restitution judgments.
- Sketch plans illustrating affected road reserves or park perimeters.
- Surveyors construct sequential
Stage 3: Procedural Compliance Checklists & Tariff Simulation¶
- Objective: Enforce procedural statutory compliance and compute administrative maintenance tariffs.
- Scrutiny & Invoicing Mechanics (
MaintenanceDraftChecklistDTO,MaintenancePerformaInvoiceService):- Evaluates statutory quality control responses (
QcChecklistResponse) under list code 387, verifying public notice advertising dates, objection appeal window expiries, and municipal engineer consents. - Invokes fee simulation to compute statutory tariffs based on the category of alteration and parcel area.
- Compiles and dispatches an official proforma tax invoice PDF to the applicant.
- Evaluates statutory quality control responses (
Stage 4: Lodgement Checkout & Workflow Submission¶
- Objective: Confirm fee settlement (or institutional statutory fee waiver) and submit the docket for Surveyor-General scrutiny.
- Checkout Pipeline (
MaintenanceResource.submitDraft,MaintenanceDraftPayment):- Applicant records payment details or uploads municipal exemption dockets.
- Locks the maintenance draft against further modification (
status = SUBMITTED). - Dispatches process execution event to
cis-workflow(Port 8090), placing the dossier in the Surveyor-General Maintenance Queue.
Stage 5: Surveyor-General Officer Scrutiny & Registry Alteration¶
- Objective: Review legal authority, verify boundary continuity, and execute the physical cadastral alteration in the master registry.
- Statutory Scrutiny Mechanics:
- SG Cadastral Officer scrutinizes gazette notices against underlying registered parcels in
cis-search. - Registry Mutation:
- Updates parcel statuses in
SgdataParcels(e.g., transitions park or street reserve to developable Erf, or marks cancelled general plan erven asCANCELLED, code1529L). - Updates mother parcel remaining extent balances in
SgdataParentChild. - Registers notarial servitudes as encumbrance child rights.
- Updates parcel statuses in
- SG Cadastral Officer scrutinizes gazette notices against underlying registered parcels in
Stage 6: Statutory Outcome Certification & Deeds Office Dispatch¶
- Objective: Compile legally certified outcome notice documentation and transmit to the Registrar of Deeds and municipality.
- Outcome Notice Generation (
MaintenanceOutcomeLetterService, Flying Saucer PDF):- Automatically compiles specialized, sealed statutory outcome notice PDFs:
MaintenanceOutcomeLetterNotification: Generic cadastral modification certificate.MaintenancePPCOutcomeLetterNotification: Public Place Closure certificate required by conveyancers.MaintenanceStreetRenameOutcomeLetterNotification: Official gazetted street renaming notices dispatched to municipal GIS and postal authorities.
- Stores certified PDFs in RustFS S3 and hands the completed record over to Module 7 (Archival).
- Automatically compiles specialized, sealed statutory outcome notice PDFs:
6.3 Detailed Sequence Interaction Diagram¶
sequenceDiagram
autonumber
actor Planner as Municipal Planner / PLS
participant BFF as cis-bff (:8080)
participant API as cis-api (:8089)
participant S3 as RustFS S3 (:9000)
participant WF as cis-workflow (:8090)
participant DB as Oracle Database 23 (:1521)
participant Deeds as Registrar of Deeds
%% 1. Initiation
Planner->>BFF: POST /api/maintenance/saveDraft (EXCISION / PPC)
BFF->>API: Forward with Bearer JWT
API->>DB: Persist MaintenanceDraft & Steps
API-->>Planner: Maintenance Draft Initialized
%% 2. Gazette Upload
Planner->>BFF: POST /api/maintenance/saveAnnexure (Provincial Gazette PDF)
BFF->>API: Stream Gazette Proclamation
API->>S3: PutObject (RustFS S3 :9000)
API->>DB: Persist MaintenanceDraftDocument
API-->>Planner: Gazette Document Staged
%% 3. Invoicing & Submit
Planner->>BFF: POST /api/maintenance/processInvoice
API->>API: MaintenancePerformaInvoiceService.calculate()
API-->>Planner: Proforma Tax Invoice Issued
Planner->>BFF: POST /api/maintenance/submitDraft (Payment Receipt)
API->>WF: Initiate Maintenance Workflow Process
WF-->>API: Status = UNDER_SG_SCRUTINY
API-->>Planner: Application Submitted
%% 4. SG Officer Endorsement & Deeds Notice
Note over WF,API: SG Cadastral Officer Scrutinizes Proclamation & Boundary
WF->>API: Trigger Endorsement Callback
API->>DB: Update SgdataParcels (Set Status = CANCELLED / EXCISED)
API->>API: MaintenanceOutcomeLetterService.generatePdf()
API->>S3: Upload Sealed Outcome Letter PDF
API->>Deeds: Transmit Statutory Notice for Title Deed Endorsement
API-->>Planner: Statutory Alteration Registered & Outcome Docket Issued
6.4 State Machine: Cadastral Maintenance Lifecycle¶
stateDiagram-v2
[*] --> DRAFT_CREATED: User initiates maintenance application
DRAFT_CREATED --> STEPS_CONFIGURED: Add parcels, steps & MaintenanceReason
STEPS_CONFIGURED --> GAZETTES_UPLOADED: Attach provincial gazette notices & council minutes
GAZETTES_UPLOADED --> CHECKLIST_VERIFIED: Complete procedural compliance checklist
CHECKLIST_VERIFIED --> INVOICED: Tariff computed & proforma invoice issued
INVOICED --> SUBMITTED: Payment settled & submitted to cis-workflow
SUBMITTED --> UNDER_EXAMINATION: Ingested into SG Maintenance queue
UNDER_EXAMINATION --> QUERIED: Procedural defect or gazette ambiguity
QUERIED --> UNDER_EXAMINATION: Rectified gazette notice uploaded
UNDER_EXAMINATION --> APPROVED: SG Officer endorses alteration
APPROVED --> REGISTRY_MUTATED: SgdataParcels status updated (Cancelled/Excised)
REGISTRY_MUTATED --> OUTCOME_ISSUED: Sealed Outcome Notice generated & sent to Deeds
OUTCOME_ISSUED --> ARCHIVED: Handed over to Module 7 Archival
ARCHIVED --> [*]
6.5 Maintenance Engine REST API Reference Matrix¶
| HTTP Verb | Endpoint | Handler Method | Request Body / Parameters | Statutory Function / Description |
|---|---|---|---|---|
POST |
/api/maintenance/saveDraft |
saveMaintenanceDraft |
MaintenanceDraftDto |
Initializes or updates a cadastral maintenance application draft. |
GET |
/api/maintenance/draft/{draftId} |
getMaintenanceDraft |
draftId |
Retrieves complete draft state, steps, and gazette attachments. |
POST |
/api/maintenance/saveSteps |
saveMaintenanceDraftStep |
MaintenanceDraftStepsDto |
Adds a statutory alteration step linked to a MaintenanceReason. |
POST |
/api/maintenance/saveDraftRequest |
saveMaintenanceDraftRequest |
MaintenanceDraftRequestDto |
Links affected cadastral parcels to the maintenance step. |
POST |
/api/maintenance/saveAnnexure |
saveMaintenanceDocument |
Multipart MaintenanceDraftAnnexureDto |
Ingests provincial gazette notices and municipal resolutions. |
POST |
/api/maintenance/processInvoice |
processInvoice |
draftId |
Computes dynamic statutory maintenance alteration tariffs. |
GET |
/api/maintenance/generatePerformaInvoice |
generatePdf |
draftId |
Compiles official DALRRD Flying Saucer tax proforma invoice PDF. |
POST |
/api/maintenance/addPayment |
addPayment |
MaintenanceDraftPaymentDto |
Records EFT settlement receipt or municipal fee waiver certificate. |
POST |
/api/maintenance/submitDraft |
submitDraft |
draftId |
Locks maintenance draft and transitions workflow to SG examination. |
GET |
/api/maintenance/getOutcomeLetter |
getOutcomeLetter |
draftId |
Streams certified PDF outcome letter (Excision, PPC, Street Rename). |
Module 7: Archival & Historical Records Archive (HRA / PlanSafe)¶
The Archival & Historical Records Archive (HRA / PlanSafe) module ensures the permanent legal preservation, physical strongroom security, high-resolution scanning, and spatial discovery of cadastral records spanning more than a century of national land registration.
It operates two complementary preservation tracks:
1. Digital HRA Pipeline (HistoricalRecordsArchiveService, HraScanDocumentService): High-throughput scanning, image quality auditing (DPI, skew, legibility), attribute OCR extraction, and Lucene spatial search index synchronization in cis-search.
2. PlanSafe Physical Strongroom Governance (PlanSafeDocTrackingService): Barcode-driven physical custody tracking of irreplaceable historical linen and paper dockets inside fireproof Surveyor-General vaults (Cabinet, Drawer, Box, and Folio coordinates).
7.1 Complete End-to-End Lifecycle Vector Architecture¶
Below is the verified end-to-end 6-stage lifecycle architecture of the Archival Engine, illustrating post-approval ingestion from Module 4, physical packet bundling, scanning quality checklists, metadata indexing, PlanSafe vault tracking, and search enablement:
7.2 Chronological Stage-by-Stage Lifecycle Walkthrough¶
%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '14px', 'fontFamily': 'Roboto', 'lineColor': '#e11d48' }}}%%
flowchart LR
classDef stage fill:#FFF1F2,stroke:#E11D48,stroke-width:2px,color:#881337;
classDef action fill:#EFF6FF,stroke:#2563EB,stroke-width:2px,color:#1E40AF;
classDef complete fill:#ECFDF5,stroke:#047857,stroke-width:2px,color:#064E3B;
S1["1. Post-Approval Ingest<br/>(ArchiveScheduler ShedLock)"]:::stage
S2["2. Packet Bundling<br/>(ArcPacket & Barcodes)"]:::action
S3["3. Scanning & QC<br/>(HraScanningChecklist)"]:::stage
S4["4. Metadata Indexing<br/>(ArcMetaData & Lucene)"]:::stage
S5["5. PlanSafe Strongroom<br/>(Vault Physical Custody)"]:::complete
S6["6. Discovery & Procurement<br/>(Module 1 Feeder)"]:::complete
S1 --> S2 --> S3 --> S4 --> S5 --> S6
Stage 1: Post-Approval Handover & Automated Ingestion¶
- Objective: Ingest approved survey batches immediately following Surveyor-General digital stamping in Module 4.
- Automated Ingestion Pipeline (
ArchiveScheduler,HistoricalRecordsArchiveService):- Coordinated via distributed ShedLock (
@SchedulerLock(name = "archive_scheduler_task")). - Periodically scans
LodgementBatchfor newly approved submissions (isExamined = 1). - Ingests
PostApprovalDTOcontaining stamped diagram PDFs, general plans, and coordinate tables. - Creates master
HistoricalRecordsArchiverecords linking the statutory SG Diagram number, approval year, and provincial registry.
- Coordinated via distributed ShedLock (
Stage 2: Archival Packet Bundling & Barcode Generation¶
- Objective: Organize disparate survey diagrams, title deeds, and working plans into coherent legal archival packets.
- Packet Architecture (
PacketService,ArcPacket,ArcPacketDocument):- Groups related records into an
ArcPacketrepresenting a physical or digital archival envelope. - Generates a unique, high-entropy Code128 barcode docket (e.g.,
ARC-PKT-2026-0089). - Links all constituent documents into
ArcPacketDocumentwith verified page counts and file format classifications. - Governs packet lifecycle progression:
DRAFT\(\rightarrow\)DISPATCHED\(\rightarrow\)ARCHIVED.
- Groups related records into an
Stage 3: Scanning Bureau Digitization & Image Quality Auditing¶
- Objective: Digitize historical paper archives at high throughput while strictly enforcing image legibility standards.
- Scanning Quality Pipeline (
HraScanDocumentService,HraScanningChecklist):- Ingests scanned image streams (600 DPI uncompressed TIFF and PDF/A) directly from scanning bureau hardware.
- Quality Checklists (
HraScanningChecklistService):- Image Resolution: Verifies minimum 300–600 DPI optical scan quality.
- Skew & Alignment: Automated detection of rotated or skewed diagram scans.
- Seal & Signature Clarity: Verifies that historic red wax seals, embossed Surveyor-General stamps, and surveyor signatures remain clearly legible.
- Promotes approved scans to
SCANNED_QC_OKstatus.
Stage 4: Automated Metadata Extraction & Lucene Search Indexing¶
- Objective: Extract alphanumeric cadastral attributes and synchronize them with
cis-searchfor sub-second spatial discovery. - Metadata Extraction Engine (
MetaDataService,AttributeDataService):- Populates
ArcMetaDataand granular attribute tables (HraScanAttributeData,ArcAttributeData). - Tags each archival document with:
- Administrative Hierarchy: Province -> Municipality -> Township / Registration Division.
- Parcel Identifiers: Erf Number, Portion Number, Farm Name, Sectional Scheme Name.
- Survey Details: Original Land Surveyor Name, Survey Completion Date, General Plan Reference.
- Feeds extracted metadata directly into the embedded
cis-searchLucene index underSearchContext.PARCELandSearchContext.FARM.
- Populates
Stage 5: PlanSafe Physical Strongroom Custody Governance¶
- Objective: Track the precise physical custody of original paper diagrams and field books inside fireproof Surveyor-General strongrooms.
- PlanSafe Tracking Architecture (
PlanSafeDocTrackingService,PlanSafeDetails):- Records exact strongroom coordinates:
Strongroom Name\(\rightarrow\)Cabinet Number\(\rightarrow\)Drawer Number\(\rightarrow\)Box ID\(\rightarrow\)Folio Index. - Barcode Check-In / Check-Out:
- When an examination officer, historical researcher, or state attorney requests physical access to an original diagram, the system logs officer identity, borrower reason, and sign-out timestamp.
- Enforces maximum retention windows and issues automated overdue return notifications.
- Records exact strongroom coordinates:
Stage 6: Public Discovery & Information System Procurement Enablement¶
- Objective: Make archived cadastral documents authoritative, searchable, and purchasable by registered surveyors, conveyancers, and citizens.
- Full Cadastral Loop Closure:
- Once indexed in HRA, the diagram PDF in RustFS S3 becomes instantly discoverable in Module 1 (Information System & Data Viewer).
- Surveyors preparing new subdivisions in Module 2 (Reservation Engine) query these archived parent records to initiate the next generation of land parcels.
7.3 Detailed Sequence Interaction Diagram¶
sequenceDiagram
autonumber
actor Officer as Archive Officer / Scanning Operator
participant BFF as cis-bff (:8080)
participant API as cis-api (:8089)
participant S3 as RustFS S3 (:9000)
participant Search as cis-search (In-Memory Lucene)
participant DB as Oracle Database 23 (:1521)
participant Vault as PlanSafe Physical Vault
%% 1. Ingestion
API->>API: ArchiveScheduler.performTask()
API->>DB: Ingest Stamped Documents into HistoricalRecordsArchive
DB-->>API: Master Archive ID = 8841
%% 2. Packet Bundling
Officer->>BFF: POST /api/archive/packet (Create ArcPacket)
BFF->>API: Group Diagrams & Deeds into Packet
API->>DB: INSERT INTO ArcPacket & ArcPacketDocument
API-->>Officer: Packet Barcode Docket Issued (ARC-PKT-2026-0089)
%% 3. Scan & Metadata
Officer->>BFF: POST /api/archive/scanDoc (Multipart 600 DPI TIFF/PDF)
BFF->>API: Upload Scanned Document
API->>S3: PutObject (RustFS S3 :9000)
API->>DB: Persist HraScanDocument
API->>API: MetaDataService.extractAttributes()
API->>Search: Synchronize Lucene Search Index (SearchContext.PARCEL)
API-->>Officer: Scan & Metadata Indexed Successfully
%% 4. PlanSafe Physical Strongroom Check-in
Officer->>BFF: POST /api/archive/plansafedoctracking (Barcode Scan)
BFF->>API: Register Physical Custody Coordinates
API->>DB: Record Strongroom, Cabinet, Drawer, Box
API->>Vault: Physical File Placed in Fireproof Strongroom
API-->>Officer: PlanSafe Custody Confirmed (File Available for Search)
7.4 State Machine: Cadastral Archival Docket & Physical Custody Lifecycle¶
stateDiagram-v2
[*] --> POST_EXAMINATION_PENDING: Approved in Module 4 Examination
POST_EXAMINATION_PENDING --> HRA_INGESTED: ArchiveScheduler ingests stamped docket
HRA_INGESTED --> PACKET_BUNDLED: PacketService creates ArcPacket & barcode
PACKET_BUNDLED --> SCANNING_BUREAU: Physical packet routed to scanners
SCANNING_BUREAU --> SCANNED_QC_PENDING: High-resolution images ingested
SCANNED_QC_PENDING --> SCAN_REJECTED: Skewed, illegible or low DPI
SCAN_REJECTED --> SCANNING_BUREAU: Re-scanned at correct settings
SCANNED_QC_PENDING --> SCANNED_QC_APPROVED: HraScanningChecklist verified
SCANNED_QC_APPROVED --> METADATA_INDEXED: MetaDataService tags parcels & feeds Lucene
METADATA_INDEXED --> PLANSAFE_FILED: Filed in fireproof strongroom (Cabinet/Drawer)
PLANSAFE_FILED --> CHECKED_OUT: Borrowed for court litigation or inquiry
CHECKED_OUT --> PLANSAFE_FILED: Returned to strongroom & barcode scanned
PLANSAFE_FILED --> DISCOVERY_ACTIVE: Live & purchasable in Module 1 Search
DISCOVERY_ACTIVE --> [*]
7.5 Archival Engine REST API Reference Matrix¶
The table below catalogs primary REST endpoints exposed by ArchiveResource:
| HTTP Verb | Endpoint | Handler Method | Request Body / Parameters | Statutory Function / Description |
|---|---|---|---|---|
POST |
/api/archive/processApproval |
processApproval |
PostApprovalDTO |
Ingests approved survey records into long-term historical archive. |
GET |
/api/archive/getApprovedBatches |
getApprovedBatches |
Pageable |
Queries batches approved in examination ready for archival ingestion. |
POST |
/api/archive/packet |
savePacket |
ArcPacketDTO |
Creates or updates an archival envelope packet docket. |
GET |
/api/archive/packet/{packetId} |
getPacket |
packetId |
Retrieves packet metadata and constituent ArcPacketDocument list. |
POST |
/api/archive/scanDoc |
saveScanDocument |
HraScanDocumentDTO |
Ingests high-resolution scanned survey diagrams and deeds. |
POST |
/api/archive/checklist |
saveChecklist |
HraScanningChecklistDTO |
Records scanning bureau quality verification audit checklist. |
POST |
/api/archive/metadata |
saveMetaData |
ArcMetaDataDTO |
Extracts and indexes cadastral search metadata into cis-search. |
POST |
/api/archive/plansafedoctracking |
savePlanSafeDocTracking |
PlanSafeDocTrackingDTO |
Records physical strongroom cabinet, drawer, and box custody coordinates. |
GET |
/api/archive/plansafedoctracking/register |
getRegister |
Pageable |
Queries PlanSafe physical document custody register and borrower logs. |
POST |
/api/archive/triggerArchive |
triggerManually |
ArchiveTriggerTaskVm |
Manually triggers scheduled archival ingestion tasks. |
3. Embedded Submodules¶
cis-api incorporates two specialized library modules compiled directly into its JAR (cis-api/build.gradle):
cis-search (Spatial & Text Query Provider)¶
- Embedded query layer optimizing spatial lookups and text searches across massive land registries.
- Shares the synchronized
SearchContextenum withcis-api(NGI,PARCEL,FARM,LUR, etc.) to guarantee seamless search indexing without RPC overhead.
cis-emailer (Document & Notification Engine)¶
- Formats dynamic HTML notifications using Thymeleaf templates.
- Generates official PDF letters, acknowledgements, and receipts using Flying Saucer XHTML-to-PDF engine.
- Automatically prepends active environment banners (e.g.,
[DEV],[UAT]) to avoid confusing recipients during test runs.
4. Storage & Runtime Integration¶
Persistence & Object Storage¶
- Relational Data: Connects to Oracle Database 23 (
:1521) via HikariCP and Spring Data JPA. - Object / Blob Storage: Connects to RustFS (
:9000) using S3-compatible APIs for all document uploads, scan packets, and generated docket PDFs. - Distributed Cache & Locking: Connects to Redis 7.4 (
:6379) for caching frequently queried cadastral layers and coordinating ShedLock scheduled background tasks.
Container Runtime Specifications¶
- Base Image: Eclipse Temurin OpenJDK 25
- Internal Listen Port:
8089(Host mapped toHOST_API_PORT=8089) - Health Check Endpoint:
GET http://localhost:8089/management/health - Volume Mounts:
/data/uploads(APP_STORAGE_LOCATION)/app/logs(Application Logback logs)
Module: cis-auth¶
cis-auth is the centralized Identity Provider and OAuth 2.1 / OpenID Connect 1.0 Authorization Server for the CIS ecosystem.
Key Capabilities¶
- OAuth2 / OIDC Engine:
- Implements Authorization Code flow with PKCE (
S256). - Implements Resource Owner Password Credentials (ROPC) with password expiry verification.
- Issues RS256 signed JSON Web Tokens (JWT) containing enriched user profiles, realm designations, and impersonator claims.
- Dynamic RSA Key Rotation:
- Generates and persists RSA 2048/4096-bit keypairs encrypted with AES-GCM in Oracle DB.
- Rotates active keys transparently and serves public keys via JWKS endpoint (
/.well-known/jwks.json). - Multi-Realm Authentication:
- Internal Realm: Authenticates against corporate Active Directory / OpenLDAP via Spring LDAP.
- External Realm: Authenticates external citizens and conveyancers with database credentials or FIDO2 / WebAuthn Passkeys.
- Token Revocation & Impersonation:
- Publishes token revocation and session termination events to Redis Pub/Sub.
- Supports administrative impersonation with mandatory audit log trails.
Module: cis-bff¶
cis-bff (Backend-for-Frontend) is the secure API Gateway and user-facing edge proxy that shields the internal microservices from direct browser exposure.
Architectural Role¶
sequenceDiagram
autonumber
actor Browser as User Browser
participant BFF as cis-bff (:8080)
participant Redis as Redis Session Store (:6379)
participant Auth as cis-auth (:8085)
participant API as cis-api (:8089)
Browser->>BFF: GET /login (Authorization Code + PKCE)
BFF->>Auth: Exchange Auth Code for Access/Refresh Tokens
Auth-->>BFF: JWT Access Token & Refresh Token
BFF->>Redis: Store Tokens mapped to Secure Session ID
BFF-->>Browser: Set-Cookie: CIS_SESSION (HttpOnly, Secure, SameSite)
Note over Browser,BFF: Subsequent API Requests
Browser->>BFF: GET /api/v1/cadastral/records (Cookie: CIS_SESSION)
BFF->>Redis: Fetch valid Access Token
BFF->>API: Reverse Proxy Request with Bearer <JWT>
API-->>BFF: Cadastral JSON Payload
BFF-->>Browser: Response JSON Payload
Security Guarantees¶
- No Tokens in Browser: Access and refresh tokens are stored exclusively server-side in Redis.
- CSRF Protection: Stateful double-submit cookie or token verification prevents cross-site request forgery.
- Session Eviction: Subscribes to Redis Pub/Sub events from
cis-authto immediately invalidate sessions on user logout or credential revocation. - Reverse Proxy: Intelligently proxies
/api/*endpoints tocis-apiand/workflow/*tocis-workflow.
Workflow Lifecycle & Status Analysis¶
1. Workflow Definition (The "Blueprint")¶
Workflows are not hardcoded but are data-driven. They are defined in the Workflow Studio (frontend) and saved into the database as a JSON configuration.
- Table:
WORKFLOWPROCESS - Key Columns:
PROCESSID: Unique ID of the workflow definition.CONFIGURATION: A JSON blob containing the entire logic (Nodes, Links, Roles, Statuses).PROVINCEID: Links the workflow to a specific province.ITEMID_MODULE: Links the workflow to a module (e.g., Lodgement, Maintenance).
Configuration JSON Structure¶
The JSON controls the status lifecycle. Each step is a Node, and transitions are Outlinks.
{
"Node": [
{
"NodeID": 101,
"NodeType": "Trigger",
"OutLink": [
{
"NextNodeID": 102,
"Action": "Submit",
"StatusInternal": "15", // The Internal Status whenever this path is taken
"StatusExternal": "20" // The External Status visible to users
}
]
},
{
"NodeID": 102,
"Role": "123", // Role ID responsible for this step
"ActionRequired": "Approve"
}
]
}
2. Triggering a Workflow¶
When a submission comes in (e.g., propert maintenance request), the backend triggers a specific workflow based on the Process Type and Province.
- API:
POST /via RoutingController/triggerTask - Request:
TriggerRequest(containsprocessId,provinceId,context,notes). - Logic:
- The system looks up the active
WorkflowProcessfor thatprocessId+provinceId. - It parses the
CONFIGURATIONJSON. - It finds the Trigger Node.
- It creates a new Workflow Instance.
- The system looks up the active
3. Workflow Objects & Tables (Runtime)¶
Once running, the state is tracked across these four key tables:
A. WORKFLOW (The "Instance")¶
Represents the overall running process.
* Table: WORKFLOW
* Key Columns:
* WORKFLOWID: Unique ID for this specific run.
* PROCESSID: Links back to the definition.
* REFERENCE_NO: The unique reference number (e.g., "GP-2023-...").
* INTERNAL_STATUS_ID / EXTERNAL_STATUS_ID: Dynamic. Updates as the workflow moves from node to node, based on the JSON configuration of the path taken.
* STATUSID: System Status (Hardcoded logic: 1 = Active, 2 = UpdateDatabase specific state).
B. WORKFLOWACTION (The "Task")¶
Represents the current pending task for a user.
* Table: WORKFLOW_ACTION
* Key Columns:
* ACTIONID: Unique Task ID.
* WORKFLOWID: Links to parent workflow.
* USERID: The user assigned to this task.
* NODEID: The step in the JSON config this task corresponds to.
* ACTED_ON: Timestamp when completed (Null if pending).
C. TRANSACTIONS (The "History")¶
Audit trail of every move.
* Table: TRANSACTIONS
* Key Columns:
* TRANSACTIONID: Unique ID.
* SUMMARY: Context/Description.
* COMMENTS: User notes.
* USERID: Who performed the action.
D. NOTIFICATION (The "Alerts")¶
Records of system notifications generated.
* Table: NOTIFICATIONS
* Linkage: Linked to WORKFLOWID and TRANSACTIONID.
4. Status Lifecycle & States¶
There are three layers of "Status":
-
System Status (
STATUSIDinWORKFLOWtable)- Controlled by Java code (
WorkflowProcessingService). - 1: Standard Processing
- 2: Update Database Step (System automated step)
- Controlled by Java code (
-
Workflow Statuses (
INTERNAL_&EXTERNAL_STATUS_ID)- Dynamic: Defined in the JSON configuration per outcome.
- Internal: Visible to internal officers (e.g., "Pending QA", "Referred for Correction").
- External: Visible to the applicant (e.g., "In Progress", "Awaiting Payment").
- Values: These are integers (e.g.,
15,20) that often map to a Lookup Table (likelyLIST_ITEMor similar generic list management incis-api).
-
Process Types (Enum:
ProcessType.java)- Defines the category of workflow.
- Examples:
EXCISION_REQUEST(366)LODGEMENT_REQUEST(278)RESERVATION_REQUEST(229)AMENDMENTS_REQUEST(906)
5. Summary of Flow¶
- Submission ->
triggerTaskAPI. - System reads
WORKFLOWPROCESSJSON -> CreatesWORKFLOW(Status X) -> CreatesWORKFLOWACTION(Task for User A). - User A completes Task ->
processTaskAPI. - System checks JSON for "Next Node" -> Updates
WORKFLOWStatus to Y -> Creates newWORKFLOWACTION(Task for User B). - Repeat until End Node.
6. List Management (The "Lookup Data")¶
The values used for Statuses, Process Types, Maintenance Reasons, and Document Types are not random integers. They are keys to a powerful generic lookup system stored in two tables:
A. M_LIST_MASTER (Categories)¶
Defines the types of lists available.
* Table: M_LIST_MASTER
* Key Column: LISTCODE (e.g., 50 might be "Workflow Statuses", 101 might be "Maintenance Reasons").
* Columns: CAPTION, ISSTATIC.
B. M_LIST_ITEM (Values)¶
Defines the specific options within a category.
* Table: M_LIST_ITEM
* Key Column: ITEMID (This is the ID used in Java Enums and JSON Config).
* Columns:
* ITEMCODE: Unique code (e.g., REAS001).
* LISTCODE: Links to the parent category.
* CAPTION: The text shown to the user (e.g., "Pending QA", "Excision", "Approved").
Example Mapping¶
- Enum:
MaintenanceReason.EXCISION(2486L) - Database:
M_LIST_ITEMtable has a row whereITEMID = 2486.CAPTION= "Excision".LISTCODE= [Some ID representing Maintenance Reasons].
Why this matters?¶
When configuring a workflow in Workflow Studio:
1. Statuses: You pick "Pending QA" from a dropdown. The system saves ID 15. This corresponds to LIST_ITEM 15.
2. Reasons: You pick "Excision". The system saves ID 2486.
3. Code: Java Enums (like ProcessType.java) must manually match these DB IDs. If you create a new List Item in the DB, you must update the Java Enum to match.
Module: cis-emailer¶
cis-emailer is the dedicated asynchronous notification and document generation library module for the CIS platform.
[!NOTE]
cis-emaileris an internal library submodule (project(":cis-emailer")) embedded directly intocis-api. It does not expose standalone REST endpoints or listen on an HTTP port; its services are invoked directly by domain services withincis-api.
Capabilities¶
- Email Template Rendering:
- Compiles dynamic HTML emails using Thymeleaf templates.
- Automatically injects environment banners (e.g.,
[DEV],[UAT]) based on active Spring profiles to avoid confusing end users during testing. - PDF Attachment Generation:
- Converts HTML receipts, certificates, and cadastral acknowledgement notices into PDF attachments using Flying Saucer (XHTML renderer).
- Transport Resilience:
- Robust error handling wrapping
JavaMailSender. - In local development, dispatches emails to Mailpit (
localhost:1025) for zero-risk inspection.
Module: cis-search¶
cis-search provides indexing and query capabilities across cadastral parcels, land deeds, and user registrations.
[!NOTE]
cis-searchis an internal library submodule (project(":cis-search")) embedded directly intocis-api. It does not expose standalone REST endpoints or listen on an HTTP port; it provides data models and query utilities utilized bycis-api.
Capabilities¶
- Full-Text Cadastral Querying:
- Supports searching land parcel records by Erf number, township, farm name, and administrative boundary.
- SearchContext Enum Synchronization:
- Synchronized search context constants (
NGI,LUR,PARCEL, etc.) aligning search queries acrosscis-apiand search indices. - Optimized Spatial & Deed Search:
- High-throughput query pipelines designed to offload heavy search indexing from the primary Oracle OLTP database.
Frameworks
Technical Frameworks Architecture¶
The Cadastral Information System (CIS) backend (cis-api-uam) is built upon modular, resilient, and enterprise-grade technical frameworks. These foundational frameworks govern cross-cutting concerns across all cadastral business domains (Reservation, Lodgement, Examination, Maintenance, and Archive).
Core Frameworks Summary¶
| Framework | Package Namespace | Primary Responsibilities | Key Capabilities |
|---|---|---|---|
| Dynamic Error Framework | com.dw.ngms.cis.framework.error |
Business validation, infrastructure exception translation, dynamic error responses | Zero hardcoded enums, \(O(1)\) concurrent in-memory caching, dual-channel resolution (ui vs api), dynamic template rendering, deep recursive PII redaction, RFC 9457 ProblemDetail. |
| Reporting Engine | com.dw.ngms.cis.reporting |
Analytical report generation, background export scheduling, bounded CSV streaming, PDF layout | Asynchronous export job queue, bounded chunked streaming, scope-based authorization, rate-limited download slots, multi-tenant province filtering. |
| Notification Engine | com.dw.ngms.cis.service.notification |
Multi-channel messaging, durable outbox delivery, document attachments | Multi-channel delivery (EMAIL, SMS, PDF), Redis-backed distributed idempotency, fail-fast strategy registries, audit ledger logging, transactional outbox queue. |
Architectural Interaction Model¶
flowchart TD
subgraph Client_Layer [Client Applications & Gateways]
ANGULAR["Angular Frontend (cis-internal / cis-web)"]
BFF["cis-bff (Backend-For-Frontend)"]
end
subgraph Business_Domains [Cadastral Business Modules]
RES["Reservation Module"]
LODGE["Lodgement Module"]
EXAM["Examination Module"]
MAINT["Maintenance Module"]
ARCH["Archive Module"]
end
subgraph Technical_Frameworks [Enterprise Technical Frameworks]
direction TB
subgraph Error_Framework [1. Error Handling Framework]
ERR_SVC["ErrorMessageService"]
ERR_REG["ErrorCodeRegistry (In-Memory O(1))"]
ERR_ADVICE["ExceptionHandlerAdvice"]
ERR_REDACT["RedactionService"]
end
subgraph Report_Framework [2. Reporting Engine]
REP_JOB["ReportJobService & Scheduler"]
REP_BUILDER["DynamicQueryBuilder"]
REP_STREAM["Bounded CsvArtifactWriter"]
REP_PDF["PdfArtifactRenderer"]
end
subgraph Notif_Framework [3. Notification Engine]
NOTIF_GW["NotificationFrameworkGateway"]
NOTIF_QUEUE["Durable Outbox Queue Worker"]
NOTIF_IDEMP["Redis Renewable Idempotency"]
NOTIF_CHANNELS["Channels: EMAIL, SMS, PDF"]
end
end
subgraph Infrastructure_Layer [Storage & Persistence]
ORACLE[("Oracle 23 Database (SGUSER)")]
REDIS[("Redis 7.4 Distributed Cache")]
S3[("RustFS S3 Object Storage")]
MAIL[("SMTP Mail Gateway")]
end
%% Client Ingress
ANGULAR & BFF --> Business_Domains
%% Error Flow
Business_Domains -->|throws BusinessException| ERR_ADVICE
ERR_ADVICE --> ERR_SVC
ERR_SVC --> ERR_REG
ERR_SVC --> ERR_REDACT
ERR_REG -.->|startup / refresh| ORACLE
ERR_ADVICE -->|HTTP 400, 422, 500 JSON| ANGULAR & BFF
%% Reporting Flow
Business_Domains & ANGULAR -->|request export / schedule job| REP_JOB
REP_JOB --> REP_BUILDER
REP_BUILDER --> ORACLE
REP_JOB --> REP_STREAM & REP_PDF
REP_STREAM & REP_PDF --> S3
%% Notification Flow
Business_Domains -->|trigger event / process step| NOTIF_GW
NOTIF_GW --> NOTIF_IDEMP
NOTIF_IDEMP --> REDIS
NOTIF_GW --> NOTIF_QUEUE
NOTIF_QUEUE --> NOTIF_CHANNELS
NOTIF_CHANNELS --> MAIL & S3 & ORACLE
Detailed Framework References¶
Explore the detailed architecture, database schemas, sequence workflows, and developer guides:
Dynamic Business Error Handling Framework¶
Target Platform: Spring Boot 4.1.2 | Java 25 | Jakarta EE 11 | Oracle Database 23ai
Package: com.dw.ngms.cis.framework.error
Git Branch: feat/error-framework
Author: Prateek Goel
1. Executive Summary & Design Goals¶
The CIS Error Handling Framework is an enterprise-grade, database-driven error resolution and translation engine for the Cadastral Information System. It replaces legacy ad-hoc runtime exceptions and hardcoded Java enums with a 100% dynamic, multi-channel architecture.
Key Capabilities¶
- 100% Dynamic Catalog (Zero Hardcoded Enums): Error codes are semantic uppercase strings (
RESERVATION_EXPIRED,LODGEMENT_DOCUMENT_MISSING,SUBDIVISION_EXCEEDS_EXTENT). No code recompilation or redeployment is required when adding or modifying error definitions. - Dual-Channel Delivery (
uivsapi): The engine inspectsX-Client-Channel. Web clients receive actionable, user-friendly toast messages; automated consumers and API integrations receive detailed technical diagnostics. - High Performance In-Memory Caching: Preloads all error definitions on startup into concurrent memory structures. Lookups execute in \(O(1)\) time with zero database queries during request execution.
- Zero-Downtime Hot Reloading: Administrators can trigger
POST /api/v1/system/errors/refreshto re-synchronize memory structures immediately from Oracle without server restart. - Deep Recursive Redaction: Automatically sanitizes sensitive keys (
password,token,secret,authorization,pin,ssn) and regex patterns in messages and nested payloads. - Spring Boot 4 Native: Standardized on RFC 9457
ProblemDetailwith correlationtraceIdand nativeNoResourceFoundExceptionrouting.
2. Dedicated Architectural Diagrams¶
2.1 Component & Boundary Diagram (Clean / Hexagonal Architecture)¶
flowchart TD
subgraph Clients [Client Layer]
ANGULAR["Angular Frontend (cis-internal)"]
EXTERNAL["BFF & External Microservices"]
end
subgraph SpringBoot4_Infrastructure [Spring Boot 4.1.2 MVC & Security Core]
DISPATCH["Spring DispatcherServlet"]
ROUTING["MvcRoutingExceptionAdvice (Order -1)\n[404 Route Not Found, 405 Method Not Allowed, 415 Media Mismatch]"]
SEC["Spring Security Filter Chain\n[401 AuthenticationEntryPoint, 403 AccessDeniedHandler]"]
end
subgraph Business_Domain [CIS Business Domain Services]
LODGE["LodgementService"]
RES["ReservationService"]
MAINT["MaintenanceService"]
EXAM["ExaminationService"]
ARCH["ArchiveService"]
INFO["InfoRequestService"]
end
subgraph Self_Contained_Framework [Module Root: com.dw.ngms.cis.framework.error]
direction TB
subgraph Boundary_Adapter [Public Boundary & API Adapter]
EXC["BusinessException\n(errorKey, args, details)"]
ADVICE["ExceptionHandlerAdvice\n(@RestControllerAdvice)"]
CTRL["ErrorCodeController\n(/api/v1/system/errors & /refresh)"]
end
subgraph Core_Engine [Domain Resolution Engine]
REG["ErrorCodeRegistry\n(In-Memory O(1) Concurrent Cache)"]
SVC["ErrorMessageService\n(Multi-Channel Resolver)"]
GRP["GroupResolutionService\n(Regex Pattern Exception Hierarchy)"]
RENDER["TemplateRenderer\n(Mustache & Positional {0} Engine)"]
REDACT["RedactionService\n(PII & Secret Sanitizer)"]
end
subgraph Data_Access [Persistence Layer]
E_CODE["ErrorCode Entity"]
E_MSG["ErrorMessage Entity"]
E_GRP["ErrorGroup Entity"]
E_MAP["ErrorGroupMapping Entity"]
E_HIST["ErrorMessageHistory Entity"]
REPOS["Spring Data JPA Repositories"]
end
end
subgraph Oracle_DB [Oracle Database: SGUSER Schema]
T_CODES[("ERROR_CODES\n(Catalog)")]
T_MSGS[("ERROR_MESSAGES\n(Templates)")]
T_GROUPS[("ERROR_GROUPS\n(Regex Patterns)")]
T_MAPS[("ERROR_GROUP_MAPPINGS\n(Channel Mappings)")]
T_HIST[("ERROR_MESSAGE_HISTORY\n(Audit Trail)")]
end
%% Wiring
ANGULAR & EXTERNAL --> DISPATCH
DISPATCH --> ROUTING
DISPATCH --> SEC
DISPATCH --> Business_Domain
Business_Domain -->|throws| EXC
EXC --> ADVICE
DISPATCH -->|Spring MVC & Unhandled Exceptions| ADVICE
CTRL --> REG
ADVICE --> SVC
SVC --> REG
SVC --> GRP
SVC --> RENDER
SVC --> REDACT
REG --> REPOS
GRP --> REPOS
REPOS --> E_CODE & E_MSG & E_GRP & E_MAP & E_HIST
E_CODE & E_MSG & E_GRP & E_MAP & E_HIST --> Oracle_DB
ADVICE -->|HTTP 400, 402, 404, 409, 422, 500| ANGULAR & EXTERNAL
2.2 Database Schema Relation ER Diagram (ERD)¶
erDiagram
ERROR_CODES ||--o{ ERROR_MESSAGES : "has templates"
ERROR_CODES ||--o{ ERROR_GROUP_MAPPINGS : "referenced by code"
ERROR_GROUPS ||--|{ ERROR_GROUP_MAPPINGS : "contains mappings"
ERROR_MESSAGES ||--o{ ERROR_MESSAGE_HISTORY : "tracks revisions"
ERROR_CODES {
VARCHAR2(50) CODE PK "Semantic error key (e.g. RESERVATION_EXPIRED)"
VARCHAR2(20) SEVERITY "INFO, WARN, ERROR, CRITICAL"
NUMBER DEFAULT_HTTP_STATUS "400, 402, 404, 409, 422, 500"
VARCHAR2(1000) DEFAULT_MESSAGE "Fallback message template"
CHAR(1) ACTIVE "'Y' or 'N'"
VARCHAR2(1000) DESCRIPTION "Technical failure condition"
VARCHAR2(100) CATEGORY "Functional domain module"
VARCHAR2(100) DOC_URL "Documentation wiki reference"
VARCHAR2(100) CREATED_BY "Author or system user"
TIMESTAMP CREATED_AT "Creation timestamp"
TIMESTAMP UPDATED_AT "Last modification timestamp"
}
ERROR_MESSAGES {
NUMBER ID PK "Synthetic primary key"
VARCHAR2(50) CODE FK "Foreign key to ERROR_CODES(CODE)"
VARCHAR2(10) LOCALE "Language code: 'en', 'af', etc."
VARCHAR2(50) CHANNEL "Delivery target: 'ui' or 'api'"
VARCHAR2(512) EXCEPTION_CLASS "Optional explicit class binding"
VARCHAR2(1000) EXCEPTION_PATTERN "Optional regex match on exception message"
VARCHAR2(2000) MESSAGE_TEMPLATE "Parameterized template: 'Reservation #{0} expired on {1}.'"
NUMBER HTTP_STATUS_OVERRIDE "Optional HTTP status override"
NUMBER PRIORITY "Evaluation priority (lowest number first)"
CHAR(1) ACTIVE "'Y' or 'N'"
NUMBER EXPOSE_STACK_TRACE "0 = suppressed, 1 = exposed"
TIMESTAMP EFFECTIVE_FROM "Optional scheduling start"
TIMESTAMP EFFECTIVE_TO "Optional scheduling expiry"
}
ERROR_GROUPS {
NUMBER ID PK "Synthetic primary key"
VARCHAR2(100) NAME UK "Unique group name (e.g. DataAccessGroup)"
VARCHAR2(1000) PATTERN "Regex match on class name (e.g. .*DataAccessException)"
VARCHAR2(500) DESCRIPTION "Group description"
NUMBER ACTIVE "1 = active, 0 = inactive"
}
ERROR_GROUP_MAPPINGS {
NUMBER ID PK "Synthetic primary key"
NUMBER GROUP_ID FK "Foreign key to ERROR_GROUPS(ID)"
VARCHAR2(50) CODE "Target error code"
VARCHAR2(10) LOCALE "Target language"
VARCHAR2(50) CHANNEL "Channel: 'ui' or 'api'"
VARCHAR2(1000) MESSAGE_TEMPLATE "Channel-specific template"
NUMBER PRIORITY "Evaluation order"
NUMBER ACTIVE "1 = active, 0 = inactive"
NUMBER EXPOSE_STACKTRACE "0 = suppressed, 1 = exposed"
}
ERROR_MESSAGE_HISTORY {
NUMBER HISTORY_ID PK "Audit record primary key"
NUMBER MESSAGE_ID "Reference to modified ERROR_MESSAGES(ID)"
VARCHAR2(50) CODE "Error code"
VARCHAR2(20) ACTION "'INSERT', 'UPDATE', 'DELETE'"
CLOB PAYLOAD "JSON snapshot of previous state"
VARCHAR2(100) PERFORMED_BY "User who executed mutation"
TIMESTAMP PERFORMED_AT "Audit timestamp"
}
2.3 Runtime Exception Resolution Sequence Diagram¶
sequenceDiagram
autonumber
actor User as Angular Client
participant Controller as REST Resource
participant Service as Business Service
participant Advice as ExceptionHandlerAdvice
participant MsgSvc as ErrorMessageService
participant Registry as ErrorCodeRegistry
participant GroupSvc as GroupResolutionService
participant Renderer as TemplateRenderer
participant Redact as RedactionService
User->>Controller: POST /api/v1/lodgement/draft/submit
Controller->>Service: submitLodgement(draftId)
Note over Service: Domain Rule Violation: Mandatory document missing
Service-->>Advice: throw new BusinessException("LODGEMENT_DOCUMENT_MISSING", "General Plan", "1049")
Advice->>MsgSvc: resolveErrorByCode("LODGEMENT_DOCUMENT_MISSING", locale="en", channel="ui", args)
MsgSvc->>Registry: findCode("LODGEMENT_DOCUMENT_MISSING")
Registry-->>MsgSvc: ErrorCode (HTTP 400, Severity WARN, Category LODGEMENT)
MsgSvc->>Registry: findMessage("LODGEMENT_DOCUMENT_MISSING", locale="en", channel="ui")
Registry-->>MsgSvc: ErrorMessage (template="Mandatory document '{0}' is missing for lodgement #{1}.")
MsgSvc->>Renderer: render(template, args=["General Plan", "1049"])
Renderer-->>MsgSvc: "Mandatory document 'General Plan' is missing for lodgement #1049."
MsgSvc->>Redact: sanitize(renderedMessage, contextDetails)
Redact-->>MsgSvc: Sanitized message and metadata
MsgSvc-->>Advice: ResolvedError(code="LODGEMENT_DOCUMENT_MISSING", httpStatus=400, message=...)
Advice-->>User: HTTP 400 Bad Request + ResponseResult JSON
2.4 Dual-Channel Message & Payload Flow Diagram¶
flowchart LR
EXC["Exception Occurs<br/>(e.g. DataAccessException during SQL timeout)"] --> ROUTE{"Channel Header<br/>X-Client-Channel"}
ROUTE -->|"Channel UI: Browser Toast"| UI_PATH["Match Group: DataAccessGroup<br/>Template: DB_ERROR_UI"]
ROUTE -->|"Channel API: Server Integration"| API_PATH["Match Group: DataAccessGroup<br/>Template: DB_ERROR"]
UI_PATH --> UI_RES["HTTP 500<br/>Code: DB_ERROR_UI<br/>Message: Something went wrong with database<br/>TraceId: a1b2-c3d4"]
API_PATH --> API_RES["HTTP 500<br/>Code: DB_ERROR<br/>Message: Database query error ORA-01013<br/>TraceId: a1b2-c3d4<br/>Exception: QueryTimeoutException"]
UI_RES --> ANGULAR["Angular App (cis-internal)<br/>Displays Toast Notification"]
API_RES --> LOGS["Splunk / CloudWatch / BFF<br/>Full Technical Diagnostics"]
2.5 Class Hierarchy & Component Structural Diagram¶
classDiagram
direction TB
class RuntimeException {
<<Java Core>>
}
class BusinessException {
-String errorCode
-Object[] args
-Map~String, Object~ details
-Integer explicitStatus
+getErrorCode() String
+getArgs() Object[]
+getDetails() Map
+getExplicitStatus() Integer
}
class ConsistencyCheckException {
<<Domain Specific>>
}
class ErrorCode {
<<JPA Entity>>
-String code
-String severity
-Integer defaultHttpStatus
-String defaultMessage
-String active
-String category
-String docUrl
}
class ErrorMessage {
<<JPA Entity>>
-Long id
-String code
-String locale
-String channel
-String exceptionClass
-String exceptionPattern
-String messageTemplate
-Integer httpStatusOverride
-Integer priority
-Integer exposeStackTrace
}
class ErrorGroup {
<<JPA Entity>>
-Long id
-String name
-String pattern
-String description
-Integer active
}
class ErrorGroupMapping {
<<JPA Entity>>
-Long id
-ErrorGroup group
-String code
-String locale
-String channel
-String messageTemplate
-Integer priority
-Integer active
-Integer exposeStackTrace
}
class ErrorCodeRegistry {
<<In-Memory Cache>>
-Map~String, ErrorCode~ codesByCode
-List~ErrorMessage~ cachedMessages
-List~ErrorGroup~ cachedGroups
-List~ErrorGroupMapping~ cachedMappings
+refresh() void
+findCode(code) Optional~ErrorCode~
+isValid(code) boolean
+getDefaultStatus(code) Integer
+resolveDocUrl(code) String
}
class ErrorMessageService {
<<Resolution Engine>>
-ErrorCodeRegistry registry
-GroupResolutionService groupService
-RedactionService redactionService
+resolveErrorByCode(code, locale, channel, args) ResolvedError
+resolveError(exceptionClass, locale, channel, throwable, extraContext) ResolvedError
}
class GroupResolutionService {
<<Rule Engine>>
-ErrorCodeRegistry registry
-RedactionService redactionService
+resolveByGroup(exceptionClass, locale, channel, t, extraContext) Optional~ResolvedErrorWithMapping~
}
class TemplateRenderer {
<<Renderer Utility>>
+render(template, ctx, args) String
}
class RedactionService {
<<Sanitizer Utility>>
+redact(context) Map
+redactString(input) String
}
RuntimeException <|-- BusinessException
BusinessException <|-- ConsistencyCheckException
ErrorMessageService --> ErrorCodeRegistry : queries cache
ErrorMessageService --> GroupResolutionService : delegates unmapped
ErrorMessageService --> TemplateRenderer : formats templates
ErrorMessageService --> RedactionService : sanitizes PII
GroupResolutionService --> ErrorCodeRegistry : queries groups/mappings
GroupResolutionService --> TemplateRenderer : renders group templates
GroupResolutionService --> RedactionService : sanitizes group context
ErrorCodeRegistry --> ErrorCode : holds
ErrorCodeRegistry --> ErrorMessage : holds
ErrorCodeRegistry --> ErrorGroup : holds
ErrorCodeRegistry --> ErrorGroupMapping : holds
3. Developer Guide & Usage Standards¶
Throwing Business Errors in Domain Services¶
// 1. Simple error with positional arguments:
throw new BusinessException("RESERVATION_EXPIRED", reservationId, expiryDate);
// 2. Error with custom contextual details map:
throw new BusinessException("SUBDIVISION_EXCEEDS_EXTENT",
Map.of("baseline", 5.0, "current", 8.2),
baseline, totalArea);
// 3. Backward compatible legacy integer codes:
throw new GenericException(80001);
Channel Selection via HTTP Headers¶
Clients can explicitly request UI-optimized or API-optimized errors by including the following header:
X-Client-Channel: ui # Returns end-user actionable message (Default)
X-Client-Channel: api # Returns technical diagnostics for integration consumers
4. Operational API Endpoints¶
The framework exposes management endpoints under /api/v1/system/errors:
| Method | Endpoint | Description | Auth Required |
|---|---|---|---|
GET |
/api/v1/system/errors |
Returns full active catalog of error codes, messages, and documentation URLs | Yes |
POST |
/api/v1/system/errors/refresh |
Triggers atomic reload of in-memory cache from Oracle database | Admin / System |
GET |
/api/v1/system/errors/export |
Exports formatted error catalog documentation for frontend/wiki consumers | Yes |
5. Seeded Module Error Codes Catalog (104 Codes)¶
| Module Category | Sample Codes | Default Status | Default Message Sample |
|---|---|---|---|
INFORMATION_REQUEST |
INFO_REQUEST_NOT_FOUNDINFO_QUOTATION_EXPIREDINFO_UNAUTHORIZED_ACCESS |
404 422 403 |
Information request #{0} not found. Fee quotation for request #{0} expired on {1}. |
RESERVATION |
RESERVATION_EXPIREDRESERVATION_DUPLICATE_PARCELRESERVATION_QUOTA_EXCEEDED |
422 409 422 |
Reservation #{0} expired on {1} and cannot be processed. Parcel {0} in province {1} is already reserved. |
LODGEMENT |
LODGEMENT_DOCUMENT_MISSINGLODGEMENT_PAYMENT_MISMATCHLODGEMENT_PQ_DISCREPANCY |
400 422 422 |
Mandatory document '{0}' is missing for lodgement #{1}. Discrepancy in PQ sheet section {0}: expected {1}, calculated {2}. |
EXAMINATION |
EXAM_CONSISTENCY_FAILEDEXAM_CLOSURE_EXCEEDEDEXAM_CAVEAT_EXISTS |
422 422 409 |
Consistency check failed for parcel {0}: {1}. Mathematical closure tolerance exceeded for {0}. Cannot proceed: active caveat exists on parcel {0}. |
MAINTENANCE |
MAINT_SUBDIVISION_EXCEEDS_EXTENTMAINT_STREET_RENAME_CONFLICTMAINT_CANNOT_WITHDRAW_REGISTERED |
422 409 409 |
Subdivision deduction exceeds extent for {0}. Baseline={1}ha, Current={2}ha. Street name '{0}' already exists in municipality {1}. |
ARCHIVE |
ARCHIVE_PACKET_NOT_FOUNDARCHIVE_SCAN_RESOLUTION_LOWARCHIVE_METADATA_INVALID |
404 422 422 |
Archive packet #{0} not found. Scanned document '{0}' resolution ({1} DPI) is below minimum (300 DPI). |
USER & WORKFLOW |
USER_LOCKEDWORKFLOW_INVALID_TRANSITIONPAYMENT_VERIFICATION_FAILED |
423 422 402 |
Account is locked. Invalid workflow process transition requested. |
CIS Reporting Engine — Architecture & Developer Guide¶
Target Platform: Spring Boot 4.1.2 | Java 25 | Jakarta EE 11 | Oracle Database 23ai
Package: com.dw.ngms.cis.reporting
Git Branch: feat/error-framework
1. Executive Summary & Design Principles¶
The CIS Reporting Engine (com.dw.ngms.cis.reporting) provides analytical data extraction, statutory report compilation, and document generation across all Cadastral modules. It addresses the historical scaling bottlenecks identified in performance audits (unbounded heap retention, repeated calendar lookups, and injection vulnerabilities in dynamic SQL) through a modern, bounded streaming architecture.
Architectural Invariants¶
- Bounded Heap Footprint: CSV reports stream directly from JDBC cursors to disk artifacts via buffered chunks (
CsvArtifactWriter). Large exports (100k+ rows) execute within a bounded heap budget. - Safe Typed Query Construction:
DynamicQueryBuilderbinds named parameters strictly through server-owned column definitions, eliminating SQL concatenation vulnerabilities. - Multi-Tenant Scope Authorization:
ReportScopeAuthorizerenforces user jurisdiction (province, office, role boundaries) at the query level before execution. - Durable Asynchronous Job Queue: Reports exceeding synchronous timeout thresholds are dispatched as background jobs (
ReportJobService) tracked in Oracle (REPORT_EXPORT_JOB) and stored in S3/disk. - Rate-Limited Download Slots:
ReportDownloadSlotsbounds concurrent file downloads to protect backend bandwidth.
2. Dedicated Architectural Diagrams¶
2.1 Component & Pipeline Topology¶
flowchart TD
subgraph Client_Layer [Clients & Gateways]
ANGULAR["Angular Frontend"]
BFF["cis-bff"]
end
subgraph REST_API [Reporting API Layer]
RESOURCE["ReportJobResource / ReportingResource"]
LIMITS["ReportJobLimits & ReportDownloadSlots"]
ADVICE["ReportJobErrorAdvice"]
end
subgraph Core_Engine [com.dw.ngms.cis.reporting.core]
REGISTRY["ReportDefinitionRegistry"]
AUTH["ReportScopeAuthorizer"]
BUILDER["DynamicQueryBuilder"]
SCOPED["ScopedReport Interface"]
end
subgraph Job_Orchestration [com.dw.ngms.cis.reporting.jobs]
SERVICE["ReportJobService"]
SCHEDULER["ReportJobScheduling"]
TELEMETRY["ReportJobTelemetry"]
STORE["ReportJobStore"]
end
subgraph Artifact_Renderers [Artifact Generation]
CSV["CsvArtifactWriter (Streaming Bounded Buffer)"]
PDF["PdfArtifactRenderer (Thymeleaf / Flying Saucer)"]
end
subgraph Storage [Persistence & Storage]
ORACLE[("Oracle DB: REPORT_EXPORT_JOB")]
FS[("S3 / File System Storage")]
end
%% Flow
ANGULAR & BFF --> RESOURCE
RESOURCE --> LIMITS
RESOURCE --> AUTH
AUTH --> REGISTRY
RESOURCE --> SERVICE
SERVICE --> STORE
STORE --> ORACLE
SERVICE --> SCOPED
SCOPED --> BUILDER
BUILDER --> ORACLE
SCOPED --> CSV & PDF
CSV & PDF --> FS
SERVICE --> TELEMETRY
2.2 Background Report Job Lifecycle Sequence Diagram¶
sequenceDiagram
autonumber
actor User as Cadastral Officer
participant Resource as ReportJobResource
participant Auth as ReportScopeAuthorizer
participant JobSvc as ReportJobService
participant Store as ReportJobStore
participant Builder as DynamicQueryBuilder
participant Writer as CsvArtifactWriter
participant S3 as S3/File Storage
User->>Resource: POST /api/v1/reporting/jobs (type="ARCHIVE_PRODUCTION", filters, format="CSV")
Resource->>Auth: authorizeUserScope(user, filters)
Auth-->>Resource: Authorized Scope (Province: GAUTENG)
Resource->>JobSvc: submitReportJob(reportDef, filters, scope)
JobSvc->>Store: createJobRecord(status="PENDING")
Store-->>JobSvc: jobId=5024
JobSvc-->>Resource: JobCreatedResponse(jobId=5024, status="PENDING")
Resource-->>User: HTTP 202 Accepted { jobId: 5024 }
Note over JobSvc: Asynchronous Worker Execution
JobSvc->>Store: updateStatus(jobId=5024, "PROCESSING")
JobSvc->>Builder: buildBoundedQuery(reportDef, filters, scope)
Builder-->>JobSvc: Prepared SQL & Named Parameters
JobSvc->>Writer: streamResultsToArtifact(sql, params)
loop Bounded Row Chunks
Writer->>Writer: Fetch batch (1000 rows) -> Flush CSV buffer
end
Writer->>S3: saveArtifact(jobId=5024, file)
S3-->>Writer: artifactUri
JobSvc->>Store: updateStatus(jobId=5024, "COMPLETED", artifactUri)
Note over User: Polling or Notification
User->>Resource: GET /api/v1/reporting/jobs/5024/download
Resource->>Store: getJob(5024)
Store-->>Resource: Job(status="COMPLETED", artifactUri)
Resource-->>User: HTTP 200 File Stream (Content-Disposition: attachment)
2.3 Class Hierarchy Diagram¶
classDiagram
direction TB
class ScopedReport {
<<Interface>>
+getReportId() String
+generateReportData(filters, scope) Object
+supportsFormat(format) boolean
}
class BackgroundCsvReport {
<<Interface>>
+streamCsv(filters, scope, writer) void
+getEstimatedCount(filters, scope) long
}
class DynamicQueryBuilder {
-NamedParameterJdbcTemplate jdbcTemplate
+buildQuery(criteria, allowedColumns) PreparedQuery
+bindScopeRestrictions(sql, userScope) String
}
class ReportScopeAuthorizer {
+enforceProvinceScope(user, requestedProvinces) List~String~
+validateDateBounds(filters) void
}
class ReportJobService {
-ReportJobStore store
-ReportDefinitionRegistry registry
-ThreadPoolTaskExecutor executor
+submitJob(request) JobHandle
+pollJobStatus(jobId) JobStatusDto
+acquireDownloadSlot(jobId) InputStream
}
class CsvArtifactWriter {
-int bufferSize
+writeChunk(rows) void
+flush() void
+close() void
}
class PdfArtifactRenderer {
-TemplateEngine templateEngine
-ReportPdfUserAgent userAgent
+renderToPdf(templateName, model, outputStream) void
}
ScopedReport <|.. BackgroundCsvReport
BackgroundCsvReport <|.. ArchiveProductionReport
BackgroundCsvReport <|.. ReservationProductionReport
BackgroundCsvReport <|.. LodgementProductionReport
BackgroundCsvReport <|.. ExaminationProductionReport
ReportJobService --> ScopedReport : executes
ReportJobService --> DynamicQueryBuilder : queries
ReportJobService --> ReportScopeAuthorizer : checks
ScopedReport --> CsvArtifactWriter : writes CSV
ScopedReport --> PdfArtifactRenderer : renders PDF
3. Supported Report Catalog¶
The reporting framework orchestrates reports across all business modules:
1. Archive Reports (com.dw.ngms.cis.reporting.reports.archive):
- ArchiveProductionReport: Monthly throughput of archived packets and microfilms.
- ScanningProductionReport: Scan volumes and DPI compliance statistics.
- PSDTReport: Plan Safe document tracking audit.
2. Reservation Reports (com.dw.ngms.cis.reporting.reports.reservation):
- ReservationProductionReport: Parcels reserved, extended, and lapsed per province.
- ReservationTransferReport: Transferee changes and surveyor ownership shifts.
3. Lodgement & Examination Reports (com.dw.ngms.cis.reporting.reports.workflow):
- WorkflowProductionReport: Cadastral turn-around times per office against statutory SLAs.
- WorkflowUserProductionReport: Examiner daily productivity metrics.
4. User Management Reports (com.dw.ngms.cis.reporting.reports.usermanagement):
- UserSummaryReport: Active internal and external professional surveyors.
- UserHourlyLoginSummary: Security session concurrency and access audit.
4. Developer Guide: Adding a New Scoped Report¶
To add a new analytical report to the framework:
- Implement
BackgroundCsvReportin the appropriate subpackage:@Component("LODGEMENT_SUMMARY_REPORT") @RequiredArgsConstructor public class LodgementSummaryReport implements BackgroundCsvReport { private final DynamicQueryBuilder queryBuilder; @Override public String getReportId() { return "LODGEMENT_SUMMARY"; } @Override public void streamCsv(ReportFilters filters, UserScope scope, CsvArtifactWriter writer) { writer.writeHeader("Lodgement ID", "Province", "Status", "Lodged Date", "Surveyor"); queryBuilder.streamRows("SELECT * FROM VW_LODGEMENT_EXPORT", filters, scope, rs -> { writer.writeRow(rs.getString("ID"), rs.getString("PROVINCE"), rs.getString("STATUS"), rs.getDate("LODGED_DATE"), rs.getString("USER_NAME")); }); } } - Register the report ID in
ReportDefinitionRegistry. - The engine automatically handles scope authorization, job persistence, chunked streaming, and download rate-limiting.
CIS Notification Framework — Canonical Architecture & Developer Guide¶
[!IMPORTANT] This document is the authoritative specification and developer reference ("The Bible") for the CIS Notification Framework. It governs all notification channels (EMAIL, SMS, PDF), asynchronous event outbox queues, workflow process notifications, template resolution and caching, document artifact generation, distributed idempotency, audit ledgers, and developer extension rules across
cis-api.
1. Scope, Responsibilities and Package Ownership¶
Package Ownership¶
service.notification
NotificationService public facade
NotificationFrameworkGateway synchronous application gateway facade
model/ shared channel, request and failure-policy types
context/ context builder and shared/domain contributors
cart/, lodgement/, domain-specific context contributors
maintenance/, payment/,
reservation/, workflow/
render/ preparation, adapter registry and render results
template/ validation, cache invalidation and token checking
channel/
pdf/ PDF payload, rendering, preview and delivery adapter
email/ email payload, delivery and attachment naming
sms/ SMS payload and delivery
delivery/ generic retries, artifact handling and delivery results
artifact/ artifact processor contract and workflow document storage
asset/ image/barcode resolution, replacement factory and cache
audit/ durable delivery observations and JPA sink
idempotency/ event identity and renewable Redis ownership
queue/ durable queue worker, outbox handler and workflow notification dispatch
Framework tests mirror these responsibility packages. Cross-cutting safety tests remain beside the public facade; template composition tests remain in service.template. Packages do not add new Spring configuration: existing component scanning covers the subpackages, and the original class names, cache names, and persistence contracts are retained.
The framework composes database-managed templates and delivers PDF, EMAIL, and SMS through a shared strategy registry. All 28 active workflow notifications, the generic event listener, public email/SMS REST resources, lodgement/reservation action notifications, search sharing, expiry reminders, and task reminders enter this framework through either the durable queue (GenericEventEmailNotificationEnqueuer) or NotificationFrameworkGateway.
Core Hardening Invariants¶
- Fail-Fast Registries: The registries fail fast if two adapters or delivery strategies claim the same channel, preventing bean ordering from silently altering runtime behavior.
- Strict Boundary Validation: Render and delivery boundaries reject null commands, null contexts, empty channel selections, invalid retry counts, and rendered results whose map key does not match their declared channel.
- Payload Immutability: Prepared contexts and channel payloads remain strictly immutable once constructed.
- Identity Fallbacks: Legacy callers may omit template/workflow IDs when they provide an explicit notification event ID (
notification:<id>:<channel>); direct callers without an event ID retain the fallbackworkflowId:templateId:channel. - Deterministic Channel Sequencing:
NotificationServicesequences dependent channels;NotificationDeliveryOrchestratorowns channel lookup, ownership, retries, artifact processing, recovery, and audit. PDF delivery runs before email only when PDF is requested because the generated resource is an input to the email attachment. Domain contributors populate template variables, while transport strategies perform physical I/O.
2. Global Architecture & Component Topology¶
flowchart TD
subgraph Ingress["1. Ingress Layer (Trigger Sources)"]
WF["Workflow Engine (ProcessNotificationsVm)"]
EV["GenericEventListener (Domain Lifecycle Events)"]
SCH["Schedulers (TaskReminderService, Expiry Reminders)"]
REST["REST API Endpoints (EmailResource, SmsResource)"]
PREV["Interactive Letter Preview (Letter Previews)"]
end
subgraph EntryPorts["2. Ingress Gateways & Outbox"]
GW["NotificationFrameworkGateway (Sync Facade)"]
ENQ["GenericEventEmailNotificationEnqueuer (Outbox Enqueuer)"]
PREV_SVC["NotificationPdfPreviewService (Preview Engine)"]
DB_QUEUE[("NOTIFICATION Table (Outbox Queue)")]
Q_WORKER["NotificationQueueService (Claim & Poller)"]
GEN_SVC["GenericNotificationService (Dispatcher)"]
WF_FACTORY["ProcessNotificationFactory (28 Active Mappings)"]
end
subgraph PrepLayer["3. Preparation & Context Assembly Pipeline"]
NPS["NotificationPreparationService (Read-Only Tx)"]
NCB["NotificationContextBuilder"]
SHARED_CONTRIB["Shared Contributors (Dates, Metadata, Recipient Fallbacks)"]
DOMAIN_CONTRIB["Domain Contributors (Cart, Lodgement, Res, Maint, Workflow)"]
T_VAL["TemplateValidationService (XSS, URL & Token Guards)"]
T_DEF["TemplateDefinitionService (3-Tier Cache: ID, Name, Type)"]
RO["NotificationOrchestrator (Channel Adapter Coordinator)"]
end
subgraph ChannelAdapters["4. Channel Adapters & Renderers"]
EMAIL_ADAPT["EmailNotificationChannelAdapter"]
SMS_ADAPT["SmsNotificationChannelAdapter"]
PDF_ADAPT["PdfNotificationChannelAdapter"]
PREPARED["PreparedNotification (Immutable Context + Rendered Payloads)"]
end
subgraph DeliveryCore["5. Delivery Coordination & Safety Layer"]
NS["NotificationService (Public Delivery Facade)"]
DO["NotificationDeliveryOrchestrator"]
REDIS_LOCK[("Redis Distributed Renewable Lease")]
AUDIT_SINK["JpaNotificationAuditSink (REQUIRES_NEW Tx)"]
AUDIT_OUTBOX[("NOTIFICATION_DELIVERY_OUTBOX (Latest State)")]
AUDIT_HIST[("NOTIFICATION_DELIVERY_HISTORY (Audit Log)")]
end
subgraph ArtifactPipeline["6. Artifact Processing & Storage"]
PDF_DELIV["PdfNotificationDelivery (FlyingSaucer + Jsoup)"]
IMG_CACHE["NotificationImageCache & AssetReplacedElementFactory"]
CHAIN["ArtifactProcessorChain (@Order Directed Pipeline)"]
WF_DOC_PROC["WorkflowDocumentArtifactProcessor (Atomic Staging & Target Move)"]
STORAGE[("Shared File Storage (/workflow-docs)")]
WF_DOC_TABLE[("WORKFLOW_DOCUMENTS Table")]
end
subgraph TransportAdapters["7. Physical Transport Adapters"]
EMAIL_DELIV["EmailNotificationDelivery (JavaMail / SMTP)"]
SMS_DELIV["SmsNotificationDelivery (HTTP SMS Gateway)"]
end
%% Ingress wirings
EV --> ENQ --> DB_QUEUE
SCH --> ENQ
DB_QUEUE --> Q_WORKER --> GEN_SVC
GEN_SVC --> WF_FACTORY
GEN_SVC --> NPS
WF --> WF_FACTORY --> NPS
REST --> GW --> NPS
PREV --> PREV_SVC --> NPS
%% Prep layer wirings
NPS --> NCB
NCB --> SHARED_CONTRIB
NCB --> DOMAIN_CONTRIB
SHARED_CONTRIB & DOMAIN_CONTRIB --> T_VAL
T_VAL <--> T_DEF
NPS --> RO
RO --> EMAIL_ADAPT & SMS_ADAPT & PDF_ADAPT
EMAIL_ADAPT & SMS_ADAPT & PDF_ADAPT --> PREPARED
%% Delivery core wirings
PREPARED --> NS
NS --> DO
DO <--> REDIS_LOCK
DO --> AUDIT_SINK
AUDIT_SINK --> AUDIT_OUTBOX & AUDIT_HIST
%% Artifact & Transport wirings
DO -->|Channel: PDF| PDF_DELIV
PDF_DELIV <--> IMG_CACHE
PDF_DELIV --> CHAIN --> WF_DOC_PROC
WF_DOC_PROC --> STORAGE & WF_DOC_TABLE
WF_DOC_PROC -.->|Enrich Email with Reusable PDF Resource| NS
DO -->|Channel: EMAIL| EMAIL_DELIV
DO -->|Channel: SMS| SMS_DELIV
3. Entry Points & Invocation Routes¶
There are four runtime ingress paths into the framework:
GenericEventEmailNotificationEnqueuer: Writes an email event toNOTIFICATIONtable within the local business transaction. Its overloads provide a convenience API, not separate delivery paths.NotificationFrameworkGateway: The synchronous application facade. Exposes operations for email, email-with-attachments, SMS, composite PDF+email, and a generic channel-set operation.GenericNotificationService: The durable queue worker entry. Dispatches generic email events toGenericEventEmailNotificationHandlerand workflow events toProcessNotificationFactory.ProcessNotificationImplementations: The workflow adapter entry point. Handlers prepare context and invokeNotificationService;NotificationSchedulerandNotificationQueueServiceprovide the scheduled polling ingress around them.
The preview path (NotificationPdfPreviewService via ReservationAcknowledgementLetterService) reuses context building and PDF composition in a read-only transaction without acquiring leases, writing audit ledgers, or dispatching external transport I/O.
Open/Closed Review¶
The extension seams are open for new channels, delivery transports, renderers, context contributors, and artifact processors: implement the corresponding interface and register the Spring bean. Existing registries do not require modification.
There is one deliberate exception: NotificationService has PDF-specific sequencing because a generated PDF is an input to the EMAIL attachment payload. Adding an ordinary channel does not require changing it, but adding another artifact-dependent channel would require extending that coordinator. Treat this as a known design boundary, not as a defect.
4. End-to-End Sequence & Execution Flows¶
4.1 Complete Delivery Sequence¶
sequenceDiagram
autonumber
actor Caller as Ingress (Queue / Gateway / Workflow)
participant Prep as NotificationPreparationService
participant Ctx as Context Contributors
participant Orch as NotificationOrchestrator
participant NS as NotificationService
participant DO as NotificationDeliveryOrchestrator
participant Oracle as Oracle Outbox & History
participant Redis as Redis Renewable Lease
participant PDF as PDF Delivery & Artifact Chain
participant Trans as Transport (SMTP / SMS Gateway)
Caller->>Prep: templateId, workflowId, attributes, channels
Note over Prep: Read-Only Transaction Begins
Prep->>Ctx: Build shared, recipient and domain attributes
Ctx-->>Prep: Immutable NotificationContext
Prep->>Orch: Validate and render each requested channel
Orch-->>Prep: RenderedEmail / RenderedSms / RenderedPdf
Prep-->>Caller: PreparedNotification
Note over Prep: Read-Only Transaction Closes
Caller->>NS: notify(PreparedNotification)
Note over NS,Trans: External delivery executes outside database transaction
opt PDF Channel Requested
NS->>DO: deliver(PDF payload)
DO->>Oracle: Look up completed event/channel
alt Stored PDF Exists
Oracle-->>DO: Usable Resource and Document ID
DO->>Oracle: Record skip observation and atomic skip increment
else No Reusable PDF
DO->>Redis: Acquire token lease (5 min TTL)
DO->>Oracle: Commit PENDING (REQUIRES_NEW)
DO->>PDF: Generate and process artifact chain
PDF-->>DO: Resource and Document ID
DO->>Oracle: Commit DELIVERED and append history
DO->>Redis: Atomic compare-and-delete token
end
DO-->>NS: PDF Outcome
NS->>NS: Enrich RenderedEmail attachment list with PDF Resource
end
loop For Remaining Channels (EMAIL, SMS)
NS->>DO: deliver(Channel payload)
DO->>Oracle: Look up completed event/channel
alt Already Delivered
DO->>Oracle: Record skip observation
else Not Completed
DO->>Redis: Acquire token lease (5 min TTL)
DO->>Oracle: Commit PENDING
DO->>Trans: Send SMTP / HTTP SMS
Trans-->>DO: Accepted / OK
DO->>Oracle: Commit DELIVERED and append history
DO->>Redis: Atomic compare-and-delete token
end
DO-->>NS: Channel Outcome
end
NS-->>Caller: Aggregate Per-Channel Outcomes
4.2 Durable Outbox Two-Tier Polling Sequence¶
sequenceDiagram
autonumber
participant Sched as NotificationScheduler
participant Queue as NotificationQueueService
participant DB as NOTIFICATION Table
participant GenSvc as GenericNotificationService
participant NS as NotificationService
Sched->>Queue: pollPendingNotifications()
Queue->>DB: SELECT FOR UPDATE SKIP LOCKED (LIMIT 25, STATUS=0, NEXT_ATTEMPT <= NOW)
DB-->>Queue: Available Rows
loop For Each Row
Queue->>DB: UPDATE NOTIFICATION SET CLAIM_TOKEN=:uuid, CLAIM_UNTIL=:now+5m WHERE ID=:id
Queue->>GenSvc: handleJdbcNotification(notification)
GenSvc->>NS: Deliver via Framework
alt Delivery Succeeded
GenSvc->>DB: UPDATE NOTIFICATION SET STATUS=1, COMPLETION_DATED=:now WHERE CLAIM_TOKEN=:uuid
else Delivery Failed
GenSvc->>DB: Calculate Backoff: min(3600, 2^attempts * 15)
alt Attempts >= 8
GenSvc->>DB: UPDATE NOTIFICATION SET STATUS=2 (DEAD_LETTER), NEXT_ATTEMPT=null
else Attempts < 8
GenSvc->>DB: UPDATE NOTIFICATION SET STATUS=0, NEXT_ATTEMPT=:backoff, DELIVERY_ATTEMPTS=DELIVERY_ATTEMPTS+1
end
end
end
5. Complete Inventory of Migrated Process Notifications¶
All 28 active workflow process notifications have been migrated to dedicated NotificationContextContributor implementations and NotificationService execution:
| Template ID | Enum (ProcessTemplateType) |
Process Notification Class | Dedicated Context Contributor | Channels | Generated Artifacts / Attachments |
|---|---|---|---|---|---|
| 13 | INFORMATION_REQUEST |
InformationRequestNotification |
InformationRequestContextContributor |
None | |
| 15 | INVOICE |
InvoiceNotification |
InvoiceContextContributor |
Invoice PDF | |
| 16 | PAYMENT_CONFIRMATION |
PaymentVerificationNotification |
PaymentVerificationContextContributor |
None | |
| 17 | DISPATCH |
DispatchNotification |
DispatchContextContributor |
None | |
| 18 | INFORMATION_REJECT |
InformationRequestRejection |
InformationRequestRejectionContextContributor |
None | |
| 19 | QUERY_OUTCOME |
QueryOutcomeNotification |
QueryOutcomeContextContributor |
None | |
| 20 | QUERY |
QueryNotification |
QueryNotificationContextContributor |
None | |
| 107 | NOTIFY_MANAGER |
NotifyManagerLog |
NotifyManagerContextContributor |
None | |
| 170 | AUTO_DISPATCH |
AutoDispatchNotification |
AutoDispatchContextContributor |
None | |
| 247 | NOTIFY_MANAGER_OUTCOME |
NotifyManagerOutcomeNotification |
NotifyManagerOutcomeContextContributor |
None | |
| 268 | PAYMENT_UPLOAD |
PaymentUploadNotification |
PaymentUploadContextContributor |
None | |
| 307 | RES_NEW_REQUEST_NOTIFICATION |
ReservationNewRequestNotification |
ReservationNewRequestContextContributor |
Reservation Request Letter PDF | |
| 308 | RES_REQUEST_REJECTION_LETTER |
ReservationRequestRejectionNotification |
ReservationRejectionContextContributor |
Reservation Rejection Letter PDF | |
| 327 | RES_EXPIRY_NOTIFICATION |
ReservationExpiryEmailNotification |
Enqueued Outbox Job | Expiry Warning Notice | |
| 328 | RES_ACKNOWLEDGEMENT_LETTER |
ReservationAcknowledgementLetterNotification |
ReservationAcknowledgementContextContributor |
PDF, EMAIL | Reservation Acknowledgement Letter PDF |
| 348 | RES_NEW_REQUEST_RESUBMISSION |
ReservationRequestResubmission |
ReservationResubmissionContextContributor |
Reservation Resubmission Letter PDF | |
| 367 | LODGEMENT_NEW_REQUEST_NOTIFICATION |
LodgementNewRequestNotification |
LodgementNewRequestContextContributor |
Lodgement Request Notice PDF | |
| 368 | LODGEMENT_LETTER |
LodgementAcknowledgementNotification |
LodgementAcknowledgementContextContributor |
Lodgement Acknowledgement Letter PDF | |
| 369 | LODGEMENT_REQ_REJECTION_LETTER |
LodgementRequestRejectNotification |
LodgementRejectionContextContributor |
Lodgement Rejection Letter PDF | |
| 370 | LODGEMENT_REQ_UPDATE_AMEND |
LodgementRequestAmendNotification |
LodgementAmendContextContributor |
Lodgement Amendment Letter PDF | |
| 388 | RES_TRANSFER_APPROVAL_OUTCOME |
ReservationTransferApprovalOutcome |
ReservationTransferApprovalContextContributor |
Reservation Transfer Outcome Letter PDF | |
| 487 | RELODGEMENT_NEW_REQUEST_NOTIFICATION |
RelodgementNewRequestNotification |
RelodgementNewRequestContextContributor |
Relodgement Request Notice PDF | |
| 488 | RELODGE_LODGEMENT_LETTER |
RelodgementAcknowledgementNotification |
RelodgementAcknowledgementContextContributor |
Relodgement Letter PDF | |
| 489 | RELODGE_REQUEST_AMMEND |
RelodgeRequestAmmendNotification |
RelodgeAmendContextContributor |
Relodgement Amendment Letter PDF | |
| 490 | REQUEST_REJECTION_LETTER |
RelodgeRequestRejectNotification |
RelodgeRejectionContextContributor |
Relodgement Rejection Letter PDF | |
| 687 | MAINTENANCE_NEW_REQUEST_NOTIFICATION |
MaintenanceNewRequestNotification |
MaintenanceNewRequestContextContributor |
Maintenance Request Notice | |
| 688 | MAINTENANCE_OUTCOME_LETTER |
MaintenanceOutcomeLetterNotification |
MaintenanceOutcomeContextContributor |
Maintenance Excision Outcome Letter PDF | |
| 707 | PUBLIC_PLACE_CLOSURE_LETTER |
MaintenancePPCOutcomeLetterNotification |
MaintenancePPCOutcomeContextContributor |
Public Place Closure Letter PDF | |
| 727 | STREET_RENAME_LETTER |
MaintenanceStreetRenameOutcomeLetterNotification |
MaintenanceStreetRenameOutcomeContextContributor |
Street Renaming Outcome Letter PDF | |
| 748 | MAINTENANCE_GENERIC_COMPLETION_LETTER |
MaintenanceGenericCompletionLetterNotification |
MaintenanceGenericCompletionContextContributor |
Generic Completion Letter PDF |
6. Identity, Recipients and Context Assembly¶
The scheduler's NOTIFICATION.ID is mapped to the internal, JSON-ignored ProcessNotificationsVm.notificationId. It enters the context and produces channel keys:
notification:<id>:<channel>
Two events on the same workflow/template no longer suppress one another. Direct callers without an event ID retain the legacy workflowId:templateId:channel fallback and must supply an event ID for distinct deliveries. A retry uses the same event ID; an intentional resend creates a new notification event.
The context makes a defensive, unmodifiable map copy that permits null optional values:
* CommonPdfContextContributor supplies formatted dates and timestamps.
* TemplateMetadataContextContributor supplies template names and identifiers.
* ArtifactMetadataContextContributor supplies artifactWorkflowId consumed by the workflow artifact processor.
* CommonRecipientContextContributor supplies recipient aliases (to, cc, bcc) with delivery fallbacks.
* Domain-specific contributors add applicant details, request steps, reference numbers, and custom metadata.
Recipient selection remains the applicant's primary email/mobile. It does not switch automatically to NOTIFICATION.USER_ID or a draft alternate email.
7. Template Engine, Fragment Composition and Caching¶
NotificationPreparationService encloses context loading and HTML rendering in one read transaction. PdfNotificationChannelAdapter composes the complete HTML there; delivery receives a RenderedPdf marked as composed, avoiding later lazy entity traversal or a second Thymeleaf pass. NotificationService enriches the already rendered email with attachments without re-rendering it. Shared email formatting uses cis-emailer/email.html.
7.1 Dynamic Fragment Composition¶
PDF composition replaces common header/footer markers with database fragments:
* Missing optional fragments remain empty; processing errors propagate.
* Styles are collected into the document <head>, then Jsoup performs one XHTML conversion.
* Named media use a shared Redis byte cache; only cold/missing names enter a batched repository lookup and disk read.
* Image payloads are Base64 encoded for the Redis JSON serializer and decoded into fresh arrays for callers.
* LogoService add/update/delete rotates a shared generation after transaction completion, preventing in-flight old reads from repopulating the current namespace. Cache defaults retain the 30-minute TTL.
* NotificationAssetReplacedElementFactory consumes the image map and delegates barcode generation to the framework resolver.
flowchart LR
B[Resolved body snapshot] --> C[Compose only referenced cached fragments]
C --> T[Thymeleaf processing]
T --> J[Single Jsoup normalization: styles to head and XHTML output]
J --> F[Flying Saucer parses XHTML]
F --> A[Discover assets from the same W3C document]
A --> P[PDF layout and output]
HtmlTextGenerationService performs no Jsoup parse. TemplateUtils.convertToXhtml owns the sole Jsoup normalization/serialization pass; the replacement factory receives ITextRenderer.getDocument() and performs no HTML string parsing.
PDF file output uses a 64 KiB BufferedOutputStream to coalesce small renderer writes. Parent directories are created before opening the output; the stream is closed before file-size validation, so delayed flush/close failures follow the incomplete-file cleanup path.
7.2 Template Invalidation¶
TemplateService.saveTemplate persists and invokes TemplateInvalidationService. Invalidation defers until after commit when called inside a surrounding transaction. Direct operator SQL changes require explicit cache eviction or cache expiry.
Name-only legacy PDF fragment lookups use TemplateDefinitionService, through the template-definitions-by-name cache. All three lookup indexes (by-id, by-name, by-item-id-module) are invalidated together. The PDF adapter supplies its already-resolved body to the composer, which fetches only the common fragments whose markers actually occur. A portrait notification never fetches the landscape footer or reloads its body by name.
8. Ownership, Audit, and Recovery¶
stateDiagram-v2
[*] --> Lookup
Lookup --> Recovered: Durable completion and usable PDF if required
Recovered --> [*]: Preserve result and append skip observation
Lookup --> Claim: No completed outcome
Claim --> Deferred: Another worker owns lease
Deferred --> [*]: Queue retries later
Claim --> PENDING: Acquire token and recheck completion
PENDING --> DELIVERED: Transport and processors succeed
PENDING --> FAILED: Attempts exhausted
DELIVERED --> Released: Commit ledger and history
FAILED --> Released: Commit ledger and history
Released --> [*]: Compare-and-delete token
Lookup --> BLOCKED: Required PDF unavailable and email not already delivered
BLOCKED --> Released: Persist blocked outcome under ownership
Redis is a 5-minute renewable worker lease, not the durable success store. UUID tokens are checked during delivery, renewed every minute, and released using atomic Lua compare-and-delete. An expired worker cannot delete a newer worker's token. Lost ownership produces an uncertain failure and prevents that worker from finalizing the channel ledger. Completed outcomes are checked again after ownership acquisition.
JpaNotificationAuditSink commits independently using REQUIRES_NEW: PENDING before I/O, final state after transport and artifact processing. Final audit precedes lease release. The latest-state ledger (NOTIFICATION_DELIVERY_OUTBOX) uses optimistic versioning; skip counts use atomic increments. The same transaction appends a row to NOTIFICATION_DELIVERY_HISTORY, preserving retry and duplicate observations. Blocked dependency handling first recovers an already-delivered email instead of overwriting it. PDF recovery returns its stored path and document ID; a missing file permits regeneration.
SMTP is synchronous for framework notifications and propagates attachment/transport errors. Blank SMS templates are omitted. Nonblank SMS requires SMS_SUCCESS_RESPONSE_PATTERN, a full-match regex from the provider's accepted-response contract. Gateway credentials and message text are not explicitly logged, and RestTemplate debug URL logging is disabled. Gateway error URLs are sanitized and SMS query values are encoded. SMTP connect/read/write timeouts are exposed in environment files. External transport remains at-least-once: a crash after SMTP/provider acceptance and before Oracle outcome commit may produce a duplicate retry.
9. Crash Recovery & Staging Verification¶
Crash recovery has two independent ownership layers. The durable queue owns the NOTIFICATION row with CLAIM_TOKEN and CLAIM_UNTIL; channel delivery owns a Redis lease keyed by the event and channel. A worker must hold both ownerships while processing. If the JVM dies, the database claim and Redis lease expire independently and the next worker can retry the event. A completed Oracle channel outcome always wins over an expired lease and is reused instead of sending again.
sequenceDiagram
participant Q as Queue worker
participant N as NOTIFICATION row
participant X as Redis lease
participant O as Oracle delivery ledger
participant T as External transport
Q->>N: Claim row with token and expiry
Q->>X: Acquire event/channel lease
Q->>O: Record PENDING
Q->>T: Generate PDF or send email/SMS
alt Worker completes normally
T-->>Q: Success
Q->>O: Record DELIVERED and history
Q->>X: Compare-and-delete owned lease
Q->>N: Mark queue row complete
else Worker crashes before finalization
Note over N,X: Claim and lease expire independently
Q-->>N: No completion update
Q-->>X: No release - TTL expires
Q->>N: Next poll reclaims row
Q->>O: Recheck completed outcome
alt Completed outcome exists
O-->>Q: Reuse stored result/artifact
else No completed outcome
Q->>X: Acquire a new lease
Q->>O: Retry delivery
end
end
PDF-Specific Crash Handling¶
WorkflowDocumentArtifactProcessor makes PDF persistence retry-safe:
1. Derives a stable NOTIFICATION_KEY for the PDF channel.
2. Reuses the existing WORKFLOW_DOCUMENTS row when the event is retried.
3. Writes a .target checkpoint before replacing the target file.
4. Copies to a .part staging file and atomically moves it into place.
5. After the document transaction commits, the checkpoint is removed.
6. On a retry, an orphan checkpoint is reconciled: a PDF whose document row never committed is removed, while unrelated files are untouched.
Staging Crash Test Matrix¶
| Scenario | Inject Failure | Expected Recovery |
|---|---|---|
| Before PDF delivery | Kill worker after queue claim | Claim expires; same event is retried and completes |
| During PDF generation | Kill process before final audit | Staging/checkpoint files are reconciled; no duplicate document created |
| After workflow-document commit | Kill before channel audit | Existing document is reused by notification key |
| After SMTP acceptance | Kill before final audit | Retry may send a duplicate; history records both observations |
| Redis lease loss | Stop/block Redis during delivery | Worker cannot finalize; next worker retries after lease expiry |
| JVM restart during batch | Stop application while several rows run | Claimed rows become eligible again; no permanent stuck claim |
Staging Verification Queries¶
SELECT ID, STATUS, DELIVERY_ATTEMPTS, CLAIM_TOKEN, CLAIM_UNTIL, NEXT_ATTEMPT
FROM NOTIFICATION
WHERE ID = :notification_id;
SELECT IDENTITY_KEY, STATUS, ATTEMPTS, ERROR_MESSAGE, RECORDED_AT
FROM NOTIFICATION_DELIVERY_HISTORY
WHERE IDENTITY_KEY LIKE '%' || :notification_id || '%'
ORDER BY ID;
SELECT IDEMPOTENCY_KEY, STATUS, ATTEMPTS, ARTIFACT_PATH, DOCUMENT_ID
FROM NOTIFICATION_DELIVERY_OUTBOX
WHERE IDEMPOTENCY_KEY LIKE '%' || :notification_id || '%';
Also inspect the workflow storage directory for leftover .part files, .target checkpoint files, and duplicate {documentId}.pdf files after each injected failure.
Synchronous Gateway Boundary¶
Queue-backed workflow and generic-event notifications recover automatically. A direct NotificationFrameworkGateway call has no queue row to resume if the JVM dies during delivery; the caller must retry it, or the operation must first enqueue a durable notification event.
10. Queue Retries and Operational Recovery¶
Email PDF attachment names use the template's configured file prefix (or template name), followed by the reference number: Reservation-acknowledgement-RES0023KZN.pdf. Missing references fall back to the workflow/event/template identifier. Names are sanitized and bounded. A resource decorator changes only the MIME filename; workflow storage remains {documentId}.pdf, so document links and recovered artifacts retain their existing paths.
NotificationQueueService selects at most 25 eligible IDs, atomically claims each row with a UUID and expiry, renews claims, and updates outcomes only when its token still matches. Polls use fixed delay; expired scheduler locks do not bypass row ownership. Failed rows are delayed by:
The eighth failed attempt moves the row to STATUS = 2 (Dead Letter Queue). Status 0 is pending; status 1 is complete; status 2 is dead letter.
Operational Dead-Letter Runbook¶
After correcting the root failure, an operator can reset a dead-letter row's STATUS to 0, DELIVERY_ATTEMPTS to 0, and NEXT_ATTEMPT to null, only when it has no active claim:
UPDATE NOTIFICATION
SET STATUS = 0,
DELIVERY_ATTEMPTS = 0,
NEXT_ATTEMPT = SYSTIMESTAMP,
CLAIM_TOKEN = NULL,
CLAIM_UNTIL = NULL
WHERE ID = :notification_id
AND STATUS = 2
AND (CLAIM_UNTIL IS NULL OR CLAIM_UNTIL < SYSTIMESTAMP);
COMMIT;
Keep its event ID to resume unfinished channels. Do not delete confirmed delivery rows or flush Redis to request a new message; create a new notification event for an intentional resend.
Database Concurrency Safeguards¶
Virtual threads are enabled for the application, but database-bound event handling is bounded. AsynchronousSpringEventsConfig uses a dedicated bounded ThreadPoolTaskExecutor with configurable core/max/queue values and CallerRunsPolicy; it does not use an unbounded SimpleAsyncTaskExecutor. The default event limits are 1 core thread, 3 maximum threads, and a queue of 100. These limits must remain below the combined Oracle connection capacity reserved for the service. Hikari connection wait timeouts are environment-configurable; the development profile uses the same 30-second default as UAT and production rather than an excessive override.
11. Consolidated Schema and Environment Rollout¶
All notification DDL is consolidated in V3__notification_delivery_outbox.sql at the user's explicit request to reset earlier interim Flyway versions. V4/V5 source files were removed. The script creates/extends the ledger, history, workflow document identity, and queue ownership/retry fields. Existing rows and sequence values are preserved on reapplication.
This changes the checksum of previously applied V3. Stop notification workers and complete the explicitly agreed notification-history reset before normal Flyway startup; if V4/V5 were applied from an interim checkout, their history must be reconciled as well. Removing history is an operator action, not performed by this implementation. Do not change unrelated migration history or drop notification data merely to reapply the consolidated script.
Existing legacy workflow/template ledger keys cannot be mapped reliably to event IDs. Before requeuing pre-upgrade notifications, reconcile their already-sent outcomes to avoid resending messages after the event-key transition. Configure the provider acknowledgement regex before enabling framework SMS and ensure all nodes share workflow storage.
12. Verification & Post-Implementation Review¶
The regression suite covers recovered PDFs, failed artifact processing, unresolved ownership, distinct event identity, immutable optional null context, preserving delivered email on a blocked dependency, final audit before release, provider acknowledgement rejection, audit skip preservation, missing artifact recovery, channel selection, and template lookup.
The combined notification/event regression run passed 125 focused tests with zero failures and zero skips. Tests cover: * Queue success/backoff/contention. * Prepared attachment enrichment without re-rendering. * Event-document reuse and crash-file reconciliation without removing unrelated files. * Generic event listener transactions and in-app side effects. * Resource routing and search-share guards. * Lodgement and reservation action routing. * Expiry reminders and task reminders.
Live isolated checks also verified Redis stale-token rejection/renewal/release and Oracle consolidated V3 reapplication with delivery-row preservation. The disposable Oracle schema was removed. SGUSER schema/history was not changed, and no external email or SMS was dispatched during tests.
13. Known Bypasses and Stale Boundaries¶
The legacy EmailServiceHandler and SmsServiceHandler call sites in cis-api have been removed from the migrated notification paths. One workflow-module hook remains outside this module's framework boundary: WorkflowProcessingService calls emailHandlerService.triggerTaskEmail(...). It is intentionally not counted as a CIS API framework entry point and requires a cis-workflow change to migrate.
PDF generation is not globally unified yet. Non-notification reports and previews still call PdfGeneratorService directly (such as examination dockets and administrative reports), while notification PDF delivery uses the channel adapter and generic delivery orchestrator. The reservation acknowledgement preview now uses NotificationPdfPreviewService, which reuses framework context/template composition without creating a durable delivery. The remaining report and examination paths are valid document-generation paths today, but they do not receive queue, idempotency, durable delivery audit, or workflow-artifact semantics. Do not describe the framework as owning every PDF in the application until those contracts are deliberately migrated.
Within the framework itself, PdfNotificationDelivery remains the concrete PdfDocumentDelivery port implementation and PdfNotificationDeliveryAdapter is its generic-delivery bridge; neither is dead code.
14. Extending the Framework¶
Follow these six canonical rules when extending the notification system:
- Add an ordered domain context contributor and populate the live template variables.
- Carry the persisted notification ID into
NotificationPreparationService.prepare. - Pass the prepared payload to
NotificationService; select the supported channels. - Propagate failed results so the durable queue can back off or dead-letter the event.
- Add ordered artifact processors only for extra artifact responsibilities.
- Test event reuse, distinct events, missing optional data, transport failure, and artifact recovery.
[!CAUTION] Anti-Pattern Warning: Do NOT duplicate PDF generation, email wrapping, attachment sequencing, leases, or audit logic inside domain notification classes. The obsolete
NotificationChannelRendererand logging-only sink were removed; the adapter registry and persistent sink are the sole maintained paths.
Developer Recipes & Code Examples¶
Recipe A: Implementing a Domain Context Contributor¶
package com.dw.ngms.cis.service.notification.context.custom;
import com.dw.ngms.cis.service.notification.context.NotificationContextContributor;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;
import java.util.Map;
@Component
@Order(500)
public class CustomProcessContextContributor implements NotificationContextContributor {
@Override
public boolean supports(Long templateId, Long workflowId, Map<String, ?> attributes) {
return Long.valueOf(999L).equals(templateId);
}
@Override
public void contribute(Long templateId, Long workflowId, Map<String, ?> attributes, Map<String, Object> target) {
target.put("referenceNumber", attributes.get("referenceNo"));
target.put("statusDescription", "Approved");
// Add domain-specific template variables here
}
}
Recipe B: Triggering via Synchronous Gateway¶
@Service
@AllArgsConstructor
public class CustomAlertService {
private final NotificationFrameworkGateway notificationGateway;
public void dispatchAlert(Long workflowId, String userEmail, String referenceNumber) {
Map<String, Object> attributes = Map.of(
"referenceNo", referenceNumber,
"notificationId", UUID.randomUUID().toString()
);
// Automatically validates, prepares, acquires Redis lease, audits, and delivers
notificationGateway.sendEmail(999L, workflowId, userEmail, null, null, attributes);
}
}
Recipe C: Triggering via Asynchronous Durable Outbox¶
@Component
@AllArgsConstructor
public class CustomEventListener {
private final GenericEventEmailNotificationEnqueuer genericEmailEnqueuer;
@EventListener(condition = "#event.eventType.name() == 'CUSTOM_EVENT'")
public void onCustomEvent(GenericNotificationEvent<User> event) {
User user = event.getContent();
// Enqueues into NOTIFICATION table within the current database transaction
genericEmailEnqueuer.enqueue(
event.getEventType(),
999L,
user.getUserId(),
user.getEmail(),
null,
Map.of("firstname", user.getFirstName(), "surname", user.getSurname())
);
}
}
Recipe D: Adding a Custom Artifact Processor¶
@Component
@Order(200) // Runs after standard workflow document processor
public class CustomArchivalArtifactProcessor implements ArtifactProcessor {
@Override
public boolean supports(ArtifactContext context) {
return context.getChannel() == NotificationChannel.PDF;
}
@Override
public Resource process(Resource inputArtifact, ArtifactContext context) throws Exception {
// Perform additional operations (e.g. upload to external secure storage or add cryptographic watermark)
return inputArtifact;
}
}
Security
Security & Identity Architecture¶
Security across the CIS platform is built on modern zero-trust and defense-in-depth principles.
Security Domains¶
graph LR
subgraph Ingress Layer
A[Browser] -->|Encrypted Cookie| B[BFF Proxy :8080]
end
subgraph Identity & Trust
B -->|OAuth2 / PKCE| C[cis-auth :8085]
C --> D[(Oracle Key Vault :1521)]
C --> E[(OpenLDAP :10389)]
C --> F[(Redis Revocation Store :6379)]
end
subgraph Internal Business Services
B -->|JWT Bearer Token| G[cis-api :8089]
B -->|JWT Bearer Token| H[cis-workflow :8090]
end
Detailed Security Documentation¶
- Authentication Reference: Exhaustive technical specification covering token lifecycles, Passkeys (WebAuthn), RSA dynamic key rotation, and session management.
- Security Remediation Guide: Details vulnerability remediations implemented in
cis-authandcis-bff, including CSRF hardening, rate limiting, and credential sanitization. - Security Audit Evidence: Findings and penetration test validation evidence.
CIS security guide: authentication, authorization and BFF¶
Source-audited implementation reference, 2026-10-19. This describes current source, compatibility paths and operating limits; it does not assert every environment has deployed the same revision. Current build: Spring Boot 4.1.2, Spring Security/MVC 7, Java 25. The BFF is a servlet gateway using filters and Java HttpClient, not a reactive Spring Cloud Gateway application.
This is the single maintained security reference for cis-auth and cis-bff. It includes browser pages, all supported grant flows, API access, configuration, deployment, error handling and a source inventory. The older separate security notes have been consolidated here; historical audit observations are distinguished from current behavior.
Contents¶
- 1. Responsibilities and boundaries
- 2. Choose the correct flow
- 3. Authorization-code flow with PKCE and BFF callback
- 4. Password grant: direct API and compatibility BFF login
- 5. Client-credentials flow: services and jobs
- 6. Shared identity verification and account policy
- 7. API access: dual-mode BFF
- 8. Refresh-token flow
- 9. Logout and revocation flows
- 10. Administrator impersonation flow
- 11. Signing-key rotation and JWT validation
- 12. Client administration and complete token settings
- 13. Endpoint reference
- 14. Security filters and persisted state
- 15. Cookies, CORS and frontend behavior
- 16. Errors, resilience, health, metrics and audit
- 17. Migration and troubleshooting
- 18. Validation strength and open operating contracts
- 19. Environment configuration and rollout
- 20. Browser pages and annotated walkthrough
- 21. Security controls and audit record
- 22. Complete request lifecycle and fish diagram
- 23. Component and configuration inventory
- 24. External-user passkeys: complete flow and rollout
For the end-to-end technical walkthrough, start with the request lifecycle.
For first-time reading, follow sections 1-3, then the page walkthrough in section 20. For implementation work, use the endpoint map and the inventory in sections 13 and 23. For operations, use sections 17-19. All example secrets and tokens are placeholders.
1. Responsibilities and boundaries¶
| Component | Responsibility |
|---|---|
| Angular portals | Navigate to login, display application, call BFF with credentials and CSRF |
| cis-auth | Verify identity/account policy; issue tokens; manage clients, keys, revocation and impersonation |
| cis-bff | Own browser callback, store tokens in Redis, manage cookies/session CSRF, proxy APIs and pass bearer tokens through |
| cis-api / cis-workflow | Validate JWTs and enforce business endpoint permissions |
| Oracle | UAM users/roles/history/policy, OAuth clients/authorizations/consents, keys, audit and rotation state |
| Redis | BFF sessions/transactions/leases/rate counters; revocation/indexes and event channel |
A user password, OAuth client secret, OAuth token and BFF session cookie are different credentials. A client secret identifies a confidential application, not a person. The cookie references server-held token state; it is not the JWT. RSA private-key encryption does not imply encryption of every OAuth token stored in Oracle or Redis.
| Service | Host development address | Container back channel |
|---|---|---|
| BFF | http://localhost:8080 | cis-bff:8080 |
| Auth | http://localhost:8085 | cis-auth:8085 in local Compose |
| API | http://localhost:8089 | cis-api:8089 |
| Workflow | http://localhost:8090 | cis-workflow:8090 |
| Internal Angular | http://localhost:4201 | Browser destination |
| External Angular | http://localhost:4200 | Browser destination |
Browser-facing URLs and private container endpoints are intentionally different. UAT BFF callback: https://bff.cis.accesscam.org/bff/auth/callback. Production: https://bff.cis.accesscam.org/bff/auth/callback. Portal destinations are separate settings; use different UAT frontend hosts there if your deployment requires them.
2. Choose the correct flow¶
| Requirement | Flow | Caller receives |
|---|---|---|
| Internal/external Angular | Authorization Code + PKCE through confidential BFF | Session cookie and sanitized profile |
| External browser user with an enrolled passkey | Optional WebAuthn login within the same authorization-code flow; see section 24 | Same BFF session cookie and profile |
| Existing integration submits user credentials | Compatibility password grant, directly or through BFF | Direct auth: tokens; BFF: cookies/profile |
| Service/job without a human | Client credentials | Application access token |
| REST caller already has a token | Bearer API access, not a grant | Resource response; no BFF session |
| Continue a browser session | BFF-managed refresh | Renewed server-held tokens |
New browser work should use authorization code. Password grant remains available for compatibility. Client credentials must not be used to impersonate a human or put an application secret in Angular.
3. Authorization-code flow with PKCE and BFF callback¶
Registration and actors¶
Angular is the frontend; BFF is the confidential OAuth client; cis-auth is the authorization server. Both configured browser clients require authorization_code, PKCE and the exact BFF callback registration.
| Portal | Configured client | Persisted client realm |
|---|---|---|
| Internal | cis-bff-internal-client | INTERNAL |
| External | cis-bff-external-client | EXTERNAL |
IDs/secrets come from CIS_BFF_INTERNAL_CLIENT_ID / CIS_BFF_INTERNAL_SECRET and CIS_BFF_EXTERNAL_CLIENT_ID / CIS_BFF_EXTERNAL_SECRET. Secrets remain server-side. CIS_BFF_CALLBACK_URI is the OAuth redirect. CIS_BFF_INTERNAL_FRONTEND_URL and CIS_BFF_EXTERNAL_FRONTEND_URL are where users land afterward. CORS permission does not register an OAuth callback.
Each step¶
- Angular navigates the browser to GET /bff/auth/authorize with clientId and optional rememberMe. Omitting clientId selects the configured confidential external client.
- BffAuthenticationFacade accepts only configured internal/external confidential IDs, loads authenticated metadata, checks the expected realm and confirms the BFF callback is registered. Caller-supplied redirectUri is rejected at this entry point.
- BFF generates random state/verifier, computes the S256 challenge, and stores a five-minute BffAuthorizationTransaction in Redis. It contains client, verifier, callback, expiry, remember choice and server-selected portal destination. The HttpOnly CIS_OAUTH_STATE cookie contains state, not the verifier or client secret.
- BFF redirects to browser-facing auth /oauth2/authorize with response_type=code, client ID, callback, scopes, state and PKCE challenge. The flow has now started.
- Auth validates registration/realm and creates a browser-bound login challenge. The login page renders internal staff/LDAP or external CIS account presentation from the registered realm, not from the frontend hostname or an arbitrary form field.
- Browser POSTs credentials to auth /login with its challenge and Spring CSRF token. BrowserAuthenticationProvider invokes shared realm strategies/account policies, rejects a principal from another realm and uses generic browser failure text.
- After successful login, BrowserLoginHandlers returns a no-store HTML continuation
page (HTTP 200). A same-origin external script navigates to the saved authorization
URL; a Continue link supports browsers with JavaScript disabled. This ends the form
POST before cross-origin OAuth redirects, preserving CSP
form-action 'self'. The browser resumes the saved /oauth2/authorize request. Seeing this URL is expected: auth must issue a code before redirecting. Auth's browser HttpSession is distinct from the later BFF Redis session. - Auth redirects the browser to BFF /bff/auth/callback?code=...&state=....
- BFF compares state to the browser cookie before consuming the Redis transaction. It rejects expired, missing, replayed or configuration-mismatched transactions. The OAuth-state cookie is cleared after consuming a matching transaction.
- BFF POSTs the code, exact callback and server-held verifier to auth /oauth2/token, authenticating with its confidential client credentials. Auth validates the code, redirect, client and PKCE; token customization rechecks current user policy/roles.
- BFF stores access/refresh tokens, identity and CSRF state in Redis, sets session and CSRF cookies, then redirects to the stored configured portal destination. Code/state/access/refresh tokens are not appended to the Angular return URL.
- Angular calls GET /bff/auth/me with credentials, reads the sanitized profile and exposed X-XSRF-TOKEN response header, and sends that header on mutations.
sequenceDiagram
participant Browser as Angular / browser
participant BFF as BFF 8080
participant Redis
participant Auth as Auth 8085
participant Identity as LDAP and Oracle / Oracle
Browser->>BFF: GET /bff/auth/authorize
BFF->>Auth: Protected client metadata lookup
BFF->>Redis: Save state, verifier and portal destination
BFF-->>Browser: State cookie and auth authorization redirect
Browser->>Auth: Authorization request, then login form
Auth->>Identity: Verify identity, realm and account policy
Auth-->>Browser: 200 continuation page after successful POST
Browser->>Auth: Separate navigation to saved authorization request
Auth-->>Browser: Redirect with code to BFF callback
Browser->>BFF: GET /bff/auth/callback with code and state
BFF->>Redis: Validate and consume browser-bound transaction
BFF->>Auth: Code, verifier and confidential authentication
Auth-->>BFF: OAuth tokens
BFF->>Redis: Persist BFF session
BFF-->>Browser: Session cookies and configured portal redirect
Browser->>BFF: GET /bff/auth/me with credentials
BFF-->>Browser: Profile and CSRF response header
Local browser entry points:
- http://localhost:8080/bff/auth/authorize?clientId=cis-bff-internal-client
- http://localhost:8080/bff/auth/authorize?clientId=cis-bff-external-client&rememberMe=true
Use top-level browser navigation. REST Client and browser cookie stores are different. Angular no longer receives the OAuth callback or relays a code in the current flow.
State, failure and browser concurrency¶
Unknown client/caller redirect override is 400; a configured client with an incorrect registered callback/realm produces a service-unavailable configuration error. Invalid browser state cannot consume another transaction. A consumed transaction is single-use, even if provider authorization or code exchange fails; restart sign-in afterward.
One CIS_OAUTH_STATE cookie is used per BFF hostname: parallel starts can replace it. One CIS_SESSION cookie is used per BFF hostname: separate portal clients do not imply independent simultaneous internal/external identities in one browser cookie jar.
4. Password grant: direct API and compatibility BFF login¶
sequenceDiagram
participant Caller as Existing caller
participant BFF
participant Auth
participant Identity as LDAP or Oracle identity
participant Store as Oracle and Redis
Caller->>BFF: POST /bff/auth/login with user credentials and realm
BFF->>Auth: Password grant with server-held client authentication
Auth->>Identity: Verify selected realm and account policies
Identity-->>Auth: Current user and authorities
Auth->>Store: Persist authorization and revocation index
Auth-->>BFF: Access and refresh tokens
BFF->>Store: Store browser session in Redis
BFF-->>Caller: Session cookies, profile and CSRF header
Note over Caller,Auth: Direct integrations can call auth instead and receive tokens directly
Direct password grant¶
This compatibility flow uses PasswordGrantAuthenticationConverter, PasswordGrantAuthenticationProvider and RealmStrategyRegistry in cis-auth.
- A confidential integration POSTs form data to auth /oauth2/token, authenticating its client and providing grant_type=password, username/password, scopes and optionally realm. It is a user grant, not client_credentials.
- The provider validates the authenticated client's allowed grant/scopes and invokes the realm registry. For this legacy path, an explicit requested realm wins, then internal/external client-name hints, then stored user type; otherwise external.
- The selected strategy verifies credentials, Oracle user/realm consistency, account policies and role names. Browser realm selection instead comes from client settings.
- Auth generates/signs tokens, persists authorization state and registers user JTIs in Redis. The direct integration receives OAuth JSON and must protect its tokens. No BFF browser session is created by calling auth directly.
POST http://localhost:8085/oauth2/token
Authorization: Basic <base64(client-id:client-secret)>
Content-Type: application/x-www-form-urlencoded
grant_type=password&username=<user>&password=<password>&realm=EXTERNAL&scope=read
The example has placeholders only. Use HTTPS outside loopback. TLS protects transport; the receiving application still sees credentials, so request bodies must not be logged.
BFF password-login compatibility¶
- Existing callers POST JSON username/password/realm to /bff/auth/login.
- BFF chooses its configured internal credentials for INTERNAL, otherwise external, and invokes the auth password grant over the back channel.
- Auth performs the same user verification described above.
- BFF persists tokens in Redis and returns profile/cookies/CSRF header, not raw tokens.
The endpoint still receives a user's password. It is retained, not used by the new browser callback flow. Migrating browser callers does not itself disable this API.
Legacy public SPA code exchange¶
The cis-bff--public-client registrations use authentication method none, PKCE and Angular callbacks on 4200/4201. Legacy POST /bff/auth/authorization-code completes compatible existing state and returns cookies/profile; it rejects BFF-owned transactions. Deprecated facade start helpers and CIS_BFF_PUBLIC_ settings are not the current /bff/auth/authorize entry. Use confidential client IDs for the new BFF flow.
5. Client-credentials flow: services and jobs¶
No human password, LDAP bind, browser callback, PKCE browser state or BFF session cookie is involved. The access token represents an application client.
- Provision a confidential client with client_credentials and minimal scopes.
- The service authenticates to auth /oauth2/token and requests that grant/scopes.
- Auth verifies client secret, enabled state, grant and allowed scopes.
- It issues a signed access token and persists authorization. Client/JTI claims identify the token. User enrichers require a CIS user principal: do not assume a machine token has user roles, province or human identity just because it is valid.
- The service calls an API with Authorization: Bearer, through BFF /api/** or a directly exposed resource server where allowed. The resource server enforces access.
- Obtain another client-credentials token on expiry; this is not a browser-session refresh.
POST http://localhost:8085/oauth2/token
Authorization: Basic <base64(service-client:service-secret)>
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&scope=read
BFF metadata discovery uses this flow with the dedicated metadata client and scope oauth.public-clients.read. It calls /api/v1/auth/internal/public-clients/{clientId} to retrieve ID, redirects, scopes, enabled/PKCE status and realm, never secrets. The legacy endpoint name says public-clients but also accepts PKCE confidential BFF clients with client_secret_basic. Its service credential is not a frontend secret.
sequenceDiagram
participant Service as Service client / BFF metadata client
participant Auth
participant API as Protected API / metadata endpoint
Service->>Auth: POST /oauth2/token with client_credentials and client authentication
Auth->>Auth: Check enabled registration, secret, grants and scopes
Auth-->>Service: Application access token
Service->>API: Authorization: Bearer access token
API->>API: Validate JWT and required scope/authority
API-->>Service: Authorized response
Note over Service,API: No human login page, browser cookie or LDAP bind
6. Shared identity verification and account policy¶
AbstractRealmAuthenticationTemplate validates input, verifies credentials/loads the Oracle user, checks user type against the selected realm, runs ordered applicable policies, resolves role names and creates AuthenticatedUserPrincipal.
| Realm | Credential authority | CIS requirement |
|---|---|---|
| INTERNAL | Configured LDAP via ActiveDirectoryLdapPortAdapter | Oracle CIS user of internal type must exist; successful LDAP bind does not provision an account |
| EXTERNAL | Oracle stored password with configured password encoder / BCrypt compatibility | External user type, account rules and role hydration |
External authentication performs a dummy password match for a nonexistent user, persists failed retry counts/lockout and resets retries after success. The retry limit comes from PASSWORD_RETRY_COUNT or the configured fallback. The internal LDAP strategy does not implement that external Oracle retry-count loop.
| Policy | Applies to | Result |
|---|---|---|
| AccountNonLockedPolicyRule | Both | Reject locked account |
| AccountActivePolicyRule | Both | Reject pending approval/inactive account |
| PasswordExpiryPolicyRule | External | Check latest history against PASSWORD_EXPIRED_POLICY/fallback; missing history is not automatically expiry |
| FirstTimeLoginPolicyRule | External | Reject reset-password/first-login flag |
Authentication exceptions do not roll back persisted retry updates. Browser login presents generic credential/account errors. Password token API responses can include structured lockout/remaining-attempt/first-login/LDAP-registration details. Those are different presenters of shared checks, not separate identity authorities.
7. API access: dual-mode BFF¶
GatewayAuthModeFilter applies to /api/** and selects handlers by priority.
| Request | Mode | Behavior |
|---|---|---|
| BFF session cookie | Cookie/session | Resolve/renew Redis session, enforce mutation CSRF, inject server-held bearer, remove browser Cookie header |
| Bearer without BFF session cookie | REST pass-through | Preserve token; no BFF cookie-session CSRF or session refresh |
| Both credentials | Cookie mode wins | Bearer cannot bypass session expiry/CSRF |
| Neither | Anonymous forwarding | Downstream endpoint decides whether anonymous access is allowed |
CookieSessionAuthHandler enumerates the injected Authorization name as well as returning its value; otherwise the proxy would omit it on ordinary Angular requests. An expired cookie does not fall back to another submitted bearer. Bearer pass-through does not establish a Spring Security user inside BFF or authenticate /bff/auth/me.
BffRouteRegistry matches configured workflow/API patterns, optionally strips prefixes, retains query strings and falls back to the API server. CisApiReverseProxyFilter uses Java HttpClient, copies allowed request/response headers and downstream status, streams the body, forwards DELETE bodies and removes hop/Connection-nominated headers. Cookie stripping is specifically part of cookie mode, not a universal assertion that no possible REST cookie header can reach an upstream.
Downstream application errors normally retain their own status/body. Gateway permitAll allows forwarding; it does not grant access to business data. API/workflow resource servers must validate tokens and enforce endpoint permissions. REST calls still rely on Redis rate limiting when enabled, even though they do not use a BFF session.
8. Refresh-token flow¶
BFF session renewal¶
- A cookie API request or POST /bff/auth/refresh reads Redis session state.
- BffSessionState compares access expiry with the configured refresh skew. /refresh does not unconditionally exchange a fresh token; GET /me does not force renewal.
- If renewal is needed but no refresh token exists, BFF deletes the session and returns refresh-unavailable/session-expired rather than inventing a token.
- It obtains a 30-second Redis refresh lease with a unique owner. A concurrent loser gets retryable 503 instead of exchanging the same rotating refresh token twice.
- The winner rereads session state, calls auth with the original client ID and the configured confidential secret when appropriate, then builds refreshed state.
- A Lua compare-and-save checks ownership and session existence. An expired lease owner cannot overwrite another winner or resurrect a deleted session.
- Lease release checks ownership. Cleanup failure is logged and the lease expires; it must not replace a successful result or the original failure.
Redis session TTL is updated using normal/remember choice. Remember state has a separate marker/TTL. Browser cookies receive Max-Age when issued; proxy token refresh does not automatically extend browser cookie expiry. Do not describe this as an unbounded sliding browser session.
Auth grant validation, policy recheck and rotation¶
Authorization-code/refresh customization reloads the current user, account policies and roles, checks browser-client realm and rejects refreshing impersonation identities. Client enabled/deleted state and denylist checks are separate from possession of a refresh string. The confidential BFF authenticates with its server secret; legacy public refresh uses PublicRefreshClientAuthentication instead.
OracleOAuth2AuthorizationService handles CLOB token lookup and framework authorization mapping. When a refresh token changes, RefreshTokenFamilyStore records a SHA-256 history entry in OAUTH2_REFRESH_HISTORY. Replay of a consumed token can revoke its entire authorization family. Sensitive issuance/rotation/revocation operations share a database mutation lock. This is not an atomic distributed Oracle/Redis transaction.
9. Logout and revocation flows¶
BFF logout¶
POST /bff/auth/logout uses cookie-session CSRF. BFF resolves the session, notifies auth about its token, removes resolved local session state and clears session/CSRF cookies. Remote notification is best effort. Local logout is not proof that all other authorizations/tokens were revoked. Auth browser SSO logout is separate: this endpoint does not automatically call identity-provider/global logout.
Custom token revocation¶
Auth POST /api/v1/auth/sessions/revoke-token accepts a token value and optional JTI hint. The route is deliberately permitAll: possession of a recognized token selects what can be revoked. The facade does not trust a standalone/unrelated JTI. It resolves the authorization in Oracle, blacklists the access JTI and removes the authorization, including its refresh credentials. Unknown tokens are idempotent no-ops. Framework OAuth revocation/introspection endpoints also exist; they are not this custom API.
Administrative user-session revocation¶
An authorized administrator POSTs /api/v1/auth/admin/sessions/revoke-user. The facade locks mutations, resolves the user, recovers access JTIs from Oracle, removes all that principal's authorization rows, revokes indexed Redis JTIs and publishes a user revocation event. Redis broadcast happens after database transaction commit. BFF's subscriber attempts to evict indexed sessions for the user.
Redis Pub/Sub has no durable replay/outbox here. Event broadcast and bulk eviction can log failures; request-time JTI/client checks remain necessary. Deleting OAuth authorizations does not itself destroy every auth browser HttpSession. Redis and Oracle failures must not be mistaken for successful global logout.
10. Administrator impersonation flow¶
- Browser POSTs /bff/auth/impersonate with positive targetUserId or nonblank targetUsername and valid cookie-session CSRF.
- BFF loads/renews the caller and checks exact authorities ROLE_ADMIN, ROLE_SUPER_ADMIN, ADMIN or SUPER_ADMIN. Substrings such as SUPERVISOR are insufficient.
- BFF calls auth /api/v1/auth/impersonate with the administrator's bearer. Auth derives the acting identity from the authenticated principal, not a submitted admin username.
- Auth rechecks administrator/target policy and issues actor-bearing impersonation credentials. BFF creates a separate Redis session linked to the original admin session, switches cookies and returns a sanitized profile.
- POST /bff/auth/impersonate/exit verifies current impersonation state, loads the original administrator session, deletes the impersonated BFF session and restores administrator cookies/profile. An expired original session cannot be restored.
Impersonation is not a normal indefinitely refreshable identity. Removing a local session is not evidence of downstream token invalidation; review the separate token lifecycle if investigating access using a copied REST token after exiting impersonation.
11. Signing-key rotation and JWT validation¶
RsaKeyPairFactory creates RSA material. AesPrivateKeyCipherAdapter uses the configured Spring encryptor password/salt for new private-key storage in RSA_KEY_PAIRS. Its legacy decryption fallback can accept unencrypted Base64/PEM material; do not assume all older rows are encrypted. All instances need compatible encryption configuration.
Scheduled or administrator KeyRotationFacade acquires the shared mutation lock, deactivates active keys with grace, purges expired grace keys, creates a new active key and publishes a local rotation event. Registration policy limits access-token lifetime relative to grace so valid tokens do not unnecessarily outlive verification keys.
OracleRsaKeyPairJwkSource returns active/grace descriptors. Despite its name, CachingJwkSourceDecorator currently rereads delegate descriptors instead of retaining a stale cross-node key list. Signing uses the active key ID; /oauth2/jwks publishes public verification keys. There is no general Redis-broadcast RSA cache-invalidation contract implemented merely because a local rotation event exists.
RotatingJwtDecoder in auth validates RS256, timestamps and configured issuer, then requires a JTI, available/enabled client and absence of token/client revocation. Revocation-store failure rejects validation. Downstream API/workflow validators have their own configurations; auth decoder behavior alone is not proof of their entire permission/revocation contracts.
JWT customization assigns JTI/client_id/clientRegistrationId and, for a CIS user, identity, authority, province, realm and impersonation actor claims. User claims come from Oracle-backed principal construction/rechecks, not from arbitrary browser fields. BFF's optional JWT payload parsing is profile extraction, not independent signature validation; its upstream OAuth responses must be trusted and transported securely.
12. Client administration and complete token settings¶
Client management supports create, list/get, secret rotation and delete. Registration policy checks grants/authentication methods, required realm, PKCE for public clients, HTTPS/loopback redirects, secret lengths and access lifetime versus key grace. Generated/supplied secrets are returned at creation/rotation time; summaries do not return them. RotatingClientSecretEncoder provides an overlap envelope for old/new hashes. Public clients using none have no rotatable secret.
The controller has no generic PUT/PATCH for callback updates. Change an existing registration through approved provisioning/migration, not undocumented delete/recreate. Deletion sets persistent client-revocation markers and removes related authorizations/ consents. New registration IDs distinguish recreated clients from old tokens.
Secret rotation is a separate lifecycle flow: an administrator authenticates, requests rotation, receives the newly generated/supplied raw secret once, distributes it through server secret management, and moves callers to it during the configured overlap. The metadata client's optional secret-file supplier can reload its credential on subsequent lookup; ordinary internal/external BFF environment secrets require the matching runtime configuration/restart. Secret rotation is not RSA signing-key rotation and does not by itself mean every existing access token was revoked.
Why authorizationCodeTimeToLive was null¶
Handwritten TOKEN_SETTINGS JSON omitted framework-required defaults. Loading that map is not equivalent to calling TokenSettings.builder(). The resulting null TTL failed during authorization-code generation, before the BFF could receive a code. All six local client registrations had incomplete settings, not only the internal BFF.
| Required setting | Current seed/backfill contract |
|---|---|
| Authorization-code TTL | Five minutes |
| Device-code TTL | Five minutes; this does not enable device grant support |
| Access-token TTL | Preserve explicit value: user-client seeds one hour, metadata client five minutes |
| Refresh-token TTL | Preserve explicit value: user-client seeds 30 days; missing values use framework fallback |
| Access-token format | Self-contained |
| Refresh-token reuse | False in module defaults; preserve explicit stored overrides |
| ID-token signature algorithm | RS256 |
| X.509-bound access tokens | False; not a statement that mTLS client authentication is configured |
R__01_seed_oauth2_registered_clients.sql now contains complete typed JSON. R__03_backfill_oauth2_token_settings.sql merges defaults below existing settings for rows missing required fields. It changes TOKEN_SETTINGS only. Typed duration, algorithm and access-token-format representations matter to JDBC deserialization.
EnabledRegisteredClientRepository fills absent/null known defaults when reading or saving older partial registrations, preserves explicit custom values, and still rejects disabled clients. It does not hide malformed JSON, invalid types or arbitrary invalid values. The tested local backfill updated six rows on 2026-10-19. This manual local repair does not mark a Flyway migration applied; its idempotent deployment backfill remains safe to run through the normal migration path.
13. Endpoint reference¶
BFF¶
| Method / path | Meaning and protection |
|---|---|
| GET /bff/auth/authorize | Confidential browser start; clientId/rememberMe optional; caller redirectUri rejected |
| GET /bff/auth/callback | Browser-bound single-use state, confidential code exchange, cookies and portal redirect |
| GET /bff/auth/me | Session profile and exposed CSRF token; unauthenticated 401 |
| POST /bff/auth/refresh | Session renewal if near expiry; cookie CSRF |
| POST /bff/auth/logout | Cookie-session logout/CSRF |
| POST /bff/auth/impersonate | Session CSRF plus exact administrator checks |
| POST /bff/auth/impersonate/exit | Session CSRF and original-admin-session restoration |
| POST /bff/auth/login | Compatibility JSON username/password flow |
| POST /bff/auth/authorization-code | Legacy SPA exchange; rejects BFF-owned transactions |
| /api/** | Cookie/bearer/anonymous proxy dispatch; final permissions downstream |
| Actuator | Operational exposure per configuration; not all probes imply authenticated access |
Auth¶
| Method / path | Meaning and protection |
|---|---|
| GET /oauth2/authorize | Authorization request, registered redirect, PKCE, browser realm handling |
| POST /oauth2/token | Registered OAuth grants and client authentication |
| /oauth2/jwks and configured OIDC/protocol endpoints | Framework protocol behavior; public keys, discovery/userinfo, revocation/introspection as configured |
| GET/POST /login | Auth browser page/form, server challenge and form CSRF |
| /logout, /signed-out, /login-assets/** | Auth browser session/logout/assets; Spring logout CSRF behavior remains enabled |
| GET /api/v1/auth/internal/public-clients/{clientId} | Bearer oauth.public-clients.read scope; enabled PKCE client metadata, no secret |
| POST /api/v1/auth/sessions/revoke-token | Token-possession revocation; optional JTI is only a hint |
| POST /api/v1/auth/admin/sessions/revoke-user | Administrator user authorization/token revocation |
| POST /api/v1/auth/impersonate | Administrator bearer identity, principal-derived acting user |
| GET/POST /api/v1/auth/admin/clients | Administrator list/create |
| GET/DELETE /api/v1/auth/admin/clients/{clientId} | Administrator get/delete |
| POST /api/v1/auth/admin/clients/{clientId}/rotate-secret | Administrator confidential-secret rotation |
| POST /api/v1/auth/admin/keys/rotate | Administrator signing-key rotation |
Admin routes require the exact four authority names listed in the impersonation section. The metadata scope is a separate authority and is not equivalent to merely being authenticated as a human. Framework OAuth endpoints follow their own chain, not the custom management-controller response contract.
14. Security filters and persisted state¶
Auth has three ordered security chains:
- OAuth/OIDC endpoint matcher: realm/mutation filters, client authentication, custom password grant, public-refresh compatibility, protocol handlers and conditional browser session creation. Its protocol CSRF configuration is separate from the browser form chain.
- Browser /login, /logout, /signed-out and assets: server challenge, realm provider, form CSRF and session-fixation protection; browser HttpSession allowed.
- Management/resource API: stateless JWT, admin/scoped matchers, health/info and token-possession revocation exceptions. CORS is disabled in this auth API chain.
BFF uses credentialed CORS, stateless Spring Security policy and custom Redis sessions. Its custom filter sequence is security headers, correlation, exception boundary, rate limiter, session-mutation CSRF, gateway mode selection, then proxy. Servlet registration is disabled for component filters already installed inside Spring Security. Otherwise a component could run outside the intended exception/security boundary.
| State | Owner / storage | Lifetime or purpose |
|---|---|---|
| Browser auth login challenge | Auth HttpSession | Expiring, bounded server-owned contexts; not BFF session state |
| BFF OAuth transaction | Redis session-prefix + oauth:transaction: | Five minutes, consumed once |
| BFF session | Redis session-prefix + session ID | Configured normal/remember session TTL |
| Refresh lease | Redis session-prefix + refresh-lease: | Owner-checked, 30 seconds |
| Remember marker | Redis session-prefix + remember: | Separate configured TTL |
| User-session index | Redis user-session prefix | Enables bulk BFF eviction |
| Rate counter | Redis rate-limit prefix and bucket/IP | Atomic fixed 60-second expiry |
| Token denylist / user token index | Auth Redis configured prefixes | Token lifetime/revocation rules, Lua coordination |
| Client deletion markers | Auth Redis client/legacy-client suffixes | Persistent registration/client identity rejection |
| OAuth clients/authorizations/consents | Oracle | Durable protocol/client state; token columns are sensitive |
| Refresh replay history | Oracle OAUTH2_REFRESH_HISTORY | Hashed consumed-token history through token expiry |
| Security mutation lock | Oracle AUTH_SECURITY_LOCK | Database serialization of sensitive mutations |
| RSA signing keys | Oracle RSA_KEY_PAIRS | Active plus grace verification material |
| User/role/config/password history | Existing Oracle UAM tables | Identity/account-policy authority |
| Auth audit | Oracle AUDIT_LOG | Event persistence; details representation discussed below |
Prefixes must match across writers and consumers. Lua makes particular operations atomic; it does not make every session/index write or Oracle/Redis operation a single distributed transaction. Oracle/JDBC authorization token storage is sensitive; RSA-key encryption is not evidence that all token values are encrypted at rest.
15. Cookies, CORS and frontend behavior¶
CIS_SESSION is HttpOnly. The CSRF cookie is separate/readable. Secure, SameSite, Max-Age and optional Partitioned attributes come from configuration. Current dev uses loopback/nonsecure/Lax; UAT/prod use Secure/Lax. SameSite is not unconditionally Strict. Auth browser session cookies and BFF session cookies serve different purposes.
The BFF module env variable CIS_BFF_CORS_ALLOWED_ORIGIN_PATTERNS is localhost-based
in dev and https://*.cis.accesscam.org in UAT/prod. Methods, request headers,
credentials and exposed response headers are environment-backed too. Compose selects
cis-bff/.env.
A CSRF cookie on the BFF hostname cannot be read directly by Angular on another host. After login/redirect, make credentialed GET /bff/auth/me, read X-XSRF-TOKEN and supply it on mutations. The current CORS exposure allows that response header. Reading a header on an Angular HTTP response is different from top-level navigation following a redirect. Never expose OAuth access/refresh tokens merely to work around CSRF.
Cookie + bearer selects cookie mode, so the bearer cannot bypass CSRF. CORS does not authenticate REST callers, register OAuth redirects or replace mutation CSRF.
16. Errors, resilience, health, metrics and audit¶
BFF generated errors use ProblemDetail. MVC failures retain 400/404/405/406/415 and protocol headers such as Allow. Domain codes/account attributes are preserved where part of the compatibility contract. LDAP registration profile data is intentionally included by that specific compatibility response. Generic internal messages are sanitized. Dependency transport failure is 503; proxy I/O/connect is 502; proxy timeout is 504; unexpected bugs are 500. The filter boundary delegates pre-controller exceptions to MVC. A committed stream cannot be rewritten as a new JSON error.
Auth has distinct browser, OAuth token and REST error presenters. Browser feedback is generic; token errors follow OAuth handling and may carry domain fields; REST advice uses its own structured domain response. An incomplete client token-settings map is a configuration error, not invalid user credentials.
Rate limiting is an atomic fixed Redis window, not a sliding token bucket. Its stricter budget covers login, authorize, legacy code exchange and refresh; callback currently uses the general budget. Missing Redis results fail closed. Client-IP extraction trusts forwarded headers, so ingress must sanitize those headers.
Circuit breakers wrap upstream calls; an HTTP 500 response is not automatically a thrown transport failure in this proxy. Body streaming occurs after header acquisition; initial HTTP timeout is not a guaranteed deadline for an entire long-lived streamed body. There is no implied automatic retry of arbitrary non-idempotent requests.
Correlation IDs are generated or accepted only with bounded safe characters, returned and forwarded. Proxy metrics are bff.proxy.latency and bff.proxy.requests.total, with route/status/family tags as implemented; rate-limit rejections have a counter. The downstream health indicator makes auth decisive and records API results in its details; it is not a strict all-upstream readiness gate. Redis has a separate probe.
BFF audit events are asynchronous log records, not an Oracle audit table. Auth's listener persists AUDIT_LOG and uses Map.toString for details, not guaranteed JSON. It is annotated Async but the auth application does not itself enable async processing; do not promise off-thread behavior without additional configuration evidence. Event logging is not proof of durable distributed delivery or completed global revocation.
17. Migration and troubleshooting¶
Auth owns FLYWAY_SCHEMA_HISTORY_AUTH; other modules have separate histories. Applied versioned migrations remain immutable. Client seeds/settings use repeatable idempotent scripts. Do not run every module's migration inventory indiscriminately in a shared schema.
| Symptom | What to check |
|---|---|
| External page for internal login | Confidential internal client ID and persisted authentication realm |
| CSP blocks login form redirect | Restart auth with the continuation-page change; begin a fresh challenge; keep strict form-action policy |
| Login resumes auth /oauth2/authorize | Expected code-issuance step; investigate only if it fails to continue |
| Angular receives /oauth/callback | Legacy public-client registration; current flow registers BFF callback |
| Invalid/missing state | Same browser cookie store, expiry, replay, parallel starts, exact callback/return settings |
| authorizationCodeTimeToLive cannot be null | Complete typed TOKEN_SETTINGS, R__03 backfill, not only one manually added TTL |
| Angular reaches API without bearer | Cookie wrapper's header enumeration, session refresh and selected proxy mode |
| 403 on browser POST/PUT/PATCH/DELETE | Credentialed session and matching CSRF header |
| REST works but browser CORS fails | Actual origin plus module CORS methods/headers/exposure and cookies |
| 503 on concurrent refresh | Lease contention/expiry; retry instead of concurrently redeeming one refresh token |
| Token works after a local logout elsewhere | Separate authorization, remote best-effort revoke, auth SSO session and downstream denylist contract |
| Signature failures after rotation | Issuer, key grace, encryption configuration and downstream JWKS refresh |
Do not troubleshoot by disabling signature checks, realm restrictions, client authentication or CSRF. Trace the selected flow, registered client, persisted settings, cookie jar and environment configuration. Avoid logging raw credentials/tokens.
18. Validation strength and open operating contracts¶
The BFF callback revision passed 106 BFF tests and 15 focused auth tests. The subsequent token-settings fix passed 13 focused seed/JDBC deserialization, missing-default/disablement and authorization-code security-chain tests, with zero failures/errors/skips. Those are snapshots, not a production certification. The earlier full auth suite was stopped while waiting for an isolated Oracle test container and is not claimed as passed.
The local Oracle token-settings-only repair updated six clients after compatibility tests passed. Existing explicit lifetimes/rotation and unrelated registration columns were preserved. No production database was changed. A browser/LDAP sign-in against the deployed build, CORS/cookie behavior, multi-node sessions and every downstream permission still require environment validation.
Known operating boundaries, not claimed fixes: Pub/Sub has no replay, bulk BFF eviction can log failure, auth browser HttpSession is separate from BFF Redis state, same-host cookies are shared by portals, IP headers require trusted ingress, and stream failures cannot replace committed responses. Spring annotations/class names are not proof of async execution, cache coherence, durable events or end-to-end revocation guarantees.
Scope of account UI and authentication factors¶
The modules enforce account flags and password-age rules; that is not evidence they implement every registration, password-reset or approval UI. BrowserAuthenticationProvider adds a password-factor authority, not an implemented second-factor/MFA enrollment flow. Account lifecycle work owned by other modules must be traced separately.
19. Environment configuration and rollout¶
Environment files and URL ownership¶
Use the module's .env.dev, .env.uat or .env.prod; matching .example templates
are the checked-in configuration contract. Root environment files control Compose
orchestration and published ports, and do not replace the module environment files.
Spring does not automatically load arbitrary .env files. Gradle bootRun selects
module environment files with -Penv=dev, -Penv=uat or -Penv=prod; other launchers
must supply the variables explicitly. The inventory below maps variables to consumers.
| Setting | Development | UAT | Production |
|---|---|---|---|
| CIS_BFF_CALLBACK_URI | http://localhost:8080/bff/auth/callback | https://bff.cis.accesscam.org/bff/auth/callback | https://bff.cis.accesscam.org/bff/auth/callback |
| CIS_BFF_INTERNAL_FRONTEND_URL | http://localhost:4201/ | https://internal.cis.accesscam.org/ | https://internal.cis.accesscam.org/ |
| CIS_BFF_EXTERNAL_FRONTEND_URL | http://localhost:4200/ | https://external.cis.accesscam.org/ | https://external.cis.accesscam.org/ |
| CIS_BFF_CORS_ALLOWED_ORIGIN_PATTERNS | Configured localhost origins | https://*.cis.accesscam.org | https://*.cis.accesscam.org |
Use separate UAT portal destinations if your frontend deployment uses different hosts.
Callback and portal settings require HTTPS except loopback development, reject query,
fragment and user-info components, and require the callback path /bff/auth/callback.
A configuration change invalidates older pending browser transactions: start again.
AUTH_SERVER_URL is the BFF server-to-server token/metadata endpoint. In host development it is http://localhost:8085; in local Compose it is http://cis-auth:8085. CIS_BFF_AUTHORIZATION_BASE_URL is browser-facing and remains http://localhost:8085 for that Compose setup. Browsers cannot normally resolve Docker service names, and localhost inside a container points to that container. Use trusted HTTPS in deployment; CIS_BFF_ALLOW_INSECURE_BACK_CHANNEL is an explicit local-development opt-in.
Metadata credentials are separate from internal/external BFF user-client credentials. Configure CIS_BFF_METADATA_CLIENT_SECRET or CIS_BFF_METADATA_SECRET_FILE to match the dedicated auth registration. The file source is reread on discovery refresh; environment credentials require process replacement after rotation. Missing deployment secrets must be supplied, never copied from development examples. Client-secret overlap must cover metadata cache lifetime and rollout delay, within the auth policy limits.
Discovery, cache and registration changes¶
| Condition | Result |
|---|---|
| Fresh metadata | Reuse within configured TTL |
| Expired metadata, service available | Refresh against the scoped metadata endpoint |
| Transport/5xx failure within stale grace | Previously validated metadata may be reused |
| No cached entry or grace exhausted | Fail closed with dependency error |
| Authentication/authorization failure or missing registration | Evict/reject; no stale fallback |
| Disabled client or changed realm | Auth rechecks current registration regardless of BFF cache |
The current metadata endpoint accepts eligible PKCE public clients and confidential BFF clients using client_secret_basic. A cached entry cannot make auth accept an unregistered callback, disabled client or wrong realm. Direct SQL enablement changes do not themselves broadcast logout of already-issued sessions/tokens.
Rollout checklist¶
- Verify BFF 8080, auth 8085, API 8089, workflow 8090 and Angular 4201/4200 for local host development. Check published ports separately from container ports.
- Apply the module's migrations through its configured Flyway history. Keep applied versioned migrations unchanged. Auth requires its security-lock schema/row and refresh-history migrations before the coordinating implementation serves traffic.
- Apply repeatable client seeds and token-settings backfill through the normal migration process. The seed upgrades recognized obsolete local callback URLs, preserves custom deployment URLs and existing secrets, and does not configure your UAT callback for you.
- Register the exact environment BFF callback for both confidential clients and require PKCE. Legacy public Angular callbacks are compatibility registrations only.
- Match client credentials, Redis namespaces, issuer and signing-key encryption settings across the processes that use them. Retain revocation markers and key grace material.
- When introducing security-mutation coordination, replace all auth nodes with compatible versions; older nodes do not participate in its Oracle lock. Deploy the matching BFF.
- Restart auth/BFF and use a fresh browser authorization. Verify each portal, callback,
/me, API mutation CSRF, refresh and logout with the same browser cookie store. - Test LDAP, cookies/CORS, multi-node behavior and downstream permissions in the target environment. Unit/security-chain tests do not establish those deployment contracts.
python scripts/config/check_auth_env.py
python scripts/config/check_auth_env.py --examples-only
.\gradlew.bat :cis-auth:test --tests '*AuthorizationCodeSecurityIntegrationTest' --console=plain
.\gradlew.bat :cis-bff:test --console=plain
The environment checker reports key problems without printing secret values. Full auth integration tests may start isolated Oracle/Redis containers; plan for Docker availability. These are verification commands, not a statement that every command was rerun for this documentation-only consolidation.
20. Browser pages and annotated walkthrough¶
Capture status and how to read these notes¶
The descriptions below were checked against the current templates, renderer and handlers.
They are source-based page notes, not screenshots or proof of a completed live login.
This session has no available browser connection, so actual page captures could not be
added. When captures are available, embed them here beside these notes rather than
creating another reference document. Keep image assets under docs/assets/images/security/;
use empty credential fields and omit cookies, tokens, real user profiles and challenge
values. Record the environment, build/date and page state with each capture.
Page A: Internal staff login¶
Open http://localhost:8080/bff/auth/authorize?clientId=cis-bff-internal-client by browser
navigation. BFF starts authorization and auth sends the browser to its challenged login
page; opening /login directly is not the entry point.
| Visible area / control | Meaning and behavior |
|---|---|
| CIS / Connected services | Local branding; page and assets are served by cis-auth |
| Internal staff badge | Comes from the registered client's INTERNAL realm |
| Welcome back / client name | Escaped registered display name identifies the application |
| Organisation username | Staff organization account; LDAP verifies credentials |
| Password / Show | Masked password with visibility toggle; visibility does not change transport |
| Sign in securely | Posts to same-origin auth /login with hidden challenge and Spring CSRF |
| Progress message | Button disables while submitting; pageshow restores controls |
| Trusted-address note | User should check the real auth origin before entering credentials |
LDAP success still requires a matching CIS internal user and account-policy checks. There is no realm dropdown or failed-login fallback to external database authentication.
Page B: External portal login¶
Open http://localhost:8080/bff/auth/authorize?clientId=cis-bff-external-client. The shared template displays External portal, CIS username, the registered client name and external account help text. ExternalDbAuthStrategy verifies the CIS database password hash and account policies. The page appearance follows the registered realm; CORS and frontend domain names do not choose the credential store.
Page C: Failed sign-in¶
The challenged login page shows: "We couldn't sign you in. Check your details and try again." The browser message deliberately does not distinguish unknown username, bad password, lockout or other account-policy failures. A valid challenge may be retried; no password is returned in the rendered form. Compatibility REST responses can retain specific domain codes and account attributes under their separate contract.
Page D: Successful sign-in continuation¶
POST /login succeeds with HTTP 200 and a no-store page titled Continue sign-in.
It says "Sign-in successful. Continuing to your application." and has a Continue link.
The local continue.js navigates to the saved same-origin authorization URL using
location.replace; the link works when JavaScript is unavailable. The URL contains the
captured OAuth request, never the submitted password.
This deliberately ends the credential form submission before OAuth redirects to another
origin. Chrome can otherwise apply form-action 'self' to the full redirect chain and
block the BFF callback. Keep the strict policy. The continuation uses an external local
script and an HTML-escaped, server-built target; it does not allow arbitrary form targets.
Seeing /oauth2/authorize briefly is expected: auth must create the code before calling
BFF. BFF then exchanges the code on its back channel and redirects to its configured
internal/external portal. Angular receives its normal page, then calls /bff/auth/me.
Page E: Expired, missing or consumed challenge¶
Auth renders Start sign-in again and explains that the request is missing, expired, already used or unavailable. Return to the portal and start at BFF authorize. Do not reuse an old challenged URL or manufacture a challenge. A successful submission consumes the challenge, preventing its reuse even after browser back navigation.
Page F: Signed out¶
Auth's CSRF-protected POST /logout redirects to /signed-out, which displays
"You are signed out". This ends auth's browser session. BFF logout separately clears
its own Redis session/cookies; it does not automatically visit this page or perform
single logout across every portal.
Browser verification notebook¶
| Check | Expected observation |
|---|---|
| Internal start | Internal staff page, or matching-realm SSO |
| External start | External portal page, or matching-realm SSO |
| Wrong password | Generic error without a credential echo |
| Successful POST | Continuation page, separate authorize navigation, BFF callback, configured portal |
| Portal URL after completion | No OAuth code, state or access/refresh token |
Credentialed /me |
Sanitized profile and exposed X-XSRF-TOKEN header |
| Cookie mutation without CSRF | Rejected; repeat with current CSRF succeeds if otherwise authorized |
| Reused/expired challenge or state | Rejected; new authorization succeeds |
| BFF logout | BFF session unusable; auth SSO may still exist |
| Auth logout | Local signed-out page; does not prove all distributed sessions revoked |
Capture the pages with notes, rather than raw network exports containing authorization headers or cookies. The latest continuation change passed all 10 authorization security integration tests; a real-browser capture/verification remains outstanding.
Angular integration after the redirect¶
The frontend starts navigation with its configured confidential BFF client ID. It does not supply redirectUri, receive a code, or hold a client secret. Example for internal:
const start = new URL('/bff/auth/authorize', environment.bffBaseUrl);
start.searchParams.set('clientId', 'cis-bff-internal-client');
start.searchParams.set('rememberMe', String(rememberMe));
window.location.assign(start.toString());
After arriving back at the portal, fetch /bff/auth/me with credentials included and
read the X-XSRF-TOKEN response header. Keep that value in application state and send
it on cookie-authenticated mutations. An Angular interceptor must cover the configured
cross-origin BFF URL; the default same-origin XSRF behavior alone may not cover it.
This is an integration contract, not a change to the separate Angular repositories.
SSO and direct protocol controls¶
A matching-realm auth HttpSession can avoid another credential prompt. A different realm requires its own authentication. Direct valid authorization requests enforce prompt=none (no form; login_required if authentication is needed), prompt=login (fresh credentials), max_age (freshness), and prompt=consent (preserved through login). Invalid combinations, unknown prompts, duplicate critical parameters and invalid redirects/PKCE are rejected. The BFF convenience endpoint exposes clientId and rememberMe, not a general prompt/max_age forwarding API. Fresh authentication removes prompt=login/max_age from the resumed request so it does not loop; consent remains subject to registered policy and existing grants.
21. Security controls and audit record¶
This section records the resulting controls, not the obsolete pre-fix implementation. It supersedes the separate discovery, hardening and BFF exception audit notes. Historical test counts describe those revisions and are not cumulative coverage or certification.
| Finding | Result |
|---|---|
| A GET against a POST-only endpoint reached the generic exception handler and returned 500. | The advice extends Spring MVC's ResponseEntityExceptionHandler, retaining framework statuses and headers, including 405 and Allow. |
| Missing/invalid parameters, unsupported media types, method validation and explicit status exceptions could fall through to 500. | Framework exception handling preserves their statuses. Public details are sanitized; body-validation field messages remain available without rejected values. |
| Cookie authentication, Redis rate limiting and CSRF failures occur before MVC advice. | A filter boundary delegates exceptions to MVC's configured resolver. Committed responses and unresolved failures are rethrown. |
| Component filters also auto-registered in the servlet chain, allowing rate limiting to run outside the security exception boundary. | Servlet registration is explicitly disabled for filters already installed in Spring Security. |
| Security entry/denial responses and session CSRF failures had different error paths. | Entry/denial handlers and session CSRF use the common problem response handling. CORS rejection remains controlled by Spring's CORS processor. |
| Token parsing errors were caught again and converted into 401; auth-server outages also became 401. | Domain errors retain their meaning; unavailable/rate-limited auth token services return 503, malformed successful token responses return 502, and missing access tokens are rejected. Known account-state responses remain intact. |
| Proxy timeout was caught as a generic I/O error; raw exception strings were interpolated into JSON. | Timeout returns 504; connection failure returns 502; unexpected failure returns 500. Generated errors use the MVC serializer and sanitized messages. A partial committed stream is never rewritten. |
| Invalid requested redirect/client input raised a generic programming exception. | Expected redirect/client validation failures use explicit 400 domain exceptions. Programming exceptions still return sanitized 500 responses. |
| Session serialization failures were logged while login could continue as if storage succeeded. | Persistence serialization failure propagates; session establishment cannot report success after that failure. |
| Impersonation/revocation back-channel requests had no explicit transport timeouts. | Both use bounded connection/read timeouts. Impersonation transport and malformed response errors are sanitized. |
Additional auth/BFF controls verified in the source audit:
- OAuth security mutations use an Oracle row lock across cooperating auth nodes. Client authentication happens before token mutation locking; response buffering prevents a successful token response escaping before transaction commit. This serializes mutations and requires throughput testing for the intended deployment.
- Refresh reloads current account policies/roles; persisted principals use an explicit deserialization allowlist. Consumed refresh tokens have hashed replay history.
- Revocation reads/writes fail closed. Token indexing retains expiry plus validation clock allowance. Lua preserves the longest blacklist/index lifetime; legacy unknown-expiry JTIs are handled conservatively instead of guessing a safe expiry.
- Standard/custom/user revocation removes the appropriate persisted authorizations and refresh capability. Untrusted JTI hints cannot revoke unrelated tokens. Oracle CLOB lookups use DBMS_LOB.COMPARE. In-flight accepted requests can still finish.
- Client create/delete/secret rotation participate in mutation coordination. Token issuance revalidates client snapshots after locking. Permanent client markers and internal registration IDs prevent recreating an external client ID from reviving old tokens.
- Key bootstrap/rotation coordinate across nodes; failed replacement rolls back deactivation. The active signing key is selected explicitly and retired verification keys remain for grace.
- Cookie wrappers enumerate the injected bearer header and remove browser cookies before forwarding. Cookie authentication wins over a simultaneous bearer header.
- OAuth state-cookie comparison occurs before Redis transaction consumption. Refresh commits only while the lease/session is still owned; lease cleanup cannot replace the original failure or invalidate a successful result.
- Rate increments/expiry are atomic, missing expiry is repaired, and absent Redis results fail closed. Trusted ingress must sanitize forwarded IP headers.
- Proxy DELETE bodies are preserved, hop-by-hop and Connection-nominated headers stripped, correlation IDs bounded, and metrics recorded even on generated proxy errors.
- Impersonation uses authenticated administrator identity and exact authorities, validates target ID/username and avoids null audit-map crashes. Transport calls have bounded timeouts.
Registration limits, supported grants/authentication combinations, key-grace relationships, secret overlap, enabled-client behavior and partial token-settings compatibility remain explained in sections 6 and 11-12. Pub/Sub replay, bulk-eviction failures, committed-stream limits, session sharing and downstream validation limits remain in sections 8-9 and 16-18. No historical audit finding is permission to relax those controls during troubleshooting.
22. Complete request lifecycle and fish diagram¶
How to use this technical guideline¶
Read the six-stage spine from left to right. Branches identify the controls at that stage; this is a fish-style flow diagram, not a cause-and-effect analysis. The image summarizes multiple HTTP requests across one signed-in session. A business API request is a separate exchange from the browser login and token endpoint exchanges.

Open scalable SVG. The diagram is based on repository source; it is not a screenshot of a running service. The diagram's API revocation check has the implementation limits described below.
Stage 1: Browser asks BFF to start authentication¶
- Internal Angular navigates to BFF 8080
/bff/auth/authorize?clientId=cis-bff-internal-client; external Angular selectscis-bff-external-client. This is top-level navigation. - BFF checks its configured client choice, discovers the enabled registered client's realm/redirects/scopes, and verifies its own exact callback. Discovery uses a separate service token with oauth.public-clients.read; a fresh cache can avoid that HTTP call.
- BFF creates state and a PKCE verifier, stores the transaction/portal destination in
Redis for five minutes, sets the browser-bound OAuth state cookie, and redirects
to auth's browser-facing
/oauth2/authorize. The verifier and client secret stay server-side.
Result: an authorization request exists; the user does not yet have a BFF session.
Stage 2: Auth verifies the user and issues an authorization code¶
- Auth checks client/redirect/scopes/PKCE and the persisted realm. A sufficiently recent matching-realm auth session may satisfy SSO. Otherwise it creates an auth-session-bound login challenge and renders the internal/external login page on auth 8085.
- The browser posts username/password, hidden challenge and Spring CSRF token to auth
/login. Internal verification uses LDAP plus a CIS internal-user record; external verification uses the CIS database password. Both apply the relevant account policies. - Successful login returns HTTP 200 with the no-store continuation page. Its local script, or the fallback Continue link, navigates to the saved relative authorization request. This breaks the form-POST redirect chain while retaining strict form-action CSP.
- Auth creates the short-lived authorization code and redirects the browser to
BFF
/bff/auth/callback?code=...&state=.... Auth's browser HttpSession belongs to auth; it is distinct from the BFF Redis session that will be created next.
Result: the browser carries a one-time code to BFF. Angular does not receive that callback.
Stage 3: BFF exchanges the code and creates its session¶
- BFF compares the returned state to its browser cookie before consuming the transaction. It checks expiry, configured callback and stored portal destination. Missing, mismatched, expired or reused state fails; the caller must restart authorization.
- BFF calls auth
/oauth2/tokenover AUTH_SERVER_URL with authorization_code, code, exact callback and stored PKCE verifier, authenticating with its server-held client secret. Auth validates the code/client/verifier and current user policy/roles, signs the JWT, persists authorization state in Oracle and maintains its revocation index in Redis. - BFF stores access/refresh tokens, expiry, JTI, identity and session CSRF state in Redis, sets the HttpOnly session cookie and CSRF cookie, and redirects to its configured portal.
- Angular calls credentialed
/bff/auth/meand reads the sanitized profile and exposed X-XSRF-TOKEN header. OAuth tokens are not returned to Angular or appended to the portal URL.
Result: browser has a session identifier; BFF holds tokens; auth owns durable OAuth state.
Stage 4: BFF processes a business request¶
- Angular sends its business request to BFF
/api/**, with credentials included and the current X-XSRF-TOKEN header for POST/PUT/PATCH/DELETE. A cross-origin browser may first issue a CORS preflight. Successful preflight is permission to send, not authentication. - BFF applies CORS/security headers, safe correlation ID, its exception boundary and the
Redis rate limiter. The separate BffSessionCsrfFilter protects BFF session mutations;
CookieSessionAuthHandler performs the CSRF check for cookie-authenticated
/api/**. - GatewayAuthModeFilter chooses cookie mode first. It loads the Redis session and checks its JTI and client-deletion markers. A corrupt/missing/revoked session cannot provide a bearer token. A simultaneous caller bearer header does not bypass cookie-mode failure.
- If access-token expiry is within the configured skew, BFF acquires a 30-second owner lease, rereads the session and calls auth's refresh grant using the original client. Auth rotates tokens and rechecks user/client policies; BFF commits only while it still owns the lease and the session exists. Contention/commit failures are retryable 503s. A valid sufficiently fresh access token skips this entire auth call.
- CookieSessionAuthHandler then verifies mutation CSRF, removes the browser Cookie header and replaces/enumerates Authorization with the session's bearer token. In this current implementation token renewal can occur before this API mutation CSRF check.
- BffRouteRegistry picks the first configured matching route, optionally strips its configured prefix and preserves the query string. Without a match, it uses the configured cis-api base URL. Workflow routes can select cis-workflow instead; confirm route settings. The proxy strips hop-by-hop headers and sends the method/body and correlation ID through a bounded HTTP call wrapped by the route circuit breaker.
Result: cis-api receives a bearer-authenticated HTTP request, not the browser's BFF cookie. A normal fresh-token request is browser -> BFF -> cis-api; it does not visit auth per request.
Stage 5: Cis-api authenticates, authorizes and executes¶
- ResourceServerSecurityConfig uses NimbusJwtDecoder and its configured JWKS endpoint to verify the signature, configured issuer/resource audience and timestamp constraints. Signed iat plus exp, sub, client_id and jti are required; missing/blank claims are rejected. Public keys can be cached; JWKS lookup is not a token introspection or a password check for each business request.
- JwtToSecurityUserConverter maps verified claims into SecurityUser and granted authorities for the current request. Cis-api creates no BFF session and does not trust browser-supplied identity headers as a replacement for the bearer token.
- RedisTokenRevocationFilter checks the JWT JTI and client-registration deletion marker against the configured revocation prefix (with a legacy client-ID marker fallback). Revocation/deletion returns 401; Redis failure or an indeterminate result returns 503, and neither reaches business execution. Anonymous public requests do not require Redis.
- URL security requires authentication except for its explicit public allowlist. Method annotations/custom permission expressions apply where declared; service/domain rules still determine record access and valid operations. Authentication alone does not prove a caller has every business permission, and not every method has an explicit role check.
- Spring binds and validates controller inputs, calls the endpoint's service, repository and database, then maps/serializes the result. Transaction boundaries and response wrappers are endpoint-specific. Do not assume every request writes data or opens a distributed transaction spanning BFF, auth, Redis and Oracle.
Result: cis-api produces its endpoint response or security/validation/domain error.
Stage 6: Response, subsequent requests and session termination¶
- BFF copies allowed upstream response headers/status and streams the body back. The BFF correlation ID remains authoritative, and proxy route/status/latency metrics are recorded. A completed cis-api error response retains its original body/status; BFF does not convert every upstream error into its own ProblemDetail envelope.
- Angular handles the returned status/body. Missing/invalid authentication requires a new sign-in; a retryable infrastructure failure is different. Do not blindly retry a mutation whose database commit outcome is unknown, especially after a timeout or disconnected stream.
- Future API calls repeat stages 4-6. Explicit BFF refresh uses the same session renewal logic;
/meitself does not silently renew the token. Remember-me session policy does not override auth refresh-token expiry or account disablement. - A CSRF-protected BFF logout resolves the session, attempts remote token revocation, deletes resolved local session state and clears cookies. Remote notification is best effort. Successful local logout does not prove that auth's separate browser SSO session or every distributed session has ended. Auth browser logout and administrator user revocation have their own flows in section 9.
Detailed service sequence: login, API, renewal and logout¶
sequenceDiagram
autonumber
participant Browser as Angular / browser
participant BFF as cis-bff :8080
participant Redis
participant Auth as cis-auth :8085
participant API as cis-api :8089
participant DB as Oracle / identity services
Browser->>BFF: GET /bff/auth/authorize with configured clientId
opt Metadata cache needs refresh
BFF->>Auth: Client-credentials token and scoped metadata lookup
Auth-->>BFF: Eligible registration metadata
end
BFF->>Redis: Store state, verifier and portal destination
BFF-->>Browser: State cookie and auth authorization redirect
Browser->>Auth: GET /oauth2/authorize
Auth-->>Browser: Challenged realm-specific login page unless SSO applies
Browser->>Auth: POST /login with credentials, CSRF and challenge
Auth->>DB: Verify realm identity and CIS account policies
Auth-->>Browser: 200 continuation page
Browser->>Auth: Separate GET of saved authorization request
Auth-->>Browser: Redirect to BFF callback with code and state
Browser->>BFF: GET /bff/auth/callback
BFF->>Redis: Check browser-bound state and consume transaction
BFF->>Auth: Code exchange with confidential credentials and PKCE
Auth->>DB: Persist OAuth authorization and current user claims
Auth->>Redis: Index issued token for revocation
Auth-->>BFF: Access and refresh tokens
BFF->>Redis: Persist session, token state and CSRF
BFF-->>Browser: Cookies and configured portal redirect
Browser->>BFF: GET /bff/auth/me with cookies
BFF-->>Browser: Profile and X-XSRF-TOKEN response header
Browser->>BFF: Business /api/** with cookies and mutation CSRF when needed
BFF->>Redis: Rate limit, session and revocation checks
opt Token needs renewal
BFF->>Redis: Acquire owner lease and reread session
BFF->>Auth: Refresh grant using original client
Auth->>DB: Recheck policy, rotate tokens and record replay history
Auth->>Redis: Update token index
Auth-->>BFF: Rotated tokens
BFF->>Redis: Commit if lease and session still owned, release lease
end
BFF->>BFF: Check API mutation CSRF, remove cookie, inject bearer, resolve route
BFF->>API: Original API method/path/body with bearer and correlation ID
opt JWKS cache needs a signing key
API->>Auth: Fetch public JWKS
Auth-->>API: Public verification keys
end
API->>API: Verify signature, issuer, audience and required claims, map principal
API->>Redis: Check JTI and client revocation, fail closed if unavailable
API->>API: Enforce URL/method policy and validate input
API->>DB: Endpoint service and repository operation
DB-->>API: Result
API-->>BFF: Endpoint status, headers and body
BFF-->>Browser: Stream response, record proxy metrics
Browser->>BFF: POST /bff/auth/logout with session CSRF
BFF->>Auth: Attempt token revocation when session token was resolved
Auth->>DB: Remove matching OAuth authorization / refresh capability
Auth->>Redis: Record revocation and publish notification
BFF->>Redis: Delete resolved local session
BFF-->>Browser: Logout response and cookie clearing
Note over Browser,Auth: Auth browser SSO logout is separate
This sequence shows the successful path. Failed state/CSRF, rejected policy, dependency failure or revocation stops later steps; auth browser SSO can skip credential entry. Redis Pub/Sub is best effort, not a durable event queue or a prerequisite for each call.
Concrete API trace and credential boundaries¶
For a read-only protected example, use BFF
GET /api/v1/province/list/address?provinceId=<existing-id>. The default core route preserves
that path and query to cis-api. ProvinceResource validates the provinceId and calls
ProvinceService for the address result. Existence of an ID and endpoint-specific permissions
must be checked in the target environment. /api/v1/province/list is an explicitly public
endpoint and should not be used as proof that protected authentication works.
| Hop | Credential or data | Where it ends |
|---|---|---|
| Browser -> auth login | User password, auth form CSRF and login challenge | Auth identity verification |
| Browser -> BFF callback | One-time authorization code and state | BFF consumes state and exchanges code |
| BFF -> auth token endpoint | Client authentication, code/verifier or refresh token | Auth token processing |
| Browser -> BFF API | HttpOnly session cookie; mutation CSRF header | BFF session and CSRF checks |
| BFF -> cis-api | Server-held access token in Authorization; correlation ID | API JWT/security chain |
| Cis-api -> repository/database | Validated business arguments under endpoint policy | Endpoint-specific persistence operation |
| Cis-api -> BFF -> browser | Endpoint status/headers/body | Frontend handling; no OAuth token exposure |
REST bearer callers skip the cookie-session branch: BFF passes their token through, without creating a BFF principal/session or performing cookie CSRF. Cis-api still verifies it. Anonymous calls may be forwarded; the downstream public allowlist decides access. Neither branch makes BFF the final business authorization authority.
Failure checkpoints and recovery¶
| Checkpoint | Visible outcome / action |
|---|---|
| Invalid callback/state or consumed transaction | Reject; begin fresh browser authorization |
| Expired/missing BFF session or revoked JTI | API session access fails with 401; sign in again |
| Missing/mismatched API mutation CSRF | BFF 403 before business forwarding |
| Disallowed browser origin | CORS rejects/withholds browser access; inspect preflight and origin settings |
| Rate budget exhausted | BFF 429; respect rate policy |
| Redis/auth dependency or renewal lease contention | Controlled dependency/renewal error, commonly 503; use bounded retry where safe |
| Invalid/expired JWT, wrong issuer/audience, or token/client revocation | Cis-api 401; do not treat it as a business permission failure |
| Downstream permission denial | Cis-api 403; inspect URL/method/domain policy |
| Invalid endpoint input | Downstream validation response; correct the request |
| Proxy circuit open / transport failure / timeout | BFF 503 / 502 / 504 respectively, if response is uncommitted |
| Response already streaming when connection fails | Partial/failed response; BFF cannot replace it with a clean error body |
| Local logout succeeded but auth browser still signed in | Separate SSO session; integrate its logout when required |
Current implementation limits to account for¶
The diagram describes actual checks, not a claim of uniform enforcement everywhere:
- The earlier missing issuer/audience and fail-open revocation gaps are fixed in source. API validation now requires the configured issuer/audience, timestamp checks and required claims. Redis checks use the verified JWT token object, not erasable password-token credentials. Known revocation returns 401 with a Bearer invalid_token challenge; Redis exceptions/null results return 503 with Retry-After and a sanitized ProblemDetail. Filter servlet auto-registration is disabled so the check runs in the intended security chain.
- JwtToSecurityUserConverter maps the authorities claim; it does not automatically turn every OAuth scope into a SCOPE_ authority. Machine tokens have no guaranteed human profile.
- API CSRF and CORS are disabled at its resource-server chain; the intended browser boundary is the configured BFF. Direct ingress and public endpoint policy must be reviewed separately.
- Cookie API handling may refresh tokens before its mutation CSRF verification. BFF session mutation endpoints use their earlier dedicated CSRF filter. Do not describe identical ordering for these two request types.
- Login does not rerun on each business call, and JWKS retrieval does not mean auth approves every API operation. A committed business mutation may outlive the caller's HTTP timeout.
These observations document current source behavior. The issuer/audience and revocation changes require deployment of the updated auth/API builds; they do not certify every resource server or historical token as compliant.
Source map for this walkthrough¶
| Responsibility | Current implementation |
|---|---|
| Browser start/callback, refresh and logout | BffAuthenticationFacade |
| BFF custom filter ordering | BffSecurityConfig |
| API cookie/bearer dispatch | GatewayAuthModeFilter |
| Session lookup, conditional renewal, API CSRF and bearer injection | CookieSessionAuthHandler |
| Redis session/JTI/client checks | RedisBffSessionStoreAdapter |
| Routing and streaming proxy | BffRouteRegistry, CisApiReverseProxyFilter |
| API JWT and URL security | ResourceServerSecurityConfig |
| API principal/authorities | JwtToSecurityUserConverter |
| API request-time revocation | RedisTokenRevocationFilter |
| API method authorization support | MethodSecurityConfig, RestPermissionEvaluator |
| Example endpoint and service | ProvinceResource, ProvinceService |
Resource-server hardening and rollout contract¶
This implements the issuer/resource-audience checks described by RFC 9700 section 2.3, the JWT access-token validation guidance, and Spring Security token validator composition. Fail-closed Redis checks are this application's revocation availability policy, not a claim that OAuth mandates a particular Redis design or an HTTP 503 status for every deployment.
OAuth 2.1 remains an IETF draft. Its password grant is omitted. This repository retains the legacy password compatibility flow described in section 4, so these fixes must not be described as whole-system OAuth 2.1 certification or full RFC 9068 JWT-profile compliance. Removal of legacy password clients requires a separate consumer migration; it is not silently disabled by this hardening.
| Variable | Auth | API | Meaning |
|---|---|---|---|
| CIS_AUTH_ISSUER_URI | cis.auth.issuer-uri | cis.auth.issuer-uri | Exact public issuer; host dev 8085, UAT and production auth ingress |
| CIS_AUTH_RESOURCE_AUDIENCE | cis.auth.resource-audience | cis.auth.audience | Stable API resource identifier, currently cis-api |
| CIS_AUTH_JWK_SET_URI | Not used for auth's signing-key storage | cis.auth.jwk-set-uri | Public keys; local Compose uses http://cis-auth:8085/oauth2/jwks |
| CIS_AUTH_REVOKED_TOKEN_PREFIX | cis.auth.redis.revoked-token-prefix | cis.auth.redis.revoked-token-prefix | Shared revocation namespace |
All dev/UAT/prod module files and examples carry these settings. Local Compose overrides API's JWKS back channel to the Docker service while retaining the published public issuer. Issuer validation never substitutes the private JWKS hostname for the public token issuer.
Auth issues the configured API audience only when the token's authorized scopes include read or write. Current API user/client registrations already use these resource scopes; new API consumers must explicitly be registered/requested for them. Metadata-only and openid/profile-only tokens retain their OAuth client audience and are rejected at cis-api. ID tokens do not gain API audience/client_id access claims. Refresh and impersonation use the same access-token customizer. Audience membership does not replace endpoint permissions.
Deploy auth first so newly issued/refreshed API tokens have the resource audience, then API with matching trust settings. Restart both with their environment files. Old access tokens with the former client audience are rejected once API enforcement is active; refresh after auth deployment or start a fresh browser login. There is no permissive legacy audience fallback. A BFF session whose old token is still fresh does not automatically refresh simply because API now returns 401, so fresh sign-in is the reliable rollout path.
Regression coverage includes signed-JWT wrong/missing audience/issuer/claims, bad signature, expired/future token, known JTI/client/legacy-client revocation, Redis exceptions/nulls, anonymous public access, credential-erasure-safe principal mapping, all three environment contracts, and scope-selected audiences across password/code/refresh/client credentials. These tests use local JWKS and mocked Redis transport; live failover and deployment remain separate operational checks.
Page captures for this walkthrough¶
Use the page-by-page notes in section 20 for the internal login, external login, failed login, continuation, expired challenge and signed-out states. No browser connection was available for this update, so actual screen captures remain pending. The embedded fish diagram is an illustration, not a substitute for screenshots or proof of live browser behavior. Add future captures beside the relevant section 20 notes, with build/environment/date and empty credential fields.
23. Component and configuration inventory¶
The following source map and environment bindings are part of this guide. Paths are relative to this document. Inventory checked on 2026-10-19; linked source is authoritative when names or Javadoc promises differ from actual execution. No secret values are included.
cis-auth: 114 production Java source files¶
| Component / source | Responsibility |
|---|---|
| AuditLogPublisher | Source-defined component or port; see linked implementation. |
| AuditLogEntity | Source-defined component or port; see linked implementation. |
| AuditLogEventListener | Auth AUDIT_LOG persistence; details use Map.toString and Async annotation alone does not enable async execution. |
| AuditLogRepository | Source-defined component or port; see linked implementation. |
| CisAuthApplication | Starts auth, enables scheduling/caching and binds CisAuthProperties; no explicit EnableAsync annotation. |
| AuthorizationServerSecurityConfig | Builds the three auth security chains, client/authorization services, token generators, decoders and protocol handlers. |
| BrowserLoginSettings | Bounds pending browser authentication requests independently of the Angular applications. |
| CisAuthProperties | Type-safe, validated configuration properties for the cis-auth Authorization Server. Binds issuer URI, RSA key management, LDAP connection thresholds, Redis namespaces, and security policies. |
| LdapRealmConfig | Spring configuration bean establishing pooled LDAP context source and LdapTemplate for the internal AD realm. |
| AuthCredentialsCommand | Encapsulates raw authentication credentials submitted by an OAuth2 client or user. |
| AuthenticatedUserPrincipal | Represents an authenticated CIS principal containing user identity, roles, provinces, and realm context. |
| AuthRealm | Enumeration identifying CIS authentication realms: INTERNAL (Active Directory LDAP) and EXTERNAL (Oracle DB BCrypt). |
| BrowserLoginContext | Immutable session-bound challenge; authorization destination is captured only from a validated request. |
| CisUserStatus | Lifecycle statuses for CIS users (PENDING, ACTIVE, INACTIVE, LOCKED, DELETED). |
| CisUserType | User classification types across the CIS system (INTERNAL, EXTERNAL, SYSTEM). |
| ClientRegistrationCommand | Inbound command for administrative registration of an OAuth2 client. |
| ClientRegistrationResponseDto | Outbound response DTO containing registered client details and the unhashed raw client secret. Note: The raw secret is only returned once upon registration or rotation. |
| ClientSummaryDto | Summary DTO of an OAuth2 client for query operations (omitting secret hash for security). |
| PublicClientMetadataDto | Public-client discovery payload includes its server-owned authentication realm. |
| RotateSecretCommand | Command to trigger rotation of an OAuth2 client's secret. If newSecret is null or blank, a cryptographically secure secret is generated automatically. |
| RotateSecretResponseDto | Response returned following client secret rotation, exposing the newly generated raw secret. |
| LdapUserProfile | Immutable value object holding user attributes extracted from corporate Active Directory. |
| RsaKeyDescriptor | Cryptographic descriptor holding RSA key pair metadata, public key, private key, and validity status. |
| AuditLogEvent | Source-defined component or port; see linked implementation. |
| AccountLockedException | Domain exception thrown when an authentication attempt is made against a locked user account. |
| AccountPendingOrInactiveException | Domain exception thrown when a user account has not yet been approved or is inactive. |
| CisSecurityDomainException | Base exception for all domain-specific security, authentication, and authorization failures in cis-auth. |
| ClientAlreadyExistsException | Domain exception thrown when attempting to register a client with an already existing clientId. |
| ClientNotFoundException | Domain exception thrown when an OAuth2 client is not found in the registration repository. |
| FirstTimeLoginException | Domain exception thrown when an external user must reset their password on first login. |
| ImpersonationSecurityException | Exception thrown when administrative user impersonation validation fails. |
| InvalidClientRegistrationException | Source-defined component or port; see linked implementation. |
| InvalidCredentialsException | Domain exception thrown when invalid credentials are provided, carrying remaining retry count. |
| LdapUserNotRegisteredException | Domain exception thrown when an LDAP-authenticated user has no corresponding record in the CIS UAM database. |
| PasswordExpiredException | Domain exception thrown when a user's password age exceeds the configured system policy threshold. |
| ImpersonationFacade | Revalidates authenticated admin and target before issuing actor-bearing impersonation credentials. |
| KeyRotationFacade | Serializes active-key replacement, grace deactivation/purge and local rotation event publication. |
| SessionTerminationFacade | Token-possession or admin user revocation across Oracle authorization state and Redis denylist/indexes. |
| CisRoleEntity | JPA Entity mapping the CIS ROLES table. |
| CisSystemConfigEntity | JPA Entity mapping system-wide security thresholds and configuration keys from SYSTEM_CONFIGURATION. |
| CisUserEntity | JPA Entity mapping the core user record in USERS. |
| CisUserPasswordHistoryEntity | JPA Entity tracking historical hashed passwords in USER_PASSWORD_HISTORY to prevent password reuse. |
| CisUserRoleEntity | JPA Entity mapping user-role assignments in USER_ADDITIONAL_ROLE. |
| RsaKeyPairEntity | JPA Entity storing versioned RSA key pairs, active status, and AES-256 encrypted private keys in RSA_KEY_PAIRS. |
| CisRoleRepository | Spring Data JPA repository for querying roles. |
| CisSystemConfigRepository | Spring Data JPA repository for querying system configuration parameters. |
| CisUserPasswordHistoryRepository | Spring Data JPA repository for historical password retrieval. |
| CisUserRepository | Spring Data JPA repository for user lookup by username, email, or user ID. |
| RsaKeyPairRepository | Spring Data JPA repository managing cryptographic key pairs in Oracle DB. |
| ActiveDirectoryLdapPortAdapter | Configured LDAP credential bind and profile extraction behind the LDAP port. |
| AesPrivateKeyCipherAdapter | Spring text encryption for private keys with explicit legacy unencrypted-material fallback. |
| EnabledRegisteredClientRepository | Honors client enabled flag and supplies missing token defaults while preserving explicit stored settings. |
| LdapAuthenticationPort | Port interface defining Active Directory LDAP authentication contract. |
| OracleOAuth2AuthorizationService | Oracle CLOB-aware token lookup, framework authorization mapping, invalidation and refresh-family hooks. |
| PrivateKeyCipherPort | Port interface defining cryptographic cipher operations for asymmetric private keys. |
| RedisTokenRevocationStoreAdapter | Lua-backed user/JTI registration/revocation and persistent client markers; failure is not accepted as verification. |
| RefreshTokenFamilyStore | Hashes consumed refresh tokens into Oracle history and resolves replay families under the mutation lock. |
| RotatingClientSecretEncoder | Current/previous secret hash envelope with bounded credential overlap. |
| RotatingJwtDecoder | Current-key RS256/issuer/time validation plus enabled-client and token/client revocation checks. |
| SecurityMutationLock | Serializes security mutations across auth nodes. The row lock lasts until transaction completion. |
| TokenRevocationStorePort | Port interface defining token and session revocation storage contract. |
| AccountActivePolicyRule | Validates that a user account is in ACTIVE status before permitting token issuance. |
| AccountNonLockedPolicyRule | Validates that a user account is not locked before permitting token issuance. |
| AuthorityClaimEnricher | Enriches JWT tokens with user roles and granted authorities. |
| CompositeJwtTokenCustomizer | JTI/client identity plus ordered user-claim enrichment; refresh/code user policy and role reload. |
| FirstTimeLoginPolicyRule | Validates whether an external user is required to reset their password on first login. |
| IdentityClaimEnricher | Enriches JWT tokens with user ID, username, and email claims. |
| ImpersonationClaimEnricher | Enriches JWT tokens with RFC-8693 actor and impersonation claims when acting on behalf of another user. |
| JwtClaimEnricher | Interface for modular JWT token claim customization steps. |
| PasswordExpiryPolicyRule | Validates that user password age has not exceeded system policy thresholds. |
| ProvinceAndRealmClaimEnricher | Enriches JWT tokens with user province assignment and authentication realm context. |
| UserAccountPolicyRule | Interface for modular user account validation policy rules. |
| BrowserLoginContextService | Creates/resolves/consumes bounded expiring auth HttpSession challenges and revalidates registered client/realm. |
| ClientAuthenticationRealm | Authoritative cis.authentication-realm reader for registered browser clients. |
| ClientManagementPort | Port defining administrative OAuth2 registered client lifecycle operations. |
| ClientManagementService | Transactional client create/read/secret rotation/delete with validation, revocation and auditing. |
| ClientRegistrationPolicy | Validates client methods/grants/scopes/redirects/secrets, browser realm/PKCE and TTL/grace compatibility. |
| RegisteredClientMapper | Constructs complete framework settings for new clients and maps secret-safe summary/registration responses. |
| CachingJwkSourceDecorator | Despite its name, currently delegates current descriptor reads instead of retaining a stale cross-node cache. |
| JwkKeySourcePort | Port interface supplying Nimbus JWKSource and active signing key descriptors. |
| OracleRsaKeyPairJwkSource | Loads current active/grace RSA descriptors and bootstraps signing material as implemented. |
| AuthDomainEventPublisher | Publishes local key/user events and broadcasts user revocation after commit; broadcast failure logs are best effort. |
| RsaKeyRotatedEvent | Domain event fired when an RSA key pair is rotated in the cluster. |
| UserSessionRevokedEvent | Domain event fired when a user session or token is invalidated across the cluster. |
| AuthenticatedPrincipalFactory | Factory constructing AuthenticatedUserPrincipal domain instances from entity records. |
| RsaKeyPairFactory | Factory generating new cryptographically secure 2048-bit RSA key pairs. |
| KeyRotationScheduler | Invokes key rotation on the configured schedule. |
| AuthenticationRealmStrategy | Strategy interface for realm-specific user authentication. |
| BrowserAuthenticationProvider | Authenticates browser challenge context through shared realm rules and returns password-factor authorities. |
| ExternalDbAuthStrategy | Oracle password verification, timing fallback, failed retries/lockout and success reset. |
| InternalLdapAuthStrategy | LDAP verification followed by required Oracle internal CIS registration and policy checks. |
| PasswordGrantAuthenticationConverter | Parses the compatibility password grant into its authentication command/token. |
| PasswordGrantAuthenticationProvider | Validates authenticated client/grant, verifies user through realm strategy and issues/persists tokens. |
| PasswordGrantAuthenticationToken | Authentication token holding password grant credentials in the Spring Security context. |
| PublicRefreshClientAuthentication | Compatibility authentication for public refresh-token requests with registered public-client checks. |
| RealmStrategyRegistry | Selects realm strategy; legacy fallback heuristics are distinct from browser registered-realm binding. |
| RotatingPublicRefreshTokenGenerator | Refresh-token generation for public compatibility while retaining confidential-client generation behavior. |
| AbstractRealmAuthenticationTemplate | Invariant credential/user-type/policy/role/principal sequence; persists external failed attempts across auth errors. |
| AuthExceptionHandlerAdvice | REST domain/security error conversion; separate from browser and OAuth token endpoint presenters. |
| AuthorizationMutationFilter | Coordinates protocol mutations with transaction/shared database lock. |
| AuthorizationRealmFilter | Binds browser authorization/login to registered realm and prevents inappropriate cross-realm session reuse. |
| BrowserAuthenticationDetailsSource | Supplies validated browser login context to the authentication provider. |
| BrowserLoginHandlers | Consumes successful login challenge and resumes saved authorization; routes login failures and restart errors. |
| LoginPageRenderer | Escapes/populates the auth-owned template with realm/client/challenge/CSRF presentation. |
| OAuth2TokenEndpointErrorResponseHandler | Token endpoint OAuth/domain response handling, separate from MVC controller advice. |
| BrowserLoginResource | Serves the realm-specific local sign-in view from a session-bound challenge. |
| ClientManagementResource | REST controller exposing administrative endpoints for programmatic OAuth2 client registration and lifecycle management. |
| ImpersonationResource | REST controller providing administrative user impersonation endpoints. |
| KeyRotationResource | REST controller exposing administrative endpoints for manual RSA key rotation. |
| PublicClientMetadataResource | Scope-protected enabled/realm-aware PKCE metadata; public and confidential-basic clients, never secrets. |
| SessionRevocationResource | REST controller exposing endpoints for token and user session revocation. |
| ImpersonateUserRequestVm | Request payload for administrative user impersonation. |
| RevokeTokenRequestVm | View model payload for token revocation requests. |
| RevokeUserSessionsRequestVm | View model payload for user session revocation requests. |
cis-bff: 43 production Java source files¶
| Component / source | Responsibility |
|---|---|
| BffAuditEvent | Immutable domain event representing an auditable security or session lifecycle event in CIS-BFF. Encapsulates the security action, identity of the principal, target session, |
| BffAuditLogListener | Asynchronous BFF event logging, not database audit persistence. |
| BffAuditLogPublisher | Publisher service dispatching security audit events across the CIS-BFF boundary. Decouples security-critical components such as the authentication facade and |
| CisBffApplication | Starts the servlet BFF, binds properties and enables asynchronous event handling. |
| BffCorsSettings | Explicit environment-backed cross-origin policy for BFF browser clients. |
| BffOAuthSettings | Public browser endpoints are independent of private back-channel routing. |
| BffSecurityConfig | Credentialed CORS, custom-filter ordering, problem handlers and disabled duplicate servlet registrations. |
| CisBffProperties | Type-safe, validated configuration properties for the cis-bff Dual-Mode Gateway. Binds upstream service URLs, multi-service route definitions, OAuth2 client credentials per realm, |
| RedisPubSubConfig | Spring configuration establishing Redis Pub/Sub subscription for auth domain events. Binds RedisAuthEventSubscriber to the cluster-wide revocation channel. |
| BffAuthorizationCodeCommand | Legacy SPA code-exchange payload, distinct from the GET BFF-owned callback. |
| BffAuthorizationTransaction | Immutable Redis state, PKCE verifier, client/callback, expiry/remember choice and server-selected frontend URI. |
| BffImpersonateCommand | Command payload for requesting administrative user impersonation in the BFF. |
| BffLoginCommand | Legacy password request and sanitized nested user-profile response; does not expose raw OAuth tokens in the profile. |
| BffSessionState | Immutable token-bearing Redis session and impersonation link; determines refresh need and produces refreshed copies. |
| OAuthTokenExchangeResult | Immutable representation of an OAuth2 token exchange response from cis-auth. |
| PublicClientMetadata | Public-client metadata obtained from the authenticated authorization server. |
| BffLdapUserNotRegisteredException | Exception thrown when an LDAP user authenticates successfully against Active Directory but does not yet possess a corresponding user profile in the CIS database. |
| BffSecurityException | Domain exception thrown when BFF authentication, session lookup, or CSRF verification fails. Carries an error code, target HTTP status, message, and contextual domain attributes |
| BffAuthenticationFacade | Owns browser start/callback, session establishment/read/refresh/logout, compatibility login and impersonation. |
| AuthServerClientPort | Port interface defining back-channel HTTP communications between cis-bff and cis-auth. Encapsulates OAuth2 password grant exchange, refresh token renewal, and token revocation. |
| BffSessionStorePort | Port interface defining Redis session persistence operations for cis-bff. Isolates core BFF session logic from the underlying Redis storage mechanics. |
| RedisBffSessionStoreAdapter | Custom Redis session/index/transaction/remember persistence and owner-checked refresh Lua operations. |
| RestAuthServerClientAdapter | Back-channel service/password/code/refresh requests, revocation notification, impersonation and OAuth error translation. |
| BearerPassThroughAuthHandler | Passes bearer-only REST calls through; does not validate JWT or create a BFF Spring principal. |
| CookieSessionAuthHandler | Session/CSRF check, refresh and request wrapper that enumerates/injects Authorization and strips Cookie headers. |
| GatewayAuthModeHandler | Handler interface for Dual-Mode Gateway authentication dispatching. Evaluates whether an incoming HTTP request should be processed as an Angular SPA Cookie |
| RedisAuthEventSubscriber | Best-effort revocation-event deserialization and indexed BFF session eviction; failures are logged. |
| BffCookieFactory | Creates/clears session, CSRF and OAuth-state cookies from configured attributes. |
| DownstreamServicesHealthIndicator | Auth/API probes; overall health is auth-driven and API result appears in details. |
| RedisSessionStoreHealthIndicator | Reports BFF session-store probe health; not proof an end-to-end login succeeds. |
| BffGatewayMetrics | Proxy latency/request counters and rate-limit rejection metric registration. |
| PublicClientRegistry | Authenticated PKCE-client discovery with bounded in-memory TTL/stale grace; never retrieves client secrets. |
| BffResilienceManager | Per-route circuit-breaker registry and execution wrapper; transport exceptions differ from HTTP error statuses. |
| BffRouteRegistry | Pattern-based route selection, prefix manipulation, target/query construction and API fallback. |
| BffExceptionHandlerAdvice | ProblemDetail conversion for MVC, domain, dependency and security failures; preserves framework status/header semantics. |
| BffExceptionTranslationFilter | Routes uncommitted filter exceptions to MVC advice without rewriting committed responses. |
| BffRateLimitingFilter | Atomic fixed-window Redis counters and 429 responses; depends on trusted forwarded-IP ingress handling. |
| BffSecurityHeadersFilter | Applies browser/security headers and no-store controls to auth/API responses. |
| BffSessionCsrfFilter | Protects browser session mutations separately from API cookie-mode CSRF and PKCE callbacks. |
| CisApiReverseProxyFilter | Java HTTP proxy, headers/body/status streaming, timeout/transport classification and gateway metrics. |
| CorrelationIdFilter | Bounds/sanitizes or generates correlation ID, returns it and manages MDC cleanup. |
| GatewayAuthModeFilter | Chooses cookie mode before bearer mode on /api/**; permits anonymous forwarding when neither applies. |
| BffAuthResource | HTTP adapter for BFF browser/session/compatibility endpoints; delegates orchestration to the facade. |
Environment placeholders and their consumers¶
These names are read from application.yaml; values belong in each module .env.dev, .env.uat or .env.prod (with tracked .example templates). This inventory records bindings, not live secrets or an assurance that all templates are configured for your deployment. Direct annotation/property lookups and operational JVM/container settings must also be checked when changing runtime configuration. The main reference explains key groups.
cis-auth YAML bindings¶
| Environment variable | Application property |
|---|---|
| CIS_AUTH_CLIENT_SECRET_OVERLAP | cis.auth.client-secret-overlap |
| CIS_AUTH_DEFAULT_MAX_PASSWORD_RETRIES | cis.auth.policy.default-max-password-retries |
| CIS_AUTH_DEFAULT_PASSWORD_MAX_AGE_DAYS | cis.auth.policy.default-password-max-age-days |
| CIS_AUTH_DEFAULT_REVOCATION_TTL | cis.auth.redis.default-revocation-ttl |
| CIS_AUTH_ISSUER_URI | cis.auth.issuer-uri |
| CIS_AUTH_RESOURCE_AUDIENCE | cis.auth.resource-audience |
| CIS_AUTH_LOGIN_CONTEXT_TTL | cis.auth.browser-login.context-ttl |
| CIS_AUTH_LOGIN_MAX_PENDING | cis.auth.browser-login.max-pending |
| CIS_AUTH_REVOCATION_CHANNEL | cis.auth.redis.revocation-channel |
| CIS_AUTH_REVOKED_TOKEN_PREFIX | cis.auth.redis.revoked-token-prefix |
| CIS_AUTH_USER_SESSIONS_PREFIX | cis.auth.redis.user-sessions-prefix |
| FLYWAY_ENABLED | spring.flyway.enabled |
| HIBERNATE_FORMAT_SQL | spring.jpa.properties.hibernate.format_sql |
| HIKARI_CONNECTION_TIMEOUT | spring.datasource.hikari.connection-timeout |
| HIKARI_IDLE_TIMEOUT | spring.datasource.hikari.idle-timeout |
| HIKARI_LEAK_DETECTION_THRESHOLD | spring.datasource.hikari.leak-detection-threshold |
| HIKARI_MAX_LIFETIME | spring.datasource.hikari.max-lifetime |
| HIKARI_MAX_POOL_SIZE | spring.datasource.hikari.maximum-pool-size |
| HIKARI_MIN_IDLE | spring.datasource.hikari.minimum-idle |
| HIKARI_POOL_NAME | spring.datasource.hikari.pool-name |
| HIKARI_VALIDATION_TIMEOUT | spring.datasource.hikari.validation-timeout |
| LDAP_BASE_DN | cis.auth.ldap.base-dn |
| LDAP_CONNECT_TIMEOUT_MS | cis.auth.ldap.connect-timeout-ms |
| LDAP_ENABLED | cis.auth.ldap.enabled |
| LDAP_MANAGER_DN | cis.auth.ldap.manager-dn |
| LDAP_MANAGER_PASSWORD | cis.auth.ldap.manager-password |
| LDAP_READ_TIMEOUT_MS | cis.auth.ldap.read-timeout-ms |
| LDAP_URL | cis.auth.ldap.url |
| LDAP_USER_SEARCH_BASE | cis.auth.ldap.user-search-base |
| LDAP_USER_SEARCH_FILTER | cis.auth.ldap.user-search-filter |
| MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE | management.endpoints.web.exposure.include |
| MANAGEMENT_HEALTH_SHOW_DETAILS | management.endpoint.health.show-details |
| REDIS_HOST | spring.data.redis.host |
| REDIS_PASSWORD | spring.data.redis.password |
| REDIS_PORT | spring.data.redis.port |
| REDIS_TIMEOUT | spring.data.redis.timeout |
| RSA_ENCRYPTOR_PASSWORD | cis.auth.keys.encryptor-password |
| RSA_ENCRYPTOR_SALT | cis.auth.keys.encryptor-salt |
| RSA_KEY_GRACE_PERIOD | cis.auth.keys.grace-period |
| RSA_KEY_ROTATION_CRON | cis.auth.keys.rotation-cron |
| RSA_KEY_SIZE_BITS | cis.auth.keys.key-size-bits |
| SERVER_COMPRESSION_ENABLED | server.compression.enabled |
| SERVER_PORT | server.port |
| SPRING_DATASOURCE_PASSWORD | spring.datasource.password |
| SPRING_DATASOURCE_URL | spring.datasource.url |
| SPRING_DATASOURCE_USERNAME | spring.datasource.username |
| VIRTUAL_THREADS_ENABLED | spring.threads.virtual.enabled |
cis-bff YAML bindings¶
| Environment variable | Application property |
|---|---|
| AUTH_SERVER_URL | cis.bff.auth-server-base-url |
| CIRCUIT_BREAKER_ENABLED | cis.bff.resilience.circuit-breaker-enabled |
| CIRCUIT_BREAKER_FAILURE_RATE_THRESHOLD | cis.bff.resilience.failure-rate-threshold |
| CIRCUIT_BREAKER_OPEN_WAIT | cis.bff.resilience.wait-duration-in-open-state |
| CIRCUIT_BREAKER_SLOW_CALL_THRESHOLD | cis.bff.resilience.slow-call-duration-threshold |
| CIS_API_URL | cis.bff.api-server-base-url |
| CIS_API_URL | cis.bff.routes.target-url |
| CIS_BFF_ALLOW_INSECURE_BACK_CHANNEL | cis.bff.allow-insecure-back-channel |
| CIS_BFF_API_PATH_PATTERN | cis.bff.routes.path-pattern |
| CIS_BFF_API_PREFIX_TO_STRIP | cis.bff.routes.prefix-to-strip |
| CIS_BFF_API_ROUTE_ID | cis.bff.routes.id |
| CIS_BFF_API_STRIP_PREFIX | cis.bff.routes.strip-prefix |
| CIS_BFF_API_TIMEOUT | cis.bff.routes.timeout |
| CIS_BFF_AUTHORIZATION_BASE_URL | cis.bff.authorization-base-url |
| CIS_BFF_CALLBACK_URI | cis.bff.callback-uri |
| CIS_BFF_CORS_ALLOWED_HEADERS | cis.bff.cors.allowed-headers |
| CIS_BFF_CORS_ALLOWED_METHODS | cis.bff.cors.allowed-methods |
| CIS_BFF_CORS_ALLOWED_ORIGIN_PATTERNS | cis.bff.cors.allowed-origin-patterns |
| CIS_BFF_CORS_ALLOW_CREDENTIALS | cis.bff.cors.allow-credentials |
| CIS_BFF_CORS_EXPOSED_HEADERS | cis.bff.cors.exposed-headers |
| CIS_BFF_EXTERNAL_CLIENT_ID | cis.bff.external-client.client-id |
| CIS_BFF_EXTERNAL_CLIENT_SCOPE | cis.bff.external-client.default-scope |
| CIS_BFF_EXTERNAL_FRONTEND_URL | cis.bff.external-frontend-url |
| CIS_BFF_EXTERNAL_SECRET | cis.bff.external-client.client-secret |
| CIS_BFF_INTERNAL_CLIENT_ID | cis.bff.internal-client.client-id |
| CIS_BFF_INTERNAL_CLIENT_SCOPE | cis.bff.internal-client.default-scope |
| CIS_BFF_INTERNAL_FRONTEND_URL | cis.bff.internal-frontend-url |
| CIS_BFF_INTERNAL_SECRET | cis.bff.internal-client.client-secret |
| CIS_BFF_METADATA_CACHE_TTL | cis.bff.metadata.cache-ttl |
| CIS_BFF_METADATA_CLIENT_ID | cis.bff.metadata.client-id |
| CIS_BFF_METADATA_CLIENT_SECRET | cis.bff.metadata.client-secret |
| CIS_BFF_METADATA_SECRET_FILE | cis.bff.metadata.secret-file |
| CIS_BFF_METADATA_STALE_GRACE | cis.bff.metadata.stale-grace |
| CIS_BFF_PUBLIC_CLIENT_ID | cis.bff.public-client.client-id |
| CIS_BFF_PUBLIC_CLIENT_SCOPE | cis.bff.public-client.default-scope |
| CIS_BFF_PUBLIC_REDIRECT_URI | cis.bff.public-client.redirect-uri |
| CIS_BFF_REFRESH_SKEW | cis.bff.redis.refresh-skew |
| CIS_BFF_REMEMBER_ME_TTL | cis.bff.remember-me-ttl |
| CIS_BFF_REVOCATION_CHANNEL | cis.bff.redis.revocation-channel |
| CIS_BFF_REVOKED_TOKEN_PREFIX | cis.bff.redis.revoked-token-prefix |
| CIS_BFF_SESSION_KEY_PREFIX | cis.bff.redis.session-key-prefix |
| CIS_BFF_SESSION_TTL | cis.bff.redis.session-ttl |
| CIS_BFF_USER_SESSIONS_KEY_PREFIX | cis.bff.redis.user-sessions-key-prefix |
| CIS_BFF_WORKFLOW_PATH_PATTERN | cis.bff.routes.path-pattern |
| CIS_BFF_WORKFLOW_PREFIX_TO_STRIP | cis.bff.routes.prefix-to-strip |
| CIS_BFF_WORKFLOW_ROUTE_ID | cis.bff.routes.id |
| CIS_BFF_WORKFLOW_STRIP_PREFIX | cis.bff.routes.strip-prefix |
| CIS_BFF_WORKFLOW_TIMEOUT | cis.bff.routes.timeout |
| CIS_WORKFLOW_URL | cis.bff.routes.target-url |
| COOKIE_CSRF_HEADER_NAME | cis.bff.cookie.csrf-header-name |
| COOKIE_CSRF_NAME | cis.bff.cookie.csrf-cookie-name |
| COOKIE_MAX_AGE | cis.bff.cookie.max-age |
| COOKIE_PARTITIONED | cis.bff.cookie.partitioned |
| COOKIE_SAME_SITE | cis.bff.cookie.same-site |
| COOKIE_SECURE | cis.bff.cookie.secure |
| COOKIE_SESSION_NAME | cis.bff.cookie.session-cookie-name |
| MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE | management.endpoints.web.exposure.include |
| MANAGEMENT_HEALTH_SHOW_DETAILS | management.endpoint.health.show-details |
| RATE_LIMIT_ENABLED | cis.bff.rate-limit.enabled |
| RATE_LIMIT_KEY_PREFIX | cis.bff.rate-limit.key-prefix |
| RATE_LIMIT_LOGIN_RPM | cis.bff.rate-limit.login-requests-per-minute |
| RATE_LIMIT_RPM | cis.bff.rate-limit.requests-per-minute |
| REDIS_HOST | spring.data.redis.host |
| REDIS_PASSWORD | spring.data.redis.password |
| REDIS_PORT | spring.data.redis.port |
| REDIS_TIMEOUT | spring.data.redis.timeout |
| SERVER_PORT | server.port |
| VIRTUAL_THREADS_ENABLED | spring.threads.virtual.enabled |
Configuration maintenance rules¶
- Browser callback/portal URLs are independent from the private auth back channel and token issuer.
- Internal/external BFF client IDs and secrets must match their Oracle registrations. Metadata service credentials are separate.
- BFF CORS is selected by environment and does not register OAuth redirects.
- Redis password, database/address and key prefixes must agree among the actual writers/readers; similar variable names are not proof.
- Signing-key encryption password/salt must remain compatible across nodes and existing encrypted rows.
- Access-token lifetime must fit key grace; token-settings JSON must contain typed framework defaults.
- Flyway histories are module-specific. Never edit applied versioned migrations to correct seed settings.
- Do not paste .env credentials, private keys or real OAuth tokens into examples or troubleshooting output.
24. External-user passkeys: complete flow and rollout¶
Passkeys are optional for external CIS accounts. Internal users continue to authenticate with LDAP. Existing password grants, password login, OAuth authorization code/PKCE, refresh, BFF cookies and API bearer contracts remain available.
The Gradle version catalog owns spring-security-webauthn and spring-session-data-redis. Their versions come from the existing Spring Boot dependency platform; cis-auth uses the catalog aliases without independent version pins.
Fishbone overview¶
Read the spine from left to right. Branches identify the controls at each stage. Enrollment is a prerequisite for first use; later sign-ins use an existing credential.

Open scalable SVG. The diagram describes source behavior, not a deployed browser capture.
What each branch guarantees¶
| Branch | What happens | Why it matters |
|---|---|---|
| Enrollment | The user proves the existing password, selects management, and creates a discoverable credential with local user verification. | An unattended old session or a passkey-only session cannot silently add another credential. |
| Account and realm | CIS resolves the opaque credential handle to a stable user ID and reloads current external account policies and roles. | A previously enrolled key cannot bypass account disablement, onboarding or realm boundaries. Username changes do not transfer credential ownership. |
| Browser and origin | The ceremony runs on the authentication host over HTTPS, with configured origins/RP ID, CSRF protection and a bounded JSON body. | A credential signed for a different site, challenge or relying party cannot authenticate here. Biometric verification stays on the device. |
| Credential and challenge | Oracle holds durable credential records; Redis holds expiring browser-bound ceremonies. GETDEL consumes a ceremony once. Oracle row locks serialize authentication/revocation. | Replayed or cross-browser submissions fail, and concurrent revocation cannot be overwritten by a stale credential save. |
| OAuth continuation | Only the original validated authorization request resumes, using the existing CIS principal, state, redirect URI and PKCE flow. | Applications keep their existing OAuth/BFF contracts and do not need to receive WebAuthn assertions or biometric information. |
| Operations and recovery | Operators enable the feature deliberately, keep password recovery available, and use credential revocation and existing session termination controls. | Lost devices, compromised credentials, rollback and ordinary LDAP users have explicit paths. |
Authentication decision flow¶
flowchart TD
Start["Application starts existing OAuth authorization"] --> Realm{"External realm?"}
Realm -->|No| LDAP["Existing internal LDAP login"]
Realm -->|Yes| Flag{"Passkeys enabled?"}
Flag -->|No| Password["Existing external password login"]
Flag -->|Yes| Choice{"User chooses a method"}
Choice -->|Password| Password
Choice -->|Passkey| Options["Validate browser context and CSRF; issue challenge"]
Password --> Manage{"Manage passkeys selected?"}
Manage -->|No| OAuth["Existing authorization code and BFF callback"]
Manage -->|Yes| Recent["Require recent password, own external account and no impersonation"]
Recent --> Create["Create credential with required local user verification"]
Create --> Register["Consume ceremony; verify attestation; store public credential"]
Register --> Continue["User selects Continue"]
Continue --> OAuth
Options --> Device["Browser selects credential and requests local verification"]
Device --> Assertion{"Valid signed assertion?"}
Assertion -->|No or cancelled| Retry["Fresh challenge or password fallback"]
Retry --> Choice
Assertion -->|Yes| Account{"Current external account policies pass?"}
Account -->|No| Reject["Reject sign-in; existing recovery or account process"]
Account -->|Yes| Session["Rotate session and CSRF; save CIS principal and WebAuthn factor"]
Session --> OAuth
LDAP --> OAuth
Detailed enrollment flow¶
sequenceDiagram
actor User
participant App as Application / BFF
participant Auth as cis-auth browser login
participant Device as Browser / authenticator
participant Redis as Shared Redis
participant DB as Oracle
User->>App: Start external sign-in
App->>Auth: Existing authorization request (state, redirect, PKCE)
Auth->>Auth: Validate client and external realm
Auth->>Redis: Store auth-host session and pending login context
Auth-->>User: Password form and manage-passkeys option
User->>Auth: Password + management option + CSRF token
Auth->>DB: Verify password, check current account policies and roles
Auth->>Auth: Rotate session, bind browser revocation version
Auth-->>User: Passkey management page
User->>Auth: POST register/options + CSRF
Auth->>Auth: External owner, current session, recent password, no impersonation
Auth->>DB: Get/create opaque user handle
Auth->>Redis: Store expiring registration options for browser and user
Auth-->>Device: RP, user handle, random challenge, required UV/resident key
Device->>User: Ask for local PIN / fingerprint / face verification
Device->>Device: Create credential and keep private key
Device->>Auth: POST register/verify + attestation + label + CSRF
Auth->>Redis: Atomically consume registration ceremony
Auth->>DB: Lock user handle, check ownership and credential quota
Auth->>Auth: Verify challenge, origin, RP, algorithm, UP and UV
Auth->>DB: Store credential public material
Auth->>Auth: Publish lifecycle audit event
Auth-->>User: Credential added, continue link
User->>Auth: Continue captured authorization request
Auth-->>App: Existing OAuth code / callback flow
The enrollment request never accepts an authoritative user ID from the browser. The current authenticated CIS principal determines ownership. Options expose the account's username for the authenticator's account picker, while durable ownership uses the stable CIS ID and an opaque handle. No anonymous registration or internal enrollment endpoint is provided.
Detailed passkey sign-in flow¶
sequenceDiagram
actor User
participant App as Application / BFF
participant Auth as cis-auth
participant Device as Browser / authenticator
participant Redis as Shared Redis
participant DB as Oracle
User->>App: Start external sign-in
App->>Auth: Existing authorization request
Auth->>Auth: Validate enabled client, realm, redirect and PKCE parameters
Auth->>Redis: Capture browser login context
Auth-->>User: Existing login page with Use a passkey
User->>Auth: POST login/options + login_challenge + CSRF
Auth->>Redis: Store random, expiring assertion challenge bound to browser/context
Auth-->>Device: Request options (RP ID, challenge, required UV)
Device->>User: Choose a credential and verify locally
Device->>Device: Sign authenticator data and client-data hash
Device->>Auth: POST login/verify + assertion + CSRF
Auth->>Redis: Atomically consume the pending ceremony
Auth->>DB: Lock active credential and resolve its stable owner
Auth->>Auth: Verify userHandle, signature, challenge, origin, RP, UP and UV
Auth->>Auth: Check counter and backup flags
Auth->>DB: Reload external account status, policies and current roles
Auth->>DB: Update credential usage, audit successful sign-in
Auth->>Auth: Revalidate/consume captured OAuth context
Auth->>Redis: Rotate session ID and CSRF, save CIS principal with WebAuthn factor
Auth-->>Device: Same-origin captured authorization continuation
Device->>Auth: Navigate to original authorization request
Auth-->>App: Existing authorization code and state
App->>Auth: Existing code exchange with PKCE verifier
Auth-->>App: Existing tokens
App-->>User: Existing application session
Discoverable login sends no username lookup request. Credential selection happens on the device, then CIS checks that the returned user handle owns the selected credential. A successful login has the WebAuthn factor, not the password factor. Password and WebAuthn timestamps both satisfy OAuth max_age; only a recent password factor permits credential changes.
Failure, recovery and revocation paths¶
| Situation | Server behavior | User/operator path |
|---|---|---|
| Unsupported browser or public HTTP host | Passkey controls cannot start a ceremony. | Use the existing password flow; use HTTPS, or the exact HTTP localhost development exception. |
| Device prompt cancelled or timed out | No successful authentication is installed. | Retry to obtain a fresh challenge, or use the password. |
| Expired, replaced or already consumed ceremony | Verification fails; a consumed challenge cannot be reused. | Request new options. Multiple attempts in the same context replace the pending ceremony. |
| Wrong origin, RP ID, signature, challenge, UP/UV or owner handle | Reject the assertion with a uniform error. | Restart sign-in; investigate repeated failures through normal security monitoring. |
| Internal realm or internal account | Reject passkey enrollment/login for that realm/account. | Continue LDAP authentication. |
| Disabled, locked, unapproved or reset/expiry-blocked external account | Current account policies reject sign-in; Oracle credential usage changes roll back. | Resolve the account condition through the existing account/password process. |
| Stale password, passkey-only or impersonated management session | Reject enrollment/revocation. | Sign out and start an external password login with the management option. |
| Another user's credential ID is submitted for revocation | Ownership check rejects it. | Manage only credentials listed for the current user. |
| Lost device | Another enrolled passkey or password remains usable. | Log in with the fallback and revoke the lost credential. |
| Credential compromise | Revocation retains a tombstone and blocks future use. | Also invoke existing session termination if active sessions/tokens may be compromised. |
| Redis unavailable | Ceremony/session operations fail closed; no substitute local challenge cache is used. | Restore Redis; password browser sessions also depend on shared Redis while enabled. |
| Oracle unavailable | Credential/account operations fail; no successful session is installed. | Restore database service and retry. |
| Non-increasing counter on a single-device credential | Reject when a nonzero counter fails to increase. | Investigate or recover using another credential/password. |
| Synced credential has a zero counter | Fresh signed ceremonies can succeed with zero counters. | This is expected for supported synced passkeys; replay protection still comes from one-use challenges. |
| Feature rolled back | Passkey endpoints and shared-session configuration are removed by the flag; credential records remain. | Restart existing password login; preserve Oracle data for later re-enablement. |
Account recovery is intentionally the existing recovery process. This implementation adds audit lifecycle events, not automatic email notifications or a separate recovery-code system.
State ownership and trust boundaries¶
| Component | Owns | Does not own |
|---|---|---|
| Device / passkey provider | Private key, local biometric/PIN verification and any provider-managed synchronization | CIS roles, account status or OAuth authorization decisions |
| Auth-host browser session | CIS principal, authentication factor/time, captured client/realm/redirect, browser revocation version and CSRF state | Authenticator private key or biometric templates |
| Oracle | Opaque identity handles, public credential material, counters/backup flags, usage metadata, revocation tombstones, users/roles/policies and existing OAuth records | Pending WebAuthn challenge expiry/consumption |
| Redis | Shared auth-host sessions, expiring one-use ceremonies, existing rate limits and revocation state | Permanent credential ownership |
| Application / BFF | Existing state/PKCE verification, OAuth callback, tokens and application session handling | Direct validation of WebAuthn signatures or storage of biometric data |
Registration and authentication cryptography use the Spring WebAuthn4J relying-party implementation. CIS adds realm/account policy, stable identity mapping, challenge/session binding, ownership, quota, current-counter handling and existing OAuth continuation. Authentication and revocation lock the credential row; registration locks the stable user-handle row to enforce the active-key limit under concurrency.
User flow¶
- Start sign-in from the application as usual.
- On the external authentication page, select Manage passkeys after password sign-in, then sign in with the existing password.
- Add a named passkey on the authentication host, complete the device prompt, then select Continue to your application.
- On subsequent sign-ins, select Use a passkey. The browser offers registered discoverable credentials and local device verification. Password login remains available.
- To list or revoke a credential, repeat the password sign-in with the management option. Changes require a password authentication within five minutes by default. A passkey-only session cannot enroll another passkey.
An account can hold up to ten active credentials by default. Register a backup device or synced passkey. CIS stores public credential material, not biometrics or authenticator private keys. Account onboarding, forced password reset, password expiry, disabled/locked status and external realm eligibility are checked again before passkey sign-in succeeds.
Revocation blocks future use of that credential. It does not terminate existing application sessions; use the existing session termination controls when compromise is suspected. Existing password recovery remains the fallback. Impersonated sessions cannot manage passkeys.
Deployment¶
The feature is off by default. Configure the target cis-auth/.env.<environment> file, which is already consumed by local and deployment Compose env_file entries:
CIS_AUTH_PASSKEYS_ENABLED=true
CIS_AUTH_PASSKEYS_RP_ID=auth.example.org
CIS_AUTH_PASSKEYS_ALLOWED_ORIGINS=https://auth.example.org
CIS_AUTH_PASSKEYS_CHALLENGE_TTL=PT3M
CIS_AUTH_PASSKEYS_RECENT_AUTHENTICATION=PT5M
CIS_AUTH_PASSKEYS_MAX_CREDENTIALS=10
Replace example values with the actual stable public authentication hostname. Origins have a scheme and optional port, with no path or trailing slash. Wildcards are rejected. Use separate RP IDs for UAT and production. Changing an RP ID later generally requires users to enroll again. Public hosts require HTTPS. The only HTTP exception is exact localhost with RP ID localhost, following the WebAuthn localhost secure-context exception.
For local IDE testing on port 8085, set these values in cis-auth/.env.dev, restart cis-auth, then begin a new external login from the application:
CIS_AUTH_PASSKEYS_ENABLED=true
CIS_AUTH_PASSKEYS_RP_ID=localhost
CIS_AUTH_PASSKEYS_ALLOWED_ORIGINS=http://localhost:8085
The external login page then displays Use a passkey and Manage passkeys after password sign-in. Enroll first using the password and management option. Restarting replaces the auth-host session setup, so do not reuse an old login_challenge URL. Keep localhost consistent; IP addresses and LAN hostnames do not receive this HTTP exception. The checked-in dev example stays disabled until explicitly enabled.
Apply auth migration V8__external_passkeys.sql through the auth Flyway runner (FLYWAY_SCHEMA_HISTORY_AUTH) before enabling. It adds AUTH_PASSKEY_USER and AUTH_PASSKEY_CREDENTIAL; no existing user records or applied migrations are modified. Credential JSON is a CLOB, credential IDs are indexed by SHA-256, and revoked records are retained.
When enabled, auth-host HTTP sessions are stored in Redis under cis:auth:http-session, with a 30-minute inactivity timeout and the host-only CIS_AUTH_SESSION cookie (Secure, HttpOnly, SameSite=Lax). Only the validated HTTP localhost development origin omits Secure so its cookie can round-trip over local HTTP; public HTTPS deployments retain it. Existing auth-host sessions need a fresh login at the switch. BFF session storage is unchanged. Replicas must use the same Redis and compatible session-serialized classes; treat an incompatible rolling upgrade as requiring reauthentication.
Ceremonies use a separate cis:auth:passkeys namespace and atomic Redis GETDEL consumption. Redis 6.2 or newer is required. Redis must be private, authenticated, monitored and shared by all auth replicas. Redis failures fail authentication closed. Protect transport according to the existing Redis deployment policy. Rolling back the feature flag removes passkey access without deleting credential data.
The existing direct-auth Redis request limiter also covers passkey endpoints. JSON bodies are limited to 64 KiB, CSRF protection is required on every mutation, and challenges expire server-side. Repeated options requests replace the pending ceremony for that browser/context. Challenges are bound to the browser, purpose and captured OAuth client/realm; management additionally binds to the current user. User verification is required at registration and authentication.
PASSKEY_REGISTERED, PASSKEY_LOGIN and PASSKEY_REVOKED use the existing audit event pipeline. Route lifecycle events to operational monitoring as appropriate. This feature does not introduce an email delivery service or a new account recovery mechanism.
HTTP surface¶
All endpoints are on the authentication host, not the resource API or an Angular origin.
| Endpoint | Access |
|---|---|
POST /passkeys/login/options?login_challenge=... |
External browser authorization context + CSRF |
POST /passkeys/login/verify?login_challenge=... |
Same context + one-use challenge + signed assertion + CSRF |
GET /passkeys |
Current external browser session |
GET /passkeys/credentials |
Own credentials in a current external browser session |
POST /passkeys/register/options |
Recent password-authenticated external browser session + CSRF |
POST /passkeys/register/verify |
Same session, stored registration challenge and CSRF |
POST /passkeys/revoke |
Recent password-authenticated external owner + CSRF |
Login uses Spring Security's WebAuthn4J relying-party verifier, then installs the existing CIS principal with FACTOR_WEBAUTHN. It rotates the session ID and CSRF state, binds the existing browser revocation version and resumes only the captured authorization request. OAuth max_age recognizes both password and WebAuthn authentication times. Enrollment always requires the password factor.
Validation¶
Run from the repository root:
./gradlew.bat :cis-auth:test --tests '*Passkey*Test' --tests '*AuthorizationCodeSecurityIntegrationTest'
./gradlew.bat :cis-auth:test :cis-bff:test
Oracle and Redis integration tests require Docker. The software authenticator tests generate real ES256 signatures and none attestation. Browser-chain tests cover registration, credential listing/revocation, OAuth continuation, session fixation, CSRF, realm isolation and replay. Container tests exercise Oracle CLOB persistence/rollback/revocation and Redis session serialization, challenge expiry and atomic consumption.
Before enabling in UAT, perform an HTTPS browser check using Windows Hello, a mobile synced passkey and an alternate browser/device. Verify password fallback, internal LDAP login, application callback, refresh, logout, revoked credentials and account disablement. Automated server tests do not certify the physical device UX or the deployed proxy/cookie/domain configuration.
Application security remediation¶
Date: 2026-10-25. Scope: the four application-level remediation areas approved after the auth/BFF audit. LDAP transport, ingress/network configuration and public metrics exposure are deferred. Existing unrelated working-tree changes were preserved.
Implemented behavior¶
| Finding | Change |
|---|---|
| AUTH-BFF-01 | 34 state-changing GET routes now require POST. Cookie-mode POST already requires the session CSRF header. Converted List Management updates explicitly require authentication before the public reference-data matcher. |
| AUTH-BFF-03 | BFF counters use the servlet peer address and ignore raw X-Forwarded-For. |
| AUTH-BFF-04 | A pre-authentication servlet filter limits direct auth login, authorization initiation, token and revocation traffic. Defaults: 120 requests per peer per minute; 20 credential submissions per normalized account per minute. Redis failure returns 503. |
| AUTH-BFF-05 | Missing/wrong/locked credentials receive generic auth and BFF responses without retry counters or lock metadata. Locked accounts perform password work instead of an immediate fast-path failure. Verified-credential LDAP onboarding and first-login/password-expiry actions remain supported. |
| AUTH-BFF-06 | Logout atomically queues remote revocation, blacklists the current JTI and removes the local session/refresh lease in Redis. Remote failures return 503/REVOCATION_PENDING while cookies are cleared. A worker retries every five seconds and removes work only after success. |
| AUTH-BFF-07 | Browser authentication records a Redis-backed per-user generation. Token logout, replay-family revocation and administrative revoke-user invalidate stale browser SSO. Affected browsers must authenticate again. |
| AUTH-BFF-08 | Audit publication strips reusable session IDs and sensitive detail fields before dispatch. Refresh/deserialization logs omit session credentials. |
Client contract changes¶
These routes keep their path/parameters but change GET -> POST. Cookie callers must send the existing session CSRF header (COOKIE_CSRF_HEADER_NAME, normally X-XSRF-TOKEN). No mutating GET alias is retained. Some former GET paths may match an existing numeric-ID reader and return 400 instead of 405; tests verify rejection before any service interaction. Callers outside this repository have not been changed.
| Endpoint | Method |
|---|---|
/api/v1/archive/checkoutHRADraft |
POST |
/api/v1/archive/checkoutPSDTDraft |
POST |
/api/v1/cart/empty |
POST |
/api/v1/cart/removeCartItem |
POST |
/api/v1/dispatch/sendDispatchEmail/{workflowId} |
POST |
/api/v1/dispatch/uploadDispatchDocsToFtp |
POST |
/api/v1/list-master/update |
POST |
/api/v1/list-master/updateDefault |
POST |
/api/v1/lodgement/addLdgStepRequestForSectionalTitle |
POST |
/api/v1/lodgement/addStepsByReservationRef |
POST |
/api/v1/lodgement/checkoutLodgementDraft |
POST |
/api/v1/lodgement/processInvoice |
POST |
/api/v1/lodgement/updateDoc |
POST |
/api/v1/maintenance/processCRE |
POST |
/api/v1/maintenance/processInvoice |
POST |
/api/v1/office-timings/update |
POST |
/api/v1/prepackage/execute/all |
POST |
/api/v1/prepackage/execute/change |
POST |
/api/v1/prepackage/subscription/status |
POST |
/api/v1/relodgement/deleteStep |
POST |
/api/v1/reservation/addDraftToTransfer |
POST |
/api/v1/reservation/addOtherDataByGis |
POST |
/api/v1/reservation/checkoutDraft |
POST |
/api/v1/reservation/processStep |
POST |
/api/v1/reservation/updateNumberingStatus |
POST |
/api/v1/sms |
POST |
/api/v1/user/changeStatus |
POST |
/api/v1/user/delegations/update |
POST |
/api/v1/user/passAgeExpiredScheduler |
POST |
/api/v1/user/resetForgotPassword/{email} |
POST |
/api/v1/user/verifySecurityAnswers |
POST |
/api/v1/workflow/deleteDocs |
POST |
/api/v1/workflow/productivity |
POST |
/api/v1/workflow/taskReminder |
POST |
Additional behavior:
- Generic credential errors replace account-existence/lock distinctions. Directory registration onboarding and password actions after credential verification retain their dedicated responses.
- A failed remote logout returns 503/REVOCATION_PENDING with cleared cookies and retained retry work. If Redis is unavailable, termination cannot be confirmed and the request fails. Successful atomic queueing also prevents a concurrent refresh commit from recreating the deleted session.
- Logout invalidates the user's auth-browser SSO generation; other already-issued BFF sessions retain independent lifetimes unless revoke-user is used. Users with valid credentials may sign in again. Legacy browser sessions without a generation must sign in again. No schema migration is needed.
- Override direct auth defaults with
cis.auth.request-limits.peer-requests-per-minuteandcis.auth.request-limits.account-requests-per-minute. Proxied users may share the peer budget; trusted peer normalization is a separate configuration decision. - Pending revocation work retains token material inside the Redis security boundary already used for sessions until remote success. Polling uses bounded batches; idempotent delivery permits retries across nodes. Redis durability remains a dependency.
Edge-case review¶
Checks cover spoofed forwarded headers, direct login/token/revoke exhaustion, Redis failure, generic credential response equivalence, first-login compatibility, missing CSRF, rejected GET requests, logout HTTP failure and retry, stale/missing browser generations and in-flight refresh lease cancellation. Real Redis/Oracle checks may be skipped when Docker is unavailable. This does not constitute a complete cis-api authorization or password-recovery audit.
The original audit evidence remains a pre-remediation snapshot. Current validation follows below.
Verification results¶
The final combined Gradle command completed successfully. Test results:
| Module | Reported | Passed | Skipped | Failures/errors |
|---|---|---|---|---|
| cis-auth | 95 | 87 | 8 | 0 |
| cis-bff | 112 | 109 | 3 | 0 |
| cis-api | 204 | 204 | 0 | 0 |
The auth and BFF suites were run in full, with the isolated audit regressions included. The API run selected the mutation-boundary, relodgement HTTP method, resource-server token security, reservation, lodgement, user and delegation controller tests. Oracle migration/transaction and real Redis integration tests were skipped where Docker was unavailable; this includes the new atomic logout/outbox integration test. Passing mock-based tests do not prove live Redis atomicity, Oracle replay-family behavior or an end-to-end cross-origin browser flow.
The API test run also revealed legacy user/delegation fixtures using SpringExtension without initializing Mockito mocks. Those fixtures now use MockitoExtension, and two unrelated stubs in the affected user fixture were corrected to target the methods actually exercised. Compiler warnings about deprecated APIs, unchecked test operations and MapStruct processor options remain; compilation and the selected checks pass.
./gradlew.bat -I scripts/security-audit/audit.init.gradle :cis-auth:test :cis-bff:test :cis-api:test --tests '*MutatingGetBoundaryTest' --tests '*RelodgementHttpMethodTest' --tests '*ResourceServerTokenSecurityTest' --tests '*ReservationResourceTest' --tests '*LodgementResourceTest' --tests '*UserResourceTest' --tests '*UserDelegationsResourceTest' --console=plain
The --tests filters apply to the API test task; auth/BFF run their full suites. git diff --check passed for the changed source and documentation. Current source fingerprints and machine-readable test counts are separate from the original audit snapshot. No deployment or database migration was performed.
cis-auth and cis-bff security audit¶
Date: 2026-10-25. Target: current local working tree, including pre-existing uncommitted changes. Application code and environment settings were not changed. Audit tests run locally with mocks and a loopback HTTP service; no attack requests were sent to deployed services.
Remediation status¶
The findings and original validation below describe the pre-remediation snapshot. Application-level fixes are now being verified; see application security remediation for the implemented changes, endpoint contract changes and current test results. LDAP transport, ingress/network controls and operational endpoint exposure are outside this development remediation scope, as requested. The original risk rating is not a post-fix assessment.
Executive assessment¶
Provisional risk: High for the reviewed code/configuration. Two High findings merit priority: cookie-authenticated CSRF against a mutating GET downstream of the BFF, and plaintext LDAP credential transport in the local UAT/production configuration. Additional Medium weaknesses affect abuse protection, information disclosure, logout guarantees and credential handling in logs. Production exposure depends on actual deployed code, network protections and ingress policy; none was independently verified.
There are 9 findings: 2 High, 6 Medium, 1 Low. This is a qualitative prioritization, not a CVSS calculation, certification, probability of compromise, or a count of independent exploit chains. The throttling and enumeration findings can reinforce each other and must not be added together as a numerical risk score. No Critical remote takeover was established in the paths examined; that is not proof one does not exist.
A defensible statement is: ?The authentication implementation has tested OAuth/session controls, but the current review found high-priority CSRF and credential-transport weaknesses, plus several session and abuse-control gaps. Production safety cannot be asserted until those are remediated and verified in the deployed environment.?
Scope and evidence strength¶
- Inventoried/scanned production Java: cis-auth 114 files / 6,283 lines, cis-bff 43 files / 4,050 lines. Searches covered all 157 files for endpoint, authorization, injection, logging and transport indicators. Detailed reading concentrated on security configurations, authentication strategies, OAuth token/refresh adapters, client management, browser handlers, impersonation, revocation, BFF session storage, cookies, filters and proxying. This is not a line-by-line review of all 10,333 lines.
- Inspected application YAML, build configuration, selected migrations and tests, local
.env.dev/.env.uat/.env.prodsecurity settings and examples with credentials/hosts withheld, and Compose ingress wiring. A local production-named file is not evidence of what production runs. - Traced one cis-api controller/service and resource-server boundary to establish the BFF GET-CSRF impact. Broader cis-api business authorization and password recovery remain outside this audit.
- Reproduced means the supplied characterization test observed the behavior in current Java code. Source-confirmed means the code/configuration establishes the behavior, with explicit runtime prerequisites. Conditional gap means whether it violates the intended security guarantee depends on deployment or product policy.
- Inventory fingerprints and test counts are in security-audit-evidence.json. Fingerprints identify this snapshot; they do not imply detailed review of every listed file.
Findings¶
AUTH-BFF-01 ? High: GET requests can perform authenticated changes without CSRF proof¶
Evidence: cis-bff/src/main/java/com/dw/ngms/cis/bff/service/chain/CookieSessionAuthHandler.java:47, cis-bff/src/main/java/com/dw/ngms/cis/bff/service/chain/CookieSessionAuthHandler.java:72, cis-api/src/main/java/com/dw/ngms/cis/web/rest/RelodgementResource.java:81. The BFF checks CSRF only for POST/PUT/PATCH/DELETE, then attaches the victim session access token to every forwarded GET. GET /api/v1/relodgement/deleteStep?stepId=... invokes deletion. Local UAT/production cookie settings use SameSite=Lax.
Attack conditions/impact: An attacker knows or predicts a valid target step ID and induces a logged-in user able to delete it to follow a top-level navigation to that BFF URL. Lax cookies can accompany top-level GET navigation. The downstream sees a valid bearer token and cannot tell that the browser request lacked user intent. Source requests/documents can be removed or locks altered through the existing service. Ownership/authorization checks still constrain the victim's effective privileges; this finding does not claim unauthenticated arbitrary deletion.
Validation: audit01_getDeleteIsRelayedWithVictimBearerWithoutCsrf reproduced bearer injection without a CSRF header. The controller/service path was read; a live database deletion and browser click were deliberately not performed.
Remediation: Move state changes to authenticated POST/DELETE routes with CSRF protection at the cookie boundary. Inventory remaining mutating GETs and temporarily block them for cookie authentication at the BFF. Update clients before removing legacy routes. Test malicious cross-origin navigation and valid same-origin mutations. Spring's CSRF model requires safe methods to be read-only.
AUTH-BFF-02 ? High: internal LDAP credentials lack transport encryption in reviewed configuration¶
Evidence: cis-auth/src/main/java/com/dw/ngms/cis/auth/config/LdapRealmConfig.java:33, cis-auth/src/main/java/com/dw/ngms/cis/auth/service/adapter/ActiveDirectoryLdapPortAdapter.java:43. Reviewed local cis-auth/.env.uat, .env.prod and corresponding examples enable LDAP with an ldap:// URL. The context source uses that URL and manager credentials without a TLS authentication strategy; user verification uses LDAP bind. No StartTLS configuration was found in these modules.
Attack conditions/impact: An adversary who can observe or intercept the auth-to-directory network path can capture LDAP bind credentials, including user passwords and manager credentials when used. This requires network position; it is not a demonstrated public Internet credential leak. An external encrypted tunnel could mitigate it, but none was verified.
Validation: Source/configuration confirmed; no packet capture, live AD connection or deployed TLS verification was performed.
Remediation: Use LDAPS with validated certificates or explicitly configured StartTLS; fail startup for insecure production directory URLs. Verify the actual AD endpoint, trust chain and negotiated transport in UAT before rollout. Spring LDAP documents TLS strategies.
AUTH-BFF-03 ? Medium: clients can choose the BFF rate-limit identity¶
Evidence: cis-bff/src/main/java/com/dw/ngms/cis/bff/web/filter/BffRateLimitingFilter.java:130. The first X-Forwarded-For value is accepted without checking a trusted proxy boundary and becomes the Redis counter key.
Attack conditions/impact: If ingress preserves or appends to user-supplied forwarded values, or the BFF is reachable directly, a caller changes that value per request to obtain new buckets. This weakens throttling for credential stuffing, enumeration and resource abuse. Per-account lockout is a separate control and is not automatically bypassed by this issue. Trusted ingress that overwrites the entire header can mitigate public exploitability.
Validation: audit02_samePeerChoosesDifferentRateLimitBucketsViaForwardedHeader reproduced distinct counters for the same remote address. Live Traefik sanitization was not verified.
Remediation: Establish trusted proxy CIDRs and normalized peer identity; strip externally supplied forwarding headers at the edge. Combine IP and normalized-account limits. Test spoofed/multiple header values through the real ingress. Spring explains forwarding-header trust.
AUTH-BFF-04 ? Medium: the public auth browser path bypasses BFF throttling¶
Evidence: cis-auth/src/main/java/com/dw/ngms/cis/auth/config/AuthorizationServerSecurityConfig.java:220, cis-auth/src/main/java/com/dw/ngms/cis/auth/service/strategy/BrowserAuthenticationProvider.java:39, cis-auth/src/main/java/com/dw/ngms/cis/auth/service/strategy/ExternalDbAuthStrategy.java:64. The browser posts credentials directly to cis-auth /login; the Redis limiter is only in cis-bff. No auth-side request throttler was found. compose/deploy/app.yml exposes auth through a host router without a repository-defined throttling middleware.
Attack conditions/impact: A caller can initiate a valid public authorization challenge and submit credentials directly to auth. CSRF tokens and login challenges are obtainable by that caller and do not limit attempt rates. Local external-account lockout remains effective for sequential wrong-password attempts, so this is principally password spraying, expensive hashing/LDAP load, and targeted lockout abuse; AD may apply its own controls. An external WAF/Traefik policy may mitigate it but was not inspected live.
Validation: Source/ingress gap confirmed; no brute-force or load test was performed. The browser handler's generic error message is a positive control and does not solve throttling.
Remediation: Apply bounded, shared rate limits to authorization initiation and credential verification at auth/ingress, with per-account and per-peer controls and operational monitoring. Verify that direct auth access cannot bypass them. OWASP discusses login throttling and lockout tradeoffs.
AUTH-BFF-05 ? Medium: password API errors disclose account existence and lock state¶
Evidence: cis-auth/src/main/java/com/dw/ngms/cis/auth/service/strategy/ExternalDbAuthStrategy.java:69, cis-auth/src/main/java/com/dw/ngms/cis/auth/service/strategy/ExternalDbAuthStrategy.java:72, cis-auth/src/main/java/com/dw/ngms/cis/auth/web/handler/OAuth2TokenEndpointErrorResponseHandler.java:59, cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:220. Missing users, incorrect passwords and locked users produce distinct descriptions/codes and remaining-attempt metadata; BFF password login propagates those distinctions, including lock-specific HTTP status.
Attack conditions/impact: Anonymous callers of /bff/auth/login can distinguish external-account names and lock state. Direct /oauth2/token use additionally requires an accepted client. The BFF supplies its confidential credentials, so that requirement does not protect the BFF login endpoint. Enumeration supports focused phishing, spraying and targeted lockout. Password verification is still required for successful sign-in. LDAP onboarding profile disclosure only follows successful directory credentials and is not classified as anonymous enumeration here.
Validation: Source-confirmed response chain; no real-user enumeration performed. Browser form errors are already more uniform.
Remediation: Return a uniform unauthenticated credential-error contract and put detailed counters/status in protected audit/support channels. Keep onboarding disclosures gated by completed authentication. Check bodies, status codes and timing differences. OWASP's generic-error guidance applies here.
AUTH-BFF-06 ? Medium: logout reports success when remote token revocation failed¶
Evidence: cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:141, cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:158, cis-bff/src/main/java/com/dw/ngms/cis/bff/facade/BffAuthenticationFacade.java:343. The adapter catches all revocation failures and returns normally; the facade deletes its Redis session and returns a successful local logout.
Attack conditions/impact: During an auth outage or revocation rejection, the browser cookie is cleared and its BFF session is deleted, but the remote access token and authorization/refresh token can survive. A previously stolen token may continue working until its expiry or another revocation. This does not mean the deleted BFF cookie still works. The failure is silent to callers and there is no durable retry in this path.
Validation: audit03_remoteRevocation503IsSilentlyAccepted made a loopback auth stub return HTTP 503 and observed a normal adapter return.
Remediation: Preserve local session termination while recording durable revocation work and surfacing a precise partial-logout result internally. Consider directly marking the access-token JTI revoked where appropriate, and retry complete authorization revocation safely. Test remote outage, Redis failure and recovery without resurrecting a deleted session.
AUTH-BFF-07 ? Medium: local logout and user-token revocation leave browser SSO usable¶
Evidence: cis-bff/src/main/java/com/dw/ngms/cis/bff/facade/BffAuthenticationFacade.java:343, cis-auth/src/main/java/com/dw/ngms/cis/auth/facade/SessionTerminationFacade.java:56, cis-auth/src/main/java/com/dw/ngms/cis/auth/web/filter/AuthorizationRealmFilter.java:71, cis-auth/src/main/java/com/dw/ngms/cis/auth/config/AuthorizationServerSecurityConfig.java:220. The auth server maintains an HTTP login session. BFF logout clears BFF cookies and revokes OAuth authorization; revoke-user removes token authorizations and publishes BFF eviction. Neither path invalidates auth HTTP sessions or records a browser-authentication cutoff. A same-realm existing principal is accepted at authorization initiation unless fresh login is requested.
Attack conditions/impact: After browser-based sign-in, someone using the still-open browser can restart authorization and receive a new BFF session without re-entering credentials while the account remains eligible. A stolen auth-session cookie can similarly survive token-only revocation. Account deactivation/policy checks at token issuance still prevent issuance for ineligible accounts. This is a conditional gap if logout/revoke-user is intended to terminate sign-in globally; local application logout semantics must be documented explicitly if intentional.
Validation: Source-confirmed split session lifecycles, not a live cross-origin browser reproduction.
Remediation: Define local versus global logout. For global logout/admin incident response, invalidate auth browser sessions or enforce a per-user authenticated-after cutoff at authorization/token issuance, and integrate a supported logout flow. Verify logout, revocation and multi-tab behavior end to end. Token blacklisting alone does not terminate SSO authentication.
AUTH-BFF-08 ? Medium: INFO audit logs contain reusable BFF session credentials¶
Evidence: cis-bff/src/main/java/com/dw/ngms/cis/bff/audit/BffAuditLogListener.java:27, cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RedisBffSessionStoreAdapter.java:92, cis-bff/src/main/java/com/dw/ngms/cis/bff/facade/BffAuthenticationFacade.java:566. Session IDs are emitted in INFO audit logs and in event details such as sessionId, deletedSessionId, restoredAdminSessionId and sessionIds. The same value is the CIS_SESSION cookie credential. Some events log currently active sessions, so the concern is not limited to expired credentials.
Attack conditions/impact: A person or compromised log system that can read a current session ID can send it as a cookie to impersonate that browser session. /bff/auth/me can expose that session's CSRF token to a holder of the cookie, so CSRF does not compensate for credential theft. HttpOnly protects browser script access, not server log disclosure. Existing log access controls reduce exposure but do not make raw credential logging safe.
Validation: Source-confirmed logging and cookie consumption; no real session identifiers were collected or replayed.
Remediation: Replace raw session IDs in logging and audit details with a keyed hash or independent audit correlation ID. Restrict access/retention and assess whether prior logs contain still-active sessions. Preserve security event correlation without retaining reusable credentials.
AUTH-BFF-09 ? Low: BFF operational metrics are publicly authorized¶
Evidence: cis-bff/src/main/java/com/dw/ngms/cis/bff/config/BffSecurityConfig.java:64 permits /actuator/**. Reviewed UAT/production BFF settings expose health,info,metrics. The deploy router does not restrict those paths in this repository.
Attack conditions/impact: If reachable through deployed ingress, anonymous clients can inspect operational meter names and available measurements/tags. The exact data depends on installed meters; no credential/secret leak is asserted. when_authorized on health does not authorize the metrics endpoint. The rate limiter also skips actuator paths.
Validation: Source/configuration confirmed; deployed URLs were not probed.
Remediation: Permit only required health probes publicly, authenticate metrics or isolate the management listener/network, and confirm edge access policy. Recheck what external health responses disclose.
Additional risks requiring targeted validation¶
These are not counted as confirmed vulnerabilities above:
- Impersonation return authority:
BffAuthenticationFacade.exitImpersonationrestores the administrator using only the current impersonated session and its server-side parent reference. If a lower-privilege impersonated cookie is stolen,/mecan provide CSRF proof and exit may recover the original administrator session. Decide whether retaining that ability is acceptable; test a separate browser/actor binding or fresh admin authentication. This audit did not reproduce it or classify its severity. - Public revocation availability: the anonymous custom revoke-token endpoint acquires the global
AUTH_SECURITY_LOCKbefore token lookup; lookups compare CLOB token columns. A load test should evaluate lock contention, unknown-token costs and request-size limits. No throughput collapse was demonstrated. - Concurrent browser password failures: the retry counter is entity read/modify/write without
@Version, explicit user-row locking or an atomic database increment. Browser authentication does not use the token mutation filter. Concurrent lost updates may undermine retry counts; an Oracle concurrency regression is needed before claiming a lockout bypass. - Private-key encryption contract:
AesPrivateKeyCipherAdapterclaims GCM in its comment but callsEncryptors.text, and decryption failure returns the original input as a legacy fallback. Plan a versioned, authenticated-encryption migration and validate existing key formats rather than swapping the cipher in place. Actual plaintext legacy key rows were not inspected. Resolved Spring Security crypto is 7.1.1; it is a fixed version for CVE-2026-47842, so that CVE is not reported as an affected dependency. The advisory also describes compatibility implications of changing encryptor APIs. - Password grant remains reachable: a custom password grant and
/bff/auth/loginare still implemented. RFC 9700 section 2.4 disallows this grant in current OAuth security practice. Retire it through a planned client migration to Authorization Code + PKCE; this is a design debt, not proof of a password bypass. Administrative step-up/MFA was not established in these modules. - HTTP backend API route: reviewed BFF API routing uses HTTP inside the container network. A network observer there may see bearer tokens; validate service-network isolation or encrypted service transport. The HTTPS validation for the auth back-channel does not secure every API route.
Controls verified in inspected source¶
- Admin client/key/session-management and impersonation URLs require administrative authorities. Impersonation derives caller identity from the authenticated principal and checks current administrator and target status/roles. No anonymous impersonation bypass was established.
- Browser login has CSRF/session-fixation defenses, per-session bounded/expiring challenges, validated registered redirects, realm binding and generic form-login errors.
- BFF authorization uses server-stored PKCE verifiers, random state bound to an HttpOnly browser cookie, atomic one-time transaction consumption and configured frontend return URLs.
- Session mutations and unsafe cookie API requests verify session-bound CSRF values; cookie forwarding is stripped and cookie mode takes precedence over supplied bearer headers.
- Access tokens use RSA signatures; auth decoding pins RS256 and verifies issuer/revocation/client availability. Refresh-time user policies/roles are reloaded. The BFF's unsigned parsing of back-channel token claims is not by itself classified as a signature bypass because those responses originate from the configured authenticated transport, and downstream APIs validate tokens.
- Refresh rotation/replay family handling and Redis refresh leases exist. Revocation verification rejects unavailable Redis checks. Existing client validation, parameterized SQL/LDAP filters, enabled-client checks and redirect allowlists provide meaningful protections.
Validation and reproduction¶
The existing :cis-auth:test :cis-bff:test run succeeded. The final combined run including isolated audit tests also succeeded:
| Module | Reported tests | Passed | Skipped | Failures/errors |
|---|---|---|---|---|
| cis-auth | 88 | 80 | 8 | 0 |
| cis-bff, including 3 audit tests | 109 | 107 | 2 | 0 |
Skipped coverage includes Oracle mutation/transaction/migration tests and Redis integration tests. Passing characterization tests confirm the weaknesses, not their remediation. Most execution uses mocks/in-memory state; it does not prove production Oracle/Redis/AD integration or ingress security.
Audit-only source is under scripts/security-audit, attached to the test source set only when the init script is explicitly used:
./gradlew.bat -I scripts/security-audit/audit.init.gradle :cis-auth:test :cis-bff:test --console=plain
./gradlew.bat -I scripts/security-audit/audit.init.gradle :cis-bff:test --tests '*SecurityAuditEvidenceTest' --console=plain
./gradlew.bat :cis-auth:dependencyInsight --dependency spring-security-crypto --configuration runtimeClasspath --console=plain
The initial sandboxed test attempt could not access the external Gradle cache; the authorized retry succeeded. No production config or business data was changed.
Remediation order and remaining assurance work¶
- Close the mutating-GET CSRF path and enable authenticated directory transport; validate both in UAT.
- Fix rate-limit identity and add auth-side abuse controls. Remove unauthenticated account-status distinctions and session credentials from logs.
- Define global logout/revoke-session guarantees, make revocation failure visible/recoverable and restrict operational endpoints.
- Add regression tests that reject the reproduced behaviors after fixes, then exercise real Oracle/Redis/AD and browser flows. Verify ingress forwarding-header sanitization, network ACLs, deployed settings and image provenance.
- Perform a full resolved-dependency/container vulnerability scan, broader cis-api authorization/password-recovery audit and independent penetration test before making an organization-wide assurance claim.
No full SCA/container scan, external penetration test, packet capture, secret-history scan, production infrastructure review or live data inspection was performed. The one advisory check above cannot establish that all dependencies are vulnerability-free. This report does not assert that exploitation or compromise has occurred.
Database
Database & Persistence Architecture¶
The CIS platform relies on Oracle Database 23 as its primary system of record for transactional cadastral land management, workflow tracking, and identity metadata.
Documentation Guides¶
- Oracle Flyway Baseline: Database schema migration conventions, baseline script naming, and execution standards.
- Mapper Constructor Injection: Architectural pattern deprecating field injection in MapStruct mappers in favor of constructor injection for immutability and testability.
- Persistence Package Audit: Complete audit of JPA entities, query bottlenecks, and N+1 query remediations.
Best Practices¶
- Explicit Schema Migrations: All DDL changes must be committed as versioned Flyway migration scripts (
V<SemVer>__description.sql). - Read-Only Transactions: Use
@Transactional(readOnly = true)for service read queries to avoid unnecessary Hibernate dirty-checking overhead. - Constructor Injection: Never use
@Autowiredfield injection in entities, mappers, or repositories.
Oracle/Flyway baseline derivation¶
This is a read-only derivation from the local cis-oracle-db container,
PDB ORCLPDB1, schema SGUSER, collected on 2026-11-02. The collector is
scripts/schema-baseline/inspect_oracle.py
and the machine-readable result is
build/reports/oracle-baseline/inspection.json.
What the live schema says¶
The schema contains 233 tables, 252 sequences, 92 views, 310 indexes, 212
foreign keys, 17 triggers and 18 invalid objects. Two foreign keys on
CART_ITEMS are disabled. The invalid objects include legacy DB-link-backed
views, missing legacy tables/sequences, and invalid migration/support program
units; they are not safe evidence for a clean application baseline.
The source scan found 201 JPA entities across cis-api, cis-search,
cis-workflow and cis-auth. The following is the source-authoritative
reconciliation. It compares explicitly mapped entity tables/columns/sequences;
it does not infer unannotated Hibernate names.
Tables mapped in source but absent from Oracle¶
ARCHIVE_MASTER—cis-api/.../archive/ArchiveMaster.javaARC_META_DATA—cis-api/.../archive/ArcMetaData.javaSGDATA_NUMBER_SEARCH—cis-search/.../parcel/SgdataNumberSearch.javaSGDATA_SECTIONAL—cis-search/.../sectional/SgdataSectional.java
Existing Oracle tables missing columns required by source¶
HISTORICAL_RECORDS_ARCHIVE:CREATEDON,DOCUMENTTYPEID,PROJECTNAMEMAN_DRAFT_CHECKLIST:GENERAL_PLANMAN_DRAFT_REQUEST:AMENDMENT_DETAILS,BC_AUTH_DIAGRAM_SGNO,BC_BOUNDARY_NOTES,BC_COORDINATE_FRAME,BC_PURPOSE,BC_REQUESTOR_TYPE,BC_SOURCE_DOCS_JSON,BC_SUPPORTING_DOC_ID,CLOSURE_TYPE,CRE_APP_LETTER_DOC_ID,CRE_CERT_DOC_ID,CRE_CHILDREN_JSON,CRE_COMPUTED_RE_EXTENT,CRE_DEEDS_PRINT_DOC_ID,CRE_FINAL_RE_EXTENT,CRE_FINAL_RE_SOURCE,CRE_LETTER_DOC_ID,CRE_REQUESTOR_TYPE,CRT_NUMBER,NEW_RECORD_ID,NOTICE_NUMBER,NOTIFICATION_TYPE,PROCLAMATION_DATE,PROCLAMATION_NUMBER,PURPOSE_OF_SERVITUDE,REGISTRATION_DATE,RENAME_REASONID,SERVITUDE_DESCRIPTION,SERVITUDE_NUMBER,SS_NUMBER,STREET_RENAME,SUBSTITUTION_REASON,TARGET_TOWNSHIP_ID,TYPE_OF_AMENDMENTS,TYPE_OF_ENDORSEMENT,WITHDRAWAL_NOTE,WITHDRAWAL_REASONMAN_DRAFT_STEPS:DOC_COUNTROLES:ROLE_ID(reported by bothRoles.javaandSiteRole.java)
MAN_DRAFT_REQUEST is already covered by
V1__maintenance_archival_schema.sql; that migration adds the older
archival/reconciliation columns and those columns are present in Oracle. The
list above is the newer entity surface that the existing migration does not
yet create. The table and migration must therefore be retained, with a new
additive migration for only the missing source columns after their Oracle
types and data/backfill rules are approved.
For the four absent tables, the source-required columns are also absent by definition. They are not repeated here as column drift; they require a table ownership/design decision first.
Sequences mapped in source but absent from Oracle¶
ARCHIVE_MASTER_SEQ—ArchiveMaster.javaARCHIVE_METADATA_SEQ—ArcMetaData.javaM_REPORT_FILTERS_CONFIG_SEQ—ReportFilterConfiguration.java
MAN_DRAFT_REQUEST_SEQ is required by MaintenanceDraftRequest.java and is
present in Oracle.
Live objects not suitable for a clean source baseline¶
The live schema also contains 18 invalid objects:
- invalid program units:
FN_GETDURATIONSTRING,MIGRATION,MD_META,MIGRATION_REPORT,MIGRATION_TRANSFORMER,CLEARME,ALL_MAJOR_REGION_TRIGGER - DB-link-dependent views:
VW_STREET_GIS_DATA,V_KZN_ERF,V_KZN_FARMS,V_PTA_ERF,V_PTA_FARMS,V_WC_ERF,V_WC_FARMS - invalid search/legacy views:
V_SGDATA_NUMBER_SEARCH_GIS,V_SGDATA_NUMBER_SEARCH_GIS_OLD,V_TOWNSHIP_ADMINISTRATION
These objects must not be copied into a clean baseline without an explicit
dependency and ownership decision. The live schema also has two disabled
foreign keys on CART_ITEMS (CART_ITEMS_FK1, CART_ITEMS_FK2).
Existing migration ownership¶
The API owns SGUSER."flyway_schema_history" and currently records baseline
0, V1, V2 and repeatable migrations. Auth owns the separate
SGUSER.FLYWAY_SCHEMA_HISTORY_AUTH table and records baseline 0 through V8
plus repeatables. Auth V2 also creates shared UAM tables, so the two histories
cannot be collapsed or replaced by a single dump-derived version.
Recommendation¶
Yes, a baseline can be derived, but the live schema is a source snapshot for reconciliation, not yet an activatable Flyway baseline. Keep the existing history tables and applied migrations immutable. Build a reviewed, versioned baseline migration only after:
- deciding ownership of shared UAM tables between API and auth;
- reconciling the 201 entity mappings against the four missing relations, ten column-drift entities and three missing sequences;
- separating required application objects (tables, sequences, constraints, required views/triggers) from legacy DB-link views, invalid program units, users, grants, links and business data; and
- replaying the candidate on an empty Oracle schema and running the API/auth migration and persistence tests.
Do not use baselineOnMigrate as proof of equivalence: it only records afer a reviewed
marker for an existing database. For a new environment, pre
baseline migration (for example a B... migration) while preserving the
current V/R history for existing environments. Do not apply the generated
DDL or change the live container from this audit.
cis-api mapper constructor injection¶
Scope¶
All 127 MapStruct mappers in cis-api explicitly select InjectionStrategy.CONSTRUCTOR. The existing field mappings, uses relationships, expression imports, inverse configurations and warning policies were retained. This change does not resolve the repository lookups documented in the persistence audit.
Thirty abstract MapStruct decorators are now concrete Spring decorators. Each has @Component, @Primary, final dependencies and one explicit constructor. The generated mapper is the qualified delegate, for example:
public TemplateMapperDecorator(
@Qualifier("templateMapperImpl") TemplateMapper delegate,
@Qualifier("userRepository") UserRepository userRepository) {
this.delegate = delegate;
this.userRepository = userRepository;
}
These decorators implement their mapper interfaces directly. Existing custom methods are retained; other interface methods explicitly forward to the generated delegate. Unqualified injection of the interface resolves the primary decorator. The constructor qualifier resolves the generated implementation and prevents the decorator from injecting itself. Do not restore @DecoratedWith on these interfaces: that would generate another decorator wrapper and reintroduce the constructor/subclass limitation.
Generated mapper bean names follow Spring's class-name convention (TemplateMapperImpl becomes templateMapperImpl). When renaming a mapper or overriding its implementation name, update its decorator qualifier. The complete mapper-context test detects broken qualifiers and dependency cycles.
The archive mapper's five existing @AfterMapping methods moved from its abstract generated superclass into HistoricalRecordsArchiveEnricher, a constructor-injected component referenced through uses. This avoids leaving repository field injection behind in an abstract mapper. The existing workflow-note enrichment hook was already constructor-injected and remains in place.
All touched Java files use organized explicit imports. No generated source was edited. The root build's defaults for other modules were left unchanged; each cis-api mapper's explicit strategy takes precedence.
Validation¶
- A clean
cis-apimain/test compilation passed, with existing nonblocking compiler warnings. - The full mapper component graph starts in an isolated Spring context with external dependencies mocked. Every component's non-static fields are checked for finality; field/method injection is rejected; decorator interfaces resolve to their primary wrappers.
- Six focused tests pass across
MapperConstructorWiringTest,MapperInjectionTest,WorkflowNotesMappingTestandHistoricalArchiveMappingTest. They cover nested address mapping, decorator forwarding and username enrichment, archive enrichment/reverse IDs/null references, and workflow notes. - During migration, 350 generated mapping methods were compared with their pre-change versions, ignoring whitespace and the archive hook receiver. All matched. All 51 pre-existing decorator method bodies and five extracted archive hook bodies also matched. Dependency setters were intentionally removed from that comparison.
- Import organization, no-inline-type checks and scoped whitespace checks passed.
This verifies mapper construction and the covered mapping behavior. It is not a full application-startup, HTTP contract, database or complete test-suite result. Request/response DTOs, controllers and repository queries were not changed.
Reproduce the focused checks from the repository root:
./gradlew.bat :cis-api:clean :cis-api:compileJava :cis-api:compileTestJava --offline --console=plain
./gradlew.bat :cis-api:test --tests '*MapperConstructorWiringTest' --tests '*MapperInjectionTest' --tests '*WorkflowNotesMappingTest' --tests '*HistoricalArchiveMappingTest' --offline --console=plain
The implementation uses constructor injection and ordinary Spring decorator composition because MapStruct documents restrictions for generated abstract-class/decorator injection. See the MapStruct injection strategy reference.
Testing
Testing Standards & Strategy¶
Testing across CIS microservices emphasizes automated verification, fast feedback loops, and authentic environment fidelity.
Testing Pyramid¶
pie title CIS Test Distribution
"Unit & Web Slice Tests (RestTestClient / MockMvc)" : 65
"Integration Tests (Testcontainers Oracle / Redis / LDAP)" : 30
"Contract & End-to-End Tests" : 5
Guides & References¶
- Integration Testing Guide: Detailed configuration and patterns for Docker Testcontainers (Oracle 23, Redis 7.4, OpenLDAP).
- Build & Test Guide: Gradle commands for slice tests, offline test execution, and JaCoCo coverage reports.
Testing Principles¶
- RestTestClient for Web Slices:
In Spring Boot 4.1.2 (Spring Framework 7), prefer
RestTestClientover rawMockMvcfor cleaner, fluent assertions and seamless alignment with modern HTTP client testing. - AssertJ Fluent Assertions:
Always prefer AssertJ assertions (
assertThat(...)) over JUnit 5 assertions for rich failure diagnostics. - No Mocks for Critical Infrastructure: Database, Redis token revocation, and LDAP queries must be validated against real Testcontainers instances in integration test suites.
Oracle integration testing¶
The domain mappings define the intended application schema. The legacy application was not bootstrapped by its feature migrations: V1 assumes tables such as MAN_DRAFT already exist. Integration tests therefore install a reviewed, structure-only legacy prerequisite fixture before executing the real API migrations. Hibernate does not create or update the database.
Database initialization¶
The API test harness starts disposable Oracle Free and Redis containers. It installs these resources in order:
db/test-bootstrap: legacy sequences, tables, indexes, foreign keys, synthetic reference parents and valid application triggers. Its separateTEST_BOOTSTRAP_HISTORYnever marks application migrations as applied.db/migration: the unchanged existing migrations plus V4 domain reconciliation, using the normalflyway_schema_historytable. Prerequisite installation checks that feature-owned tables and representative columns are absent before this step.db/test-views: valid local legacy views, installed after the feature columns and tables they can reference.
The fixture was derived from read-only metadata in the host cis-oracle-db, PDB ORCLPDB1, schema SGUSER, on 4 November 2026. It contains 173 legacy tables, 56 local views and 13 application triggers. It contains no application rows, passwords, grants, database links or application Flyway history. Source sequence and identity high-water marks are replaced with deterministic test values. Invalid and remote dependencies are excluded. Synthetic parent rows exist only to satisfy the real migration seeds and foreign keys.
db/test-bootstrap/manifest.json records the object scope, exclusions, feature-owned objects and SHA256 hashes of normalized UTF-8 resources. Fixtures are not a production baseline or a replacement for application migrations. Their scripts may be revised together because every test JVM creates a disposable database.
The host database is not used by tests and was not migrated during fixture derivation. The domain reconciliation migration must be deployed through the normal application migration process for shared environments.
Domain reconciliation¶
V4__reconcile_domain_schema.sql adds four mapped tables, 42 missing columns and three sequences. It preserves existing columns and rows. The source inventory originally attributed a collection join column to ROLES; that column belongs to SITEMAP_ROLE, so no ROLE_ID column is added to ROLES.
The live archive identifier triggers also replaced IDs that Hibernate had already allocated. V4 preserves supplied IDs while retaining sequence defaults for native inserts that omit an ID. This aligns stored identity with the domain sequence mappings. The regression test exercises both paths with transaction rollback.
DomainSchemaIntegrationTest compares explicit scalar and singular association column mappings and sequence generators from the running JPA metamodel with the migrated schema, including embedded IDs. It checks presence, not comprehensive datatype, default or constraint equivalence. Collection join columns are not treated as columns of their owner table. OracleSchemaMigrationIntegrationTest checks feature objects, preservation of a legacy sentinel record, actual V4 re-execution with an independent test history, sequence preservation and a second no-op application migration run.
Test isolation and lifecycle¶
The integration profile disables scheduled business jobs and uses loopback addresses for external transports. Redis is real and disposable. Authentication helpers apply the real JWT-to-domain-principal converter; dedicated security tests remain responsible for cryptographic token validation. Resource integration tests must not send real email or SMS; mock the transport or application service when testing those endpoints.
Oracle and Redis are manually managed JVM singletons. They are not simultaneously managed by the JUnit Testcontainers extension. Shutdown hooks stop them even when Bitbucket disables Ryuk, preventing database containers from accumulating across modules. Docker-free local runs skip the Oracle suites; TESTCONTAINERS_REQUIRED=true turns missing Docker into a CI failure.
API integration tests have a bounded heap and a small Spring context cache. Database slice tests use transactions; individual service and controller tests must provide their own valid fixtures and clean up writes. Do not rely on host business rows or test execution order. A startup failure must not be hidden by ddl-auto: update, disabling the integration task or marking migration history successful.
Commands and pipeline¶
Run from the repository root in PowerShell:
./gradlew.bat :cis-api:test
./gradlew.bat :cis-api:integrationTest
./gradlew.bat :cis-api:integrationTest --tests '*OracleSchemaMigrationIntegrationTest' --tests '*DomainSchemaIntegrationTest'
./gradlew.bat check --no-daemon
The API separates integration-tagged tests from unit tests. Auth and workflow retain their existing test tasks and now use a consistent singleton lifecycle. The BFF's class-managed Redis tests retain their own lifecycle. Bitbucket runs check, requires Testcontainers, disables Ryuk for the runner and publishes detailed test XML and HTML artifacts. Full exception output exposes the original Oracle error instead of only Spring context wrappers.
Refreshing the fixture¶
Use scripts/schema-baseline/inspect_oracle.py --export-ddl to collect metadata and structure to a task-local review directory. It is read-only. Review the inventory and domain gaps before using scripts/schema-baseline/export_test_fixture.py --inspection <review-directory> to derive test resources. The exporter supports --view-ddl and --trigger-ddl for reviewed offline exports. The live container is not required by CI; the resulting resources are checked in.
Review regenerated SQL, excluded objects and the manifest. Run migration, schema contract and integration tests against a fresh container. Never copy production data, credentials or history tables into the fixture. Never modify an already applied production migration to accommodate test setup.
CIS API test suites and CI¶
Tests share the standard cis-api/src/test/java source set. Use one execution
category per test. Prefer a class-level JUnit @Tag.
| Tag | Gradle task | Scope |
|---|---|---|
unit |
:cis-api:test |
Isolated logic. Untagged legacy unit tests are included during migration. |
slice |
:cis-api:sliceTest |
Spring MVC or persistence slices that run without Docker. |
integration |
:cis-api:integrationTest |
Oracle-backed JPA slices and application integration with Oracle, Redis and local adapters. |
contract |
:cis-api:contractTest |
API/client contracts with local stubs. |
e2e |
:cis-api:e2eTest |
Full multi-service scenarios when provisioned. |
Run ./gradlew :cis-api:jacocoTestReport for fast-suite coverage and
./gradlew :cis-api:integrationTest for Oracle integration coverage.
Both reports publish HTML and XML under cis-api/build/reports/jacoco.
JaCoCo exposes line, branch, method and class counters with package drill-down,
including web.rest, service, persistence.repository, security
and configuration and their subpackages.
Bitbucket runs fast verification on ordinary commits, adds Oracle integration
for pull requests, and runs all module checks before releases. Schedule the
nightly-verification custom pipeline in Bitbucket for nightly runs.
Operations
Operations & DevOps¶
This section covers continuous integration, container packaging, deployment pipelines, and notification operations.
Operations Guides¶
- Pipeline Deployment Guide: CI/CD automation in Bitbucket Pipelines, multi-stage Docker builds, git commit SHA tagging, and production artifact promotion.
- Notification Framework: Operational setup for
cis-emailer, Thymeleaf templates, Mailpit testing, and SMTP server configuration. - Runtime Topology: Multi-environment container topologies across
dev,uat, andprod.
Pipeline deployment audit and RustFS rollout¶
Scope and verified findings¶
The current checkout deploys cis-api and cis-workflow. The default registry is now registry.digitalocean.com/cadastral in publishing scripts, Compose defaults and shipped UAT/production templates. Existing Bitbucket CONTAINER_REGISTRY overrides must also be changed in Bitbucket settings; repository code cannot overwrite those remote settings.
The old pipeline copied files, then attempted execution through a separate ssh-run command containing nested shell quotes and interpolated secret JSON. Copy success did not establish script execution or application health. Without the failed run's SSH logs, the exact observed server failure cannot be proven. The repository audit established these gaps:
| Finding | Change |
|---|---|
| Publish step had no deployment context, so deployment-scoped registry secrets could be absent | Publishing and remote deployment now share the same Bitbucket deployment step |
| Registry authentication warned and continued when credentials were absent | Local preflight fails before publishing/copying |
| Generic user/host fallbacks could resolve unintended destinations; remote directory silently defaulted | Explicit settings or named UAT/PROD aliases required; APP_DIR must already exist and be writable |
| Secrets were embedded in a nested YAML/SSH command string | Bash-serialized exports travel over SSH stdin; tracing disabled; credentials stored in temporary Docker config directories |
| Several duplicated UAT/prod/custom flows could drift | YAML anchors call shared publish/remote/server scripts |
| Deployment ignored the build's commit tag and used server env image settings | Server exports both exact commit-tagged images before Compose interpolation |
No CIS_ENV was explicitly selected remotely |
Server exports the validated target environment and exact application env-file paths |
Success meant up -d returned, not that applications were ready |
Server waits for running/healthy application containers and propagates failure |
| Shell files could arrive with CRLF | LF Git attributes and normalized copied script bundle |
| Host-path preparation did not use Compose's actual mount resolution | Removed guessed directory creation; provision bind mounts/network explicitly and let Compose use the selected env files |
Atlassian documents deployment variable scoping and pipeline SSH identity handling. The pipeline retains existing branch behavior: UAT from release/uat or uat; production from main with a manual publish/deploy gate; custom UAT/production flows reuse the same steps. This change does not restrict backend deployments to the separate frontend repository's branch policy.
Execution contract¶
- CI runs deployment contract tests with mocked tools, then Gradle test-class compilation.
- A deployment step resolves the environment and runs
scripts/deploy.sh. scripts/deploy.shverifies local preflight without contacting the server, logs into the registry, builds both multi-stage Dockerfiles and pushes<environment>-<first-seven-commit-characters>plus the environment alias.- It checks SSH access and the existing writable APP_DIR before copying. It copies only deployment Compose and LDAP/Oracle supporting assets. No
--deleteis used; server environment/data files are preserved. - The script prints
3/3 Executing deployment script on serverand sends its orchestration directly over SSH stdin. - The server prints
[server] Started deployment, verifies Docker access, Compose and all three env files, validates the rendered Compose config, logs into the registry, pulls the exact application images, starts the stack and waits for application readiness. - SSH returns the actual server exit status.
[deploy] Remote script completed successfullyis printed only after success. Errors identify the failing phase without printing secrets.
Required Bitbucket settings¶
Configure these as repository variables or, for environment-specific secrets/hosts, variables under the matching uat / production deployment environment:
| Setting | Meaning |
|---|---|
SSH_HOST, SSH_USER, APP_DIR |
Explicit target host/user and existing absolute directory; spaces and shell metacharacters in APP_DIR are rejected |
SSH_PORT |
Optional; defaults to 22 |
SSH_KEY |
Secured raw or base64-encoded SSH private key; alternatively use the configured Bitbucket key through BITBUCKET_SSH_KEY_FILE/default SSH identity |
SSH_KNOWN_HOSTS |
Verified known-hosts lines; alternatively configure Bitbucket's known-hosts file. Nondefault SSH ports require the corresponding [host]:port entry |
CONTAINER_REGISTRY |
Optional; defaults to registry.digitalocean.com/cadastral; update any old override |
DOCKER_CONFIG_JSON / DOCKER_CONFIG_B64 |
Secured Docker auth JSON or base64 JSON |
DIGITALOCEAN_ACCESS_TOKEN |
Alternative registry login token; optional DOCKER_REGISTRY_USER override |
DEPLOY_HEALTH_TIMEOUT |
Optional application readiness deadline in seconds; default 240 |
DEPLOY_SERVICES |
Optional cis-api, cis-workflow, or both; default updates the full profile-selected stack |
Existing UAT_SSH_USER/UAT_SERVER_HOST/UAT_APP_DIR/UAT_SSH_PORT/UAT_SSH_KEY and PROD equivalents remain supported. Generic settings take precedence. The script never falls back to the pipeline container's USER/HOST. DEPLOY_TARGET_NAME is selected by the YAML step; IMAGE_TAG is derived from BITBUCKET_COMMIT unless explicitly provided for a controlled manual deployment.
The SSH user needs Bash, Docker CLI/Compose v2 and Docker daemon access. Provision the external Traefik network and required bind-mount directories/permissions. In APP_DIR, supply .env.uat or .env.prod, plus matching files under cis-api/ and cis-workflow/. DEPLOY_ENV_FILE, DEPLOY_API_ENV_FILE and DEPLOY_WORKFLOW_ENV_FILE can select alternative paths. Deployment Compose remains the fixed docker-compose-deploy.yml entrypoint.
Upload storage path¶
Bitbucket's APP_DIR is forwarded over SSH and is authoritative during deployment. The server script exports HOST_UPLOADS_DIR=${APP_DIR}/data/upload, overriding stale upload paths in server environment files. Compose mounts that host directory at /data/uploads and explicitly sets the API's APP_STORAGE_LOCATION=/data/uploads inside the container. For APP_DIR=/opt/cis/backend, uploads are stored on the server at /opt/cis/backend/data/upload.
Do not set APP_STORAGE_LOCATION to the host path inside the API environment file: the process accesses the container mount path. Provision the host directory with write permissions for the API container user before deployment. Existing files under an older uploads directory are not moved automatically; copy/restore them to the new directory before switching the mount.
RustFS instead of MinIO¶
Local and deployed companion stacks now use rustfs/rustfs and the RustFS rc client (rustfs/rc) for bucket creation and the existing public bucket policy. No MinIO image, mc command or legacy MINIO variable is needed. The existing S3-compatible application property names DO_SPACE_* remain because they describe the application's S3 client rather than a particular server implementation.
- S3 endpoint:
http://rustfs:9000inside the Compose network. - Console: port 9001; server-published ports remain loopback-bound by default.
- Credentials:
RUSTFS_ACCESS_KEYandRUSTFS_SECRET_KEY, matching the API's DO_SPACE_KEY/DO_SPACE_SECRET. - Images: RUSTFS_IMAGE, RUSTFS_INIT_IMAGE and RUSTFS_PERMISSIONS_IMAGE; pin deployment-approved tags/digests through env files.
- Storage: HOST_RUSTFS_DATA_DIR; a permissions init job changes the mount root owner to RustFS uid/gid 10001. It does not recursively change existing object ownership.
- Readiness:
/health/ready; the bucket init job waits for the server and fails on command errors instead of unconditionally exiting zero. The API waits for successful bucket initialization when that companion service is enabled. - Routing/resource variables use RUSTFS names, including CIS_RUSTFS_HOST and TRAEFIK_RUSTFS_ENABLE.
The implementation follows the official RustFS Docker instructions and RustFS CLI bucket commands. Local/sample credentials must be replaced for deployment.
Existing object data is not migrated by renaming a service. Use a new RustFS data directory; do not point it at MinIO's internal data directory. Back up and copy objects using S3-compatible tooling, validate counts/content, then switch the application endpoint. Old storage is not deleted by these changes. Server files are not overwritten by the pipeline bundle: apply the new root RUSTFS variables and matching application DO_SPACE credentials/endpoint on the server before rollout.
Validation and limits¶
Restricted Bitbucket Buildx failure¶
An observed pipeline run failed before reading the Dockerfile with authorization denied by plugin pipelines: --privileged=true is not allowed, while starting moby/buildkit through the docker-container driver. publish.sh now explicitly sets DOCKER_BUILDKIT=0 so Docker 27 uses its daemon-native classic builder. Both application Dockerfiles therefore use ordinary RUN instructions rather than BuildKit-only RUN --mount cache syntax. Existing Docker layer caching remains; BuildKit cache mounts are no longer used. The regression test starts publishing with BuildKit enabled in its parent environment and verifies that both builds override it.
This follows Atlassian's documented BuildKit restrictions and disable switch. It does not enable privileged containers or change server-side deployment. A real Bitbucket rerun is still required to verify publishing on that runner.
After this fix, all 18 deployment contract checks passed, including forced classic-builder selection when the parent environment enables BuildKit. Java production/test compilation also passed; a live Docker image build remains unverified locally.
Run bash scripts/deploy/test-deployment.sh. These contract tests execute the real orchestration/server scripts against fake SSH, rsync and Docker, covering successful copy-to-execution, exact image/environment selection, secret quoting, preserved env files, and failures before/after copying. CI runs the same checks before Java compilation. Also validate each shell file with bash -n and render local/UAT/production Compose with docker compose ... config --quiet.
No real registry publish or server deployment is performed by these checks. Production acceptance still needs the configured SSH host/key, remote env/mount permissions, registry access and real application dependencies. Docker Desktop's Linux daemon was unavailable during this pass, so RustFS image startup/bucket initialization could not be exercised live; Compose rendering and the mocked deployment contracts are distinct from live integration.
Recorded validation: all 17 deployment contract checks passed, all deployment/entrypoint Bash files passed syntax checks, pipeline/Compose YAML parsed, and local/UAT/production Compose configuration checks passed. Environment scans found no legacy MinIO settings in actual or example root/API environment files. No remote deployment was initiated.
UAT readiness follow-up — 2026-10-16¶
Status: not yet ready for an unconditional UAT release. Current production and test sources compile successfully with gradle testClasses; this does not run application tests. Compose rendering confirms the aligned API/workflow Oracle service configuration, LDAP/Redis/RustFS credential consistency and upload mount. The observed restricted-runner Buildx failure has a repository fix above, pending a real Bitbucket rerun.
Outstanding code findings:
| Priority | Finding | Required action |
|---|---|---|
| Resolved in code; live Oracle validation pending | compose/oracle/init/01_import_dump.sh previously marked failed imports completed. |
SQL/OS errors now fail; only Data Pump exit 0 creates the marker. Populated schemas and concurrent/stale locks block imports; REPLACE removed. CI regression tests cover failures, empty-schema retry, partial-import refusal and success/skip. Verify legacy markers and the actual UAT import state before rollout; see compose/oracle/init/README.md. |
| High | PersistenceConfig.flywayMigrationStrategy() runs flyway.repair() automatically before migrate. With the branch's consolidated/deleted migration files, this can accept changed history instead of stopping for review. |
Remove unconditional startup repair and reconcile actual UAT history explicitly before applying the consolidated migration set. |
| High | FtpService.open() installs PrintCommandListener(PrintWriter) without login suppression, then sends the real FTP credentials. |
Remove protocol console logging or enable credential suppression, and verify secrets never reach application logs. Apache's listener implementation defaults suppression to false. |
Remaining rollout/verification conditions:
- Runtime application settings still come from server env files. Updated ignored local
.env.uatfiles are not transferred by remote.sh; update the server files through the approved configuration path, or implement secure delivery from Bitbucket settings before relying on those local corrections. - Provision writable upload/log bind mounts for the non-root application containers and migrate old uploads/object data before switching directories/services.
- Verify existing UAT Flyway history, Oracle dump contents/import result, LDAP login, mail, external FTP/SMS connectivity and RustFS bucket operations against the actual environment.
- Docker Desktop's daemon is unavailable locally, so no fresh image build, container startup or live server smoke test was completed. Existing JARs on disk were not treated as proof of a current image build.
- CI currently runs deployment contract tests and Java test-class compilation, not the full Java application test suite.
The Oracle import finding has since been addressed with guarded initialization and regression tests. Oracle migration behavior and FTP logging remain unchanged; real Oracle import validation is still pending.
CIS Notification Framework — Canonical Architecture & Developer Guide¶
[!IMPORTANT] This document is the authoritative specification and developer reference ("The Bible") for the CIS Notification Framework. It governs all notification channels (EMAIL, SMS, PDF), asynchronous event outbox queues, workflow process notifications, template resolution and caching, document artifact generation, distributed idempotency, audit ledgers, and developer extension rules across
cis-api.
1. Scope, Responsibilities and Package Ownership¶
Package Ownership¶
service.notification
NotificationService public facade
NotificationFrameworkGateway synchronous application gateway facade
model/ shared channel, request and failure-policy types
context/ context builder and shared/domain contributors
cart/, lodgement/, domain-specific context contributors
maintenance/, payment/,
reservation/, workflow/
render/ preparation, adapter registry and render results
template/ validation, cache invalidation and token checking
channel/
pdf/ PDF payload, rendering, preview and delivery adapter
email/ email payload, delivery and attachment naming
sms/ SMS payload and delivery
delivery/ generic retries, artifact handling and delivery results
artifact/ artifact processor contract and workflow document storage
asset/ image/barcode resolution, replacement factory and cache
audit/ durable delivery observations and JPA sink
idempotency/ event identity and renewable Redis ownership
queue/ durable queue worker, outbox handler and workflow notification dispatch
Framework tests mirror these responsibility packages. Cross-cutting safety tests remain beside the public facade; template composition tests remain in service.template. Packages do not add new Spring configuration: existing component scanning covers the subpackages, and the original class names, cache names, and persistence contracts are retained.
The framework composes database-managed templates and delivers PDF, EMAIL, and SMS through a shared strategy registry. All 28 active workflow notifications, the generic event listener, public email/SMS REST resources, lodgement/reservation action notifications, search sharing, expiry reminders, and task reminders enter this framework through either the durable queue (GenericEventEmailNotificationEnqueuer) or NotificationFrameworkGateway.
Core Hardening Invariants¶
- Fail-Fast Registries: The registries fail fast if two adapters or delivery strategies claim the same channel, preventing bean ordering from silently altering runtime behavior.
- Strict Boundary Validation: Render and delivery boundaries reject null commands, null contexts, empty channel selections, invalid retry counts, and rendered results whose map key does not match their declared channel.
- Payload Immutability: Prepared contexts and channel payloads remain strictly immutable once constructed.
- Identity Fallbacks: Legacy callers may omit template/workflow IDs when they provide an explicit notification event ID (
notification:<id>:<channel>); direct callers without an event ID retain the fallbackworkflowId:templateId:channel. - Deterministic Channel Sequencing:
NotificationServicesequences dependent channels;NotificationDeliveryOrchestratorowns channel lookup, ownership, retries, artifact processing, recovery, and audit. PDF delivery runs before email only when PDF is requested because the generated resource is an input to the email attachment. Domain contributors populate template variables, while transport strategies perform physical I/O.
2. Global Architecture & Component Topology¶
flowchart TD
subgraph Ingress["1. Ingress Layer (Trigger Sources)"]
WF["Workflow Engine (ProcessNotificationsVm)"]
EV["GenericEventListener (Domain Lifecycle Events)"]
SCH["Schedulers (TaskReminderService, Expiry Reminders)"]
REST["REST API Endpoints (EmailResource, SmsResource)"]
PREV["Interactive Letter Preview (Letter Previews)"]
end
subgraph EntryPorts["2. Ingress Gateways & Outbox"]
GW["NotificationFrameworkGateway (Sync Facade)"]
ENQ["GenericEventEmailNotificationEnqueuer (Outbox Enqueuer)"]
PREV_SVC["NotificationPdfPreviewService (Preview Engine)"]
DB_QUEUE[("NOTIFICATION Table (Outbox Queue)")]
Q_WORKER["NotificationQueueService (Claim & Poller)"]
GEN_SVC["GenericNotificationService (Dispatcher)"]
WF_FACTORY["ProcessNotificationFactory (28 Active Mappings)"]
end
subgraph PrepLayer["3. Preparation & Context Assembly Pipeline"]
NPS["NotificationPreparationService (Read-Only Tx)"]
NCB["NotificationContextBuilder"]
SHARED_CONTRIB["Shared Contributors (Dates, Metadata, Recipient Fallbacks)"]
DOMAIN_CONTRIB["Domain Contributors (Cart, Lodgement, Res, Maint, Workflow)"]
T_VAL["TemplateValidationService (XSS, URL & Token Guards)"]
T_DEF["TemplateDefinitionService (3-Tier Cache: ID, Name, Type)"]
RO["NotificationOrchestrator (Channel Adapter Coordinator)"]
end
subgraph ChannelAdapters["4. Channel Adapters & Renderers"]
EMAIL_ADAPT["EmailNotificationChannelAdapter"]
SMS_ADAPT["SmsNotificationChannelAdapter"]
PDF_ADAPT["PdfNotificationChannelAdapter"]
PREPARED["PreparedNotification (Immutable Context + Rendered Payloads)"]
end
subgraph DeliveryCore["5. Delivery Coordination & Safety Layer"]
NS["NotificationService (Public Delivery Facade)"]
DO["NotificationDeliveryOrchestrator"]
REDIS_LOCK[("Redis Distributed Renewable Lease")]
AUDIT_SINK["JpaNotificationAuditSink (REQUIRES_NEW Tx)"]
AUDIT_OUTBOX[("NOTIFICATION_DELIVERY_OUTBOX (Latest State)")]
AUDIT_HIST[("NOTIFICATION_DELIVERY_HISTORY (Audit Log)")]
end
subgraph ArtifactPipeline["6. Artifact Processing & Storage"]
PDF_DELIV["PdfNotificationDelivery (FlyingSaucer + Jsoup)"]
IMG_CACHE["NotificationImageCache & AssetReplacedElementFactory"]
CHAIN["ArtifactProcessorChain (@Order Directed Pipeline)"]
WF_DOC_PROC["WorkflowDocumentArtifactProcessor (Atomic Staging & Target Move)"]
STORAGE[("Shared File Storage (/workflow-docs)")]
WF_DOC_TABLE[("WORKFLOW_DOCUMENTS Table")]
end
subgraph TransportAdapters["7. Physical Transport Adapters"]
EMAIL_DELIV["EmailNotificationDelivery (JavaMail / SMTP)"]
SMS_DELIV["SmsNotificationDelivery (HTTP SMS Gateway)"]
end
%% Ingress wirings
EV --> ENQ --> DB_QUEUE
SCH --> ENQ
DB_QUEUE --> Q_WORKER --> GEN_SVC
GEN_SVC --> WF_FACTORY
GEN_SVC --> NPS
WF --> WF_FACTORY --> NPS
REST --> GW --> NPS
PREV --> PREV_SVC --> NPS
%% Prep layer wirings
NPS --> NCB
NCB --> SHARED_CONTRIB
NCB --> DOMAIN_CONTRIB
SHARED_CONTRIB & DOMAIN_CONTRIB --> T_VAL
T_VAL <--> T_DEF
NPS --> RO
RO --> EMAIL_ADAPT & SMS_ADAPT & PDF_ADAPT
EMAIL_ADAPT & SMS_ADAPT & PDF_ADAPT --> PREPARED
%% Delivery core wirings
PREPARED --> NS
NS --> DO
DO <--> REDIS_LOCK
DO --> AUDIT_SINK
AUDIT_SINK --> AUDIT_OUTBOX & AUDIT_HIST
%% Artifact & Transport wirings
DO -->|Channel: PDF| PDF_DELIV
PDF_DELIV <--> IMG_CACHE
PDF_DELIV --> CHAIN --> WF_DOC_PROC
WF_DOC_PROC --> STORAGE & WF_DOC_TABLE
WF_DOC_PROC -.->|Enrich Email with Reusable PDF Resource| NS
DO -->|Channel: EMAIL| EMAIL_DELIV
DO -->|Channel: SMS| SMS_DELIV
3. Entry Points & Invocation Routes¶
There are four runtime ingress paths into the framework:
GenericEventEmailNotificationEnqueuer: Writes an email event toNOTIFICATIONtable within the local business transaction. Its overloads provide a convenience API, not separate delivery paths.NotificationFrameworkGateway: The synchronous application facade. Exposes operations for email, email-with-attachments, SMS, composite PDF+email, and a generic channel-set operation.GenericNotificationService: The durable queue worker entry. Dispatches generic email events toGenericEventEmailNotificationHandlerand workflow events toProcessNotificationFactory.ProcessNotificationImplementations: The workflow adapter entry point. Handlers prepare context and invokeNotificationService;NotificationSchedulerandNotificationQueueServiceprovide the scheduled polling ingress around them.
The preview path (NotificationPdfPreviewService via ReservationAcknowledgementLetterService) reuses context building and PDF composition in a read-only transaction without acquiring leases, writing audit ledgers, or dispatching external transport I/O.
Open/Closed Review¶
The extension seams are open for new channels, delivery transports, renderers, context contributors, and artifact processors: implement the corresponding interface and register the Spring bean. Existing registries do not require modification.
There is one deliberate exception: NotificationService has PDF-specific sequencing because a generated PDF is an input to the EMAIL attachment payload. Adding an ordinary channel does not require changing it, but adding another artifact-dependent channel would require extending that coordinator. Treat this as a known design boundary, not as a defect.
4. End-to-End Sequence & Execution Flows¶
4.1 Complete Delivery Sequence¶
sequenceDiagram
autonumber
actor Caller as Ingress (Queue / Gateway / Workflow)
participant Prep as NotificationPreparationService
participant Ctx as Context Contributors
participant Orch as NotificationOrchestrator
participant NS as NotificationService
participant DO as NotificationDeliveryOrchestrator
participant Oracle as Oracle Outbox & History
participant Redis as Redis Renewable Lease
participant PDF as PDF Delivery & Artifact Chain
participant Trans as Transport (SMTP / SMS Gateway)
Caller->>Prep: templateId, workflowId, attributes, channels
Note over Prep: Read-Only Transaction Begins
Prep->>Ctx: Build shared, recipient and domain attributes
Ctx-->>Prep: Immutable NotificationContext
Prep->>Orch: Validate and render each requested channel
Orch-->>Prep: RenderedEmail / RenderedSms / RenderedPdf
Prep-->>Caller: PreparedNotification
Note over Prep: Read-Only Transaction Closes
Caller->>NS: notify(PreparedNotification)
Note over NS,Trans: External delivery executes outside database transaction
opt PDF Channel Requested
NS->>DO: deliver(PDF payload)
DO->>Oracle: Look up completed event/channel
alt Stored PDF Exists
Oracle-->>DO: Usable Resource and Document ID
DO->>Oracle: Record skip observation and atomic skip increment
else No Reusable PDF
DO->>Redis: Acquire token lease (5 min TTL)
DO->>Oracle: Commit PENDING (REQUIRES_NEW)
DO->>PDF: Generate and process artifact chain
PDF-->>DO: Resource and Document ID
DO->>Oracle: Commit DELIVERED and append history
DO->>Redis: Atomic compare-and-delete token
end
DO-->>NS: PDF Outcome
NS->>NS: Enrich RenderedEmail attachment list with PDF Resource
end
loop For Remaining Channels (EMAIL, SMS)
NS->>DO: deliver(Channel payload)
DO->>Oracle: Look up completed event/channel
alt Already Delivered
DO->>Oracle: Record skip observation
else Not Completed
DO->>Redis: Acquire token lease (5 min TTL)
DO->>Oracle: Commit PENDING
DO->>Trans: Send SMTP / HTTP SMS
Trans-->>DO: Accepted / OK
DO->>Oracle: Commit DELIVERED and append history
DO->>Redis: Atomic compare-and-delete token
end
DO-->>NS: Channel Outcome
end
NS-->>Caller: Aggregate Per-Channel Outcomes
4.2 Durable Outbox Two-Tier Polling Sequence¶
sequenceDiagram
autonumber
participant Sched as NotificationScheduler
participant Queue as NotificationQueueService
participant DB as NOTIFICATION Table
participant GenSvc as GenericNotificationService
participant NS as NotificationService
Sched->>Queue: pollPendingNotifications()
Queue->>DB: SELECT FOR UPDATE SKIP LOCKED (LIMIT 25, STATUS=0, NEXT_ATTEMPT <= NOW)
DB-->>Queue: Available Rows
loop For Each Row
Queue->>DB: UPDATE NOTIFICATION SET CLAIM_TOKEN=:uuid, CLAIM_UNTIL=:now+5m WHERE ID=:id
Queue->>GenSvc: handleJdbcNotification(notification)
GenSvc->>NS: Deliver via Framework
alt Delivery Succeeded
GenSvc->>DB: UPDATE NOTIFICATION SET STATUS=1, COMPLETION_DATED=:now WHERE CLAIM_TOKEN=:uuid
else Delivery Failed
GenSvc->>DB: Calculate Backoff: min(3600, 2^attempts * 15)
alt Attempts >= 8
GenSvc->>DB: UPDATE NOTIFICATION SET STATUS=2 (DEAD_LETTER), NEXT_ATTEMPT=null
else Attempts < 8
GenSvc->>DB: UPDATE NOTIFICATION SET STATUS=0, NEXT_ATTEMPT=:backoff, DELIVERY_ATTEMPTS=DELIVERY_ATTEMPTS+1
end
end
end
5. Complete Inventory of Migrated Process Notifications¶
All 28 active workflow process notifications have been migrated to dedicated NotificationContextContributor implementations and NotificationService execution:
| Template ID | Enum (ProcessTemplateType) |
Process Notification Class | Dedicated Context Contributor | Channels | Generated Artifacts / Attachments |
|---|---|---|---|---|---|
| 13 | INFORMATION_REQUEST |
InformationRequestNotification |
InformationRequestContextContributor |
None | |
| 15 | INVOICE |
InvoiceNotification |
InvoiceContextContributor |
Invoice PDF | |
| 16 | PAYMENT_CONFIRMATION |
PaymentVerificationNotification |
PaymentVerificationContextContributor |
None | |
| 17 | DISPATCH |
DispatchNotification |
DispatchContextContributor |
None | |
| 18 | INFORMATION_REJECT |
InformationRequestRejection |
InformationRequestRejectionContextContributor |
None | |
| 19 | QUERY_OUTCOME |
QueryOutcomeNotification |
QueryOutcomeContextContributor |
None | |
| 20 | QUERY |
QueryNotification |
QueryNotificationContextContributor |
None | |
| 107 | NOTIFY_MANAGER |
NotifyManagerLog |
NotifyManagerContextContributor |
None | |
| 170 | AUTO_DISPATCH |
AutoDispatchNotification |
AutoDispatchContextContributor |
None | |
| 247 | NOTIFY_MANAGER_OUTCOME |
NotifyManagerOutcomeNotification |
NotifyManagerOutcomeContextContributor |
None | |
| 268 | PAYMENT_UPLOAD |
PaymentUploadNotification |
PaymentUploadContextContributor |
None | |
| 307 | RES_NEW_REQUEST_NOTIFICATION |
ReservationNewRequestNotification |
ReservationNewRequestContextContributor |
Reservation Request Letter PDF | |
| 308 | RES_REQUEST_REJECTION_LETTER |
ReservationRequestRejectionNotification |
ReservationRejectionContextContributor |
Reservation Rejection Letter PDF | |
| 327 | RES_EXPIRY_NOTIFICATION |
ReservationExpiryEmailNotification |
Enqueued Outbox Job | Expiry Warning Notice | |
| 328 | RES_ACKNOWLEDGEMENT_LETTER |
ReservationAcknowledgementLetterNotification |
ReservationAcknowledgementContextContributor |
PDF, EMAIL | Reservation Acknowledgement Letter PDF |
| 348 | RES_NEW_REQUEST_RESUBMISSION |
ReservationRequestResubmission |
ReservationResubmissionContextContributor |
Reservation Resubmission Letter PDF | |
| 367 | LODGEMENT_NEW_REQUEST_NOTIFICATION |
LodgementNewRequestNotification |
LodgementNewRequestContextContributor |
Lodgement Request Notice PDF | |
| 368 | LODGEMENT_LETTER |
LodgementAcknowledgementNotification |
LodgementAcknowledgementContextContributor |
Lodgement Acknowledgement Letter PDF | |
| 369 | LODGEMENT_REQ_REJECTION_LETTER |
LodgementRequestRejectNotification |
LodgementRejectionContextContributor |
Lodgement Rejection Letter PDF | |
| 370 | LODGEMENT_REQ_UPDATE_AMEND |
LodgementRequestAmendNotification |
LodgementAmendContextContributor |
Lodgement Amendment Letter PDF | |
| 388 | RES_TRANSFER_APPROVAL_OUTCOME |
ReservationTransferApprovalOutcome |
ReservationTransferApprovalContextContributor |
Reservation Transfer Outcome Letter PDF | |
| 487 | RELODGEMENT_NEW_REQUEST_NOTIFICATION |
RelodgementNewRequestNotification |
RelodgementNewRequestContextContributor |
Relodgement Request Notice PDF | |
| 488 | RELODGE_LODGEMENT_LETTER |
RelodgementAcknowledgementNotification |
RelodgementAcknowledgementContextContributor |
Relodgement Letter PDF | |
| 489 | RELODGE_REQUEST_AMMEND |
RelodgeRequestAmmendNotification |
RelodgeAmendContextContributor |
Relodgement Amendment Letter PDF | |
| 490 | REQUEST_REJECTION_LETTER |
RelodgeRequestRejectNotification |
RelodgeRejectionContextContributor |
Relodgement Rejection Letter PDF | |
| 687 | MAINTENANCE_NEW_REQUEST_NOTIFICATION |
MaintenanceNewRequestNotification |
MaintenanceNewRequestContextContributor |
Maintenance Request Notice | |
| 688 | MAINTENANCE_OUTCOME_LETTER |
MaintenanceOutcomeLetterNotification |
MaintenanceOutcomeContextContributor |
Maintenance Excision Outcome Letter PDF | |
| 707 | PUBLIC_PLACE_CLOSURE_LETTER |
MaintenancePPCOutcomeLetterNotification |
MaintenancePPCOutcomeContextContributor |
Public Place Closure Letter PDF | |
| 727 | STREET_RENAME_LETTER |
MaintenanceStreetRenameOutcomeLetterNotification |
MaintenanceStreetRenameOutcomeContextContributor |
Street Renaming Outcome Letter PDF | |
| 748 | MAINTENANCE_GENERIC_COMPLETION_LETTER |
MaintenanceGenericCompletionLetterNotification |
MaintenanceGenericCompletionContextContributor |
Generic Completion Letter PDF |
6. Identity, Recipients and Context Assembly¶
The scheduler's NOTIFICATION.ID is mapped to the internal, JSON-ignored ProcessNotificationsVm.notificationId. It enters the context and produces channel keys:
notification:<id>:<channel>
Two events on the same workflow/template no longer suppress one another. Direct callers without an event ID retain the legacy workflowId:templateId:channel fallback and must supply an event ID for distinct deliveries. A retry uses the same event ID; an intentional resend creates a new notification event.
The context makes a defensive, unmodifiable map copy that permits null optional values:
* CommonPdfContextContributor supplies formatted dates and timestamps.
* TemplateMetadataContextContributor supplies template names and identifiers.
* ArtifactMetadataContextContributor supplies artifactWorkflowId consumed by the workflow artifact processor.
* CommonRecipientContextContributor supplies recipient aliases (to, cc, bcc) with delivery fallbacks.
* Domain-specific contributors add applicant details, request steps, reference numbers, and custom metadata.
Recipient selection remains the applicant's primary email/mobile. It does not switch automatically to NOTIFICATION.USER_ID or a draft alternate email.
7. Template Engine, Fragment Composition and Caching¶
NotificationPreparationService encloses context loading and HTML rendering in one read transaction. PdfNotificationChannelAdapter composes the complete HTML there; delivery receives a RenderedPdf marked as composed, avoiding later lazy entity traversal or a second Thymeleaf pass. NotificationService enriches the already rendered email with attachments without re-rendering it. Shared email formatting uses cis-emailer/email.html.
7.1 Dynamic Fragment Composition¶
PDF composition replaces common header/footer markers with database fragments:
* Missing optional fragments remain empty; processing errors propagate.
* Styles are collected into the document <head>, then Jsoup performs one XHTML conversion.
* Named media use a shared Redis byte cache; only cold/missing names enter a batched repository lookup and disk read.
* Image payloads are Base64 encoded for the Redis JSON serializer and decoded into fresh arrays for callers.
* LogoService add/update/delete rotates a shared generation after transaction completion, preventing in-flight old reads from repopulating the current namespace. Cache defaults retain the 30-minute TTL.
* NotificationAssetReplacedElementFactory consumes the image map and delegates barcode generation to the framework resolver.
flowchart LR
B[Resolved body snapshot] --> C[Compose only referenced cached fragments]
C --> T[Thymeleaf processing]
T --> J[Single Jsoup normalization: styles to head and XHTML output]
J --> F[Flying Saucer parses XHTML]
F --> A[Discover assets from the same W3C document]
A --> P[PDF layout and output]
HtmlTextGenerationService performs no Jsoup parse. TemplateUtils.convertToXhtml owns the sole Jsoup normalization/serialization pass; the replacement factory receives ITextRenderer.getDocument() and performs no HTML string parsing.
PDF file output uses a 64 KiB BufferedOutputStream to coalesce small renderer writes. Parent directories are created before opening the output; the stream is closed before file-size validation, so delayed flush/close failures follow the incomplete-file cleanup path.
7.2 Template Invalidation¶
TemplateService.saveTemplate persists and invokes TemplateInvalidationService. Invalidation defers until after commit when called inside a surrounding transaction. Direct operator SQL changes require explicit cache eviction or cache expiry.
Name-only legacy PDF fragment lookups use TemplateDefinitionService, through the template-definitions-by-name cache. All three lookup indexes (by-id, by-name, by-item-id-module) are invalidated together. The PDF adapter supplies its already-resolved body to the composer, which fetches only the common fragments whose markers actually occur. A portrait notification never fetches the landscape footer or reloads its body by name.
8. Ownership, Audit, and Recovery¶
stateDiagram-v2
[*] --> Lookup
Lookup --> Recovered: Durable completion and usable PDF if required
Recovered --> [*]: Preserve result and append skip observation
Lookup --> Claim: No completed outcome
Claim --> Deferred: Another worker owns lease
Deferred --> [*]: Queue retries later
Claim --> PENDING: Acquire token and recheck completion
PENDING --> DELIVERED: Transport and processors succeed
PENDING --> FAILED: Attempts exhausted
DELIVERED --> Released: Commit ledger and history
FAILED --> Released: Commit ledger and history
Released --> [*]: Compare-and-delete token
Lookup --> BLOCKED: Required PDF unavailable and email not already delivered
BLOCKED --> Released: Persist blocked outcome under ownership
Redis is a 5-minute renewable worker lease, not the durable success store. UUID tokens are checked during delivery, renewed every minute, and released using atomic Lua compare-and-delete. An expired worker cannot delete a newer worker's token. Lost ownership produces an uncertain failure and prevents that worker from finalizing the channel ledger. Completed outcomes are checked again after ownership acquisition.
JpaNotificationAuditSink commits independently using REQUIRES_NEW: PENDING before I/O, final state after transport and artifact processing. Final audit precedes lease release. The latest-state ledger (NOTIFICATION_DELIVERY_OUTBOX) uses optimistic versioning; skip counts use atomic increments. The same transaction appends a row to NOTIFICATION_DELIVERY_HISTORY, preserving retry and duplicate observations. Blocked dependency handling first recovers an already-delivered email instead of overwriting it. PDF recovery returns its stored path and document ID; a missing file permits regeneration.
SMTP is synchronous for framework notifications and propagates attachment/transport errors. Blank SMS templates are omitted. Nonblank SMS requires SMS_SUCCESS_RESPONSE_PATTERN, a full-match regex from the provider's accepted-response contract. Gateway credentials and message text are not explicitly logged, and RestTemplate debug URL logging is disabled. Gateway error URLs are sanitized and SMS query values are encoded. SMTP connect/read/write timeouts are exposed in environment files. External transport remains at-least-once: a crash after SMTP/provider acceptance and before Oracle outcome commit may produce a duplicate retry.
9. Crash Recovery & Staging Verification¶
Crash recovery has two independent ownership layers. The durable queue owns the NOTIFICATION row with CLAIM_TOKEN and CLAIM_UNTIL; channel delivery owns a Redis lease keyed by the event and channel. A worker must hold both ownerships while processing. If the JVM dies, the database claim and Redis lease expire independently and the next worker can retry the event. A completed Oracle channel outcome always wins over an expired lease and is reused instead of sending again.
sequenceDiagram
participant Q as Queue worker
participant N as NOTIFICATION row
participant X as Redis lease
participant O as Oracle delivery ledger
participant T as External transport
Q->>N: Claim row with token and expiry
Q->>X: Acquire event/channel lease
Q->>O: Record PENDING
Q->>T: Generate PDF or send email/SMS
alt Worker completes normally
T-->>Q: Success
Q->>O: Record DELIVERED and history
Q->>X: Compare-and-delete owned lease
Q->>N: Mark queue row complete
else Worker crashes before finalization
Note over N,X: Claim and lease expire independently
Q-->>N: No completion update
Q-->>X: No release - TTL expires
Q->>N: Next poll reclaims row
Q->>O: Recheck completed outcome
alt Completed outcome exists
O-->>Q: Reuse stored result/artifact
else No completed outcome
Q->>X: Acquire a new lease
Q->>O: Retry delivery
end
end
PDF-Specific Crash Handling¶
WorkflowDocumentArtifactProcessor makes PDF persistence retry-safe:
1. Derives a stable NOTIFICATION_KEY for the PDF channel.
2. Reuses the existing WORKFLOW_DOCUMENTS row when the event is retried.
3. Writes a .target checkpoint before replacing the target file.
4. Copies to a .part staging file and atomically moves it into place.
5. After the document transaction commits, the checkpoint is removed.
6. On a retry, an orphan checkpoint is reconciled: a PDF whose document row never committed is removed, while unrelated files are untouched.
Staging Crash Test Matrix¶
| Scenario | Inject Failure | Expected Recovery |
|---|---|---|
| Before PDF delivery | Kill worker after queue claim | Claim expires; same event is retried and completes |
| During PDF generation | Kill process before final audit | Staging/checkpoint files are reconciled; no duplicate document created |
| After workflow-document commit | Kill before channel audit | Existing document is reused by notification key |
| After SMTP acceptance | Kill before final audit | Retry may send a duplicate; history records both observations |
| Redis lease loss | Stop/block Redis during delivery | Worker cannot finalize; next worker retries after lease expiry |
| JVM restart during batch | Stop application while several rows run | Claimed rows become eligible again; no permanent stuck claim |
Staging Verification Queries¶
SELECT ID, STATUS, DELIVERY_ATTEMPTS, CLAIM_TOKEN, CLAIM_UNTIL, NEXT_ATTEMPT
FROM NOTIFICATION
WHERE ID = :notification_id;
SELECT IDENTITY_KEY, STATUS, ATTEMPTS, ERROR_MESSAGE, RECORDED_AT
FROM NOTIFICATION_DELIVERY_HISTORY
WHERE IDENTITY_KEY LIKE '%' || :notification_id || '%'
ORDER BY ID;
SELECT IDEMPOTENCY_KEY, STATUS, ATTEMPTS, ARTIFACT_PATH, DOCUMENT_ID
FROM NOTIFICATION_DELIVERY_OUTBOX
WHERE IDEMPOTENCY_KEY LIKE '%' || :notification_id || '%';
Also inspect the workflow storage directory for leftover .part files, .target checkpoint files, and duplicate {documentId}.pdf files after each injected failure.
Synchronous Gateway Boundary¶
Queue-backed workflow and generic-event notifications recover automatically. A direct NotificationFrameworkGateway call has no queue row to resume if the JVM dies during delivery; the caller must retry it, or the operation must first enqueue a durable notification event.
10. Queue Retries and Operational Recovery¶
Email PDF attachment names use the template's configured file prefix (or template name), followed by the reference number: Reservation-acknowledgement-RES0023KZN.pdf. Missing references fall back to the workflow/event/template identifier. Names are sanitized and bounded. A resource decorator changes only the MIME filename; workflow storage remains {documentId}.pdf, so document links and recovered artifacts retain their existing paths.
NotificationQueueService selects at most 25 eligible IDs, atomically claims each row with a UUID and expiry, renews claims, and updates outcomes only when its token still matches. Polls use fixed delay; expired scheduler locks do not bypass row ownership. Failed rows are delayed by:
The eighth failed attempt moves the row to STATUS = 2 (Dead Letter Queue). Status 0 is pending; status 1 is complete; status 2 is dead letter.
Operational Dead-Letter Runbook¶
After correcting the root failure, an operator can reset a dead-letter row's STATUS to 0, DELIVERY_ATTEMPTS to 0, and NEXT_ATTEMPT to null, only when it has no active claim:
UPDATE NOTIFICATION
SET STATUS = 0,
DELIVERY_ATTEMPTS = 0,
NEXT_ATTEMPT = SYSTIMESTAMP,
CLAIM_TOKEN = NULL,
CLAIM_UNTIL = NULL
WHERE ID = :notification_id
AND STATUS = 2
AND (CLAIM_UNTIL IS NULL OR CLAIM_UNTIL < SYSTIMESTAMP);
COMMIT;
Keep its event ID to resume unfinished channels. Do not delete confirmed delivery rows or flush Redis to request a new message; create a new notification event for an intentional resend.
Database Concurrency Safeguards¶
Virtual threads are enabled for the application, but database-bound event handling is bounded. AsynchronousSpringEventsConfig uses a dedicated bounded ThreadPoolTaskExecutor with configurable core/max/queue values and CallerRunsPolicy; it does not use an unbounded SimpleAsyncTaskExecutor. The default event limits are 1 core thread, 3 maximum threads, and a queue of 100. These limits must remain below the combined Oracle connection capacity reserved for the service. Hikari connection wait timeouts are environment-configurable; the development profile uses the same 30-second default as UAT and production rather than an excessive override.
11. Consolidated Schema and Environment Rollout¶
All notification DDL is consolidated in V3__notification_delivery_outbox.sql at the user's explicit request to reset earlier interim Flyway versions. V4/V5 source files were removed. The script creates/extends the ledger, history, workflow document identity, and queue ownership/retry fields. Existing rows and sequence values are preserved on reapplication.
This changes the checksum of previously applied V3. Stop notification workers and complete the explicitly agreed notification-history reset before normal Flyway startup; if V4/V5 were applied from an interim checkout, their history must be reconciled as well. Removing history is an operator action, not performed by this implementation. Do not change unrelated migration history or drop notification data merely to reapply the consolidated script.
Existing legacy workflow/template ledger keys cannot be mapped reliably to event IDs. Before requeuing pre-upgrade notifications, reconcile their already-sent outcomes to avoid resending messages after the event-key transition. Configure the provider acknowledgement regex before enabling framework SMS and ensure all nodes share workflow storage.
12. Verification & Post-Implementation Review¶
The regression suite covers recovered PDFs, failed artifact processing, unresolved ownership, distinct event identity, immutable optional null context, preserving delivered email on a blocked dependency, final audit before release, provider acknowledgement rejection, audit skip preservation, missing artifact recovery, channel selection, and template lookup.
The combined notification/event regression run passed 125 focused tests with zero failures and zero skips. Tests cover: * Queue success/backoff/contention. * Prepared attachment enrichment without re-rendering. * Event-document reuse and crash-file reconciliation without removing unrelated files. * Generic event listener transactions and in-app side effects. * Resource routing and search-share guards. * Lodgement and reservation action routing. * Expiry reminders and task reminders.
Live isolated checks also verified Redis stale-token rejection/renewal/release and Oracle consolidated V3 reapplication with delivery-row preservation. The disposable Oracle schema was removed. SGUSER schema/history was not changed, and no external email or SMS was dispatched during tests.
13. Known Bypasses and Stale Boundaries¶
The legacy EmailServiceHandler and SmsServiceHandler call sites in cis-api have been removed from the migrated notification paths. One workflow-module hook remains outside this module's framework boundary: WorkflowProcessingService calls emailHandlerService.triggerTaskEmail(...). It is intentionally not counted as a CIS API framework entry point and requires a cis-workflow change to migrate.
PDF generation is not globally unified yet. Non-notification reports and previews still call PdfGeneratorService directly (such as examination dockets and administrative reports), while notification PDF delivery uses the channel adapter and generic delivery orchestrator. The reservation acknowledgement preview now uses NotificationPdfPreviewService, which reuses framework context/template composition without creating a durable delivery. The remaining report and examination paths are valid document-generation paths today, but they do not receive queue, idempotency, durable delivery audit, or workflow-artifact semantics. Do not describe the framework as owning every PDF in the application until those contracts are deliberately migrated.
Within the framework itself, PdfNotificationDelivery remains the concrete PdfDocumentDelivery port implementation and PdfNotificationDeliveryAdapter is its generic-delivery bridge; neither is dead code.
14. Extending the Framework¶
Follow these six canonical rules when extending the notification system:
- Add an ordered domain context contributor and populate the live template variables.
- Carry the persisted notification ID into
NotificationPreparationService.prepare. - Pass the prepared payload to
NotificationService; select the supported channels. - Propagate failed results so the durable queue can back off or dead-letter the event.
- Add ordered artifact processors only for extra artifact responsibilities.
- Test event reuse, distinct events, missing optional data, transport failure, and artifact recovery.
[!CAUTION] Anti-Pattern Warning: Do NOT duplicate PDF generation, email wrapping, attachment sequencing, leases, or audit logic inside domain notification classes. The obsolete
NotificationChannelRendererand logging-only sink were removed; the adapter registry and persistent sink are the sole maintained paths.
Developer Recipes & Code Examples¶
Recipe A: Implementing a Domain Context Contributor¶
package com.dw.ngms.cis.service.notification.context.custom;
import com.dw.ngms.cis.service.notification.context.NotificationContextContributor;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;
import java.util.Map;
@Component
@Order(500)
public class CustomProcessContextContributor implements NotificationContextContributor {
@Override
public boolean supports(Long templateId, Long workflowId, Map<String, ?> attributes) {
return Long.valueOf(999L).equals(templateId);
}
@Override
public void contribute(Long templateId, Long workflowId, Map<String, ?> attributes, Map<String, Object> target) {
target.put("referenceNumber", attributes.get("referenceNo"));
target.put("statusDescription", "Approved");
// Add domain-specific template variables here
}
}
Recipe B: Triggering via Synchronous Gateway¶
@Service
@AllArgsConstructor
public class CustomAlertService {
private final NotificationFrameworkGateway notificationGateway;
public void dispatchAlert(Long workflowId, String userEmail, String referenceNumber) {
Map<String, Object> attributes = Map.of(
"referenceNo", referenceNumber,
"notificationId", UUID.randomUUID().toString()
);
// Automatically validates, prepares, acquires Redis lease, audits, and delivers
notificationGateway.sendEmail(999L, workflowId, userEmail, null, null, attributes);
}
}
Recipe C: Triggering via Asynchronous Durable Outbox¶
@Component
@AllArgsConstructor
public class CustomEventListener {
private final GenericEventEmailNotificationEnqueuer genericEmailEnqueuer;
@EventListener(condition = "#event.eventType.name() == 'CUSTOM_EVENT'")
public void onCustomEvent(GenericNotificationEvent<User> event) {
User user = event.getContent();
// Enqueues into NOTIFICATION table within the current database transaction
genericEmailEnqueuer.enqueue(
event.getEventType(),
999L,
user.getUserId(),
user.getEmail(),
null,
Map.of("firstname", user.getFirstName(), "surname", user.getSurname())
);
}
}
Recipe D: Adding a Custom Artifact Processor¶
@Component
@Order(200) // Runs after standard workflow document processor
public class CustomArchivalArtifactProcessor implements ArtifactProcessor {
@Override
public boolean supports(ArtifactContext context) {
return context.getChannel() == NotificationChannel.PDF;
}
@Override
public Resource process(Resource inputArtifact, ArtifactContext context) throws Exception {
// Perform additional operations (e.g. upload to external secure storage or add cryptographic watermark)
return inputArtifact;
}
}
Requirements
Business Requirements & Domain Workflows¶
This section documents core cadastral land administration business processes, validation rules, and approval workflows.
Process Catalog¶
- Cancellation Requirements: Rules, transitions, and fee calculations for cancelling cadastral land requests and reservations.
- Exercision Requirements: Specifications for parcel exercision and boundary subdivision processing.
- New Process Workflows: Architectural and functional specifications for introducing new cadastral workflow processes.
- Maintenance Module Analysis: Maintenance operations for administrative boundaries and parcel attributes.
Cancellation Process - Functional Breakdown¶
NOTE Review along with full FRS
1. Overview¶
Cancellation refers to the process of nullifying an existing property record or transaction due to legal, administrative, or operational reasons. This process ensures that the property status is updated and all related endorsements are removed from the system.
2. Actors Involved¶
- Maintenance Manager: Reviews and assigns tasks.
- Officer: Captures cancellation request and validates documents.
- Scrutinizer: Performs quality assurance and final checks.
- System: Handles workflow routing, notifications, and updates to property records.
3. Inputs¶
- Cancellation request letter.
- Proof of authority (e.g., court order, official directive).
- Supporting documents (e.g., title deed, previous transaction details).
4. Preconditions¶
- Property record exists in the system.
- All required documents are submitted.
- Payment verification completed (if applicable).
5. Process Flow¶
- Capture Request
- Officer selects "Cancellation" process type.
- Uploads required documents.
-
Completes mandatory fields (e.g., property ID, reason for cancellation).
-
Validation
-
System checks:
- Mandatory fields completed.
- Document formats correct.
- Authority verification (court order or directive).
-
Workflow Routing
- Task moves to Maintenance Manager for review.
- Manager assigns to Officer for processing.
- Officer completes data entry and submits for QA.
-
Scrutinizer reviews and approves/rejects.
-
System Actions
- Update property status to "Cancelled".
- Remove endorsements from diagrams and general plans.
- Trigger GIS update to reflect cancellation.
-
Generate notification letters.
-
Outputs
- Updated property record marked as cancelled.
- Notification letters sent to applicant and stakeholders.
- Audit trail updated.
6. Business Rules¶
- Cancellation must be supported by legal authority.
- All related endorsements must be removed before final approval.
- Audit trail must capture every status change and user action.
7. Integration Points¶
- Deeds Office API: For verification of title deed status.
- GIS Service: For spatial data updates after cancellation.
8. Exceptions¶
- Missing documents → Request returned to applicant.
- Invalid authority → Process halted until resolved.
- GIS update failure → Escalate to technical support.
9. Estimated Effort for Implementation¶
| Component | Effort Points (EP) |
|---|---|
| UI Form + Validation | 6 EP |
| Workflow Routing | 4 EP |
| Backend Logic | 8 EP |
| Integration (Deeds/GIS) | 6 EP |
| Document Upload & Output | 4 EP |
| Testing (Unit + UAT) | 6 EP |
| Total | 34 EP |
10. Key Screens¶
- Capture Request Screen: Dynamic fields for Cancellation.
- Maintenance Tab: Displays process status and linked documents.
- QA Checklist Screen: For Scrutinizer validation.
11. Notifications¶
- Email and system inbox alerts for:
- Task assignment.
- Approval/rejection.
- Completion of process.
12. Audit Trail¶
- Log every action:
- User ID.
- Timestamp.
- Status change.
- Comments.
Excision Process - Functional Breakdown¶
NOTE Review along with full FRS
1. Overview¶
Excision refers to the process of removing a portion of land from an existing property for allocation or other purposes. This process involves validation, approval, and updates to both alphanumeric and spatial data.
2. Actors Involved¶
- Maintenance Manager: Reviews and assigns tasks.
- Officer: Captures request details and validates documents.
- Scrutinizer: Performs quality assurance and final checks.
- Land Surveyor: Updates diagrams and plans.
- System: Handles workflow routing, notifications, and data updates.
3. Inputs¶
- Request letter from applicant.
- Consent from relevant authorities.
- Proof of payment.
- Supporting documents (e.g., survey diagrams, title deeds).
4. Preconditions¶
- Applicant must have submitted all required documents.
- Payment verification completed.
- Existing property details available in the system.
5. Process Flow¶
- Capture Request
- Officer logs into the system.
- Selects "Excision" process type.
- Uploads required documents.
-
Completes mandatory fields (e.g., property ID, portion details).
-
Validation
-
System checks:
- Mandatory fields completed.
- Document formats correct.
- Payment verified.
-
Workflow Routing
- Task moves to Maintenance Manager for review.
- Manager assigns to Officer for processing.
- Officer completes data entry and submits for QA.
-
Scrutinizer reviews and approves/rejects.
-
System Actions
- Reserve new portion number.
- Update property description in database.
- Trigger GIS update for spatial data.
-
Generate notification letters.
-
Outputs
- Updated property record.
- Endorsement on diagrams and general plans.
- Notification letters sent to applicant and stakeholders.
6. Business Rules¶
- Portion number must be unique and reserved before approval.
- All documents must be linked to the property record.
- Audit trail must capture every status change and user action.
7. Integration Points¶
- Deeds Office API: For transfer number verification.
- GIS Service: For spatial data updates.
8. Exceptions¶
- Missing documents → Request returned to applicant.
- Invalid payment → Process halted until resolved.
- GIS update failure → Escalate to technical support.
9. Estimated Effort for Implementation¶
| Component | Effort Points (EP) |
|---|---|
| UI Form + Validation | 6 EP |
| Workflow Routing | 4 EP |
| Backend Logic | 8 EP |
| Integration (Deeds/GIS) | 6 EP |
| Document Upload & Output | 4 EP |
| Testing (Unit + UAT) | 6 EP |
| Total | 34 EP |
10. Key Screens¶
- Capture Request Screen: Dynamic fields for Excision.
- Maintenance Tab: Displays process status and linked documents.
- QA Checklist Screen: For Scrutinizer validation.
11. Notifications¶
- Email and system inbox alerts for:
- Task assignment.
- Approval/rejection.
- Completion of process.
12. Audit Trail¶
- Log every action:
- User ID.
- Timestamp.
- Status change.
- Comments.
Requirements for Adding a New Maintenance Process (Example: Excision)¶
This document outlines the code changes required to add the Excision process to the system, assuming it hasn't been implemented yet. This serves as a template for adding similar maintenance processes.
1. cis-workflow Module¶
A. Register the Process Type¶
File: com.dw.ngms.cis.cisworkflow.enums.ProcessType.java
Action: Add a new Enum constant matching the ID from the WORKFLOWPROCESS table (Process ID 366).
public enum ProcessType {
// ... existing types
EXCISION_REQUEST(366L), // <--- Add this entry
// ...
}
B. Update Routing Logic¶
File: com.dw.ngms.cis.cisworkflow.service.CisBusinessService.java
Action: Update the process method to include the new enum in the switch case. This handles the event where the workflow engine links the generic MAN_DRAFT (Maintenance Draft) record to the specific running Workflow ID.
// Inside public void process(...)
switch (processType) {
// ...
case EXCISION_REQUEST: // <--- Add this case
case PROCLAMATION_OF_APPROVED_TOWNSHIP_REQUEST:
// ...
{
log.debug(" updating maintenance request with workflowId [{}] for draftId [{}]", workflowId, draftId);
// This links the draft to the workflow in the database
this.jdbcTemplate.update("update MAN_DRAFT set WORKFLOW_ID = ? where DRAFT_ID = ?", workflowId, draftId);
}
break;
}
2. cis-api Module¶
A. Register Maintenance Reason¶
File: com.dw.ngms.cis.enums.MaintenanceReason.java
Action: Add a new Enum constant. This ID corresponds to the LIST_ITEM table entry for "Excision" (ID 2486).
B. Configure Parcel Validation (Business Rules)¶
File: com.dw.ngms.cis.enums.ReasonTypeToRecordTypeList.java
Action: Define the specific Record Types that are valid for Excision. For Excision, usually only specific Record Types (e.g., ID 8 for Holdings/Farms) are valid.
public enum ReasonTypeToRecordTypeList {
// ...
/**
* for excision
*/
EXCISION(Collections.singletonList(8L)); // <--- Valid Record Type IDs
// ...
}
C. Update Search & Validation Filter¶
File: com.dw.ngms.cis.service.maintenance.MaintenanceDraftService.java
Action: Update the search method. When a user searches for a parcel to excise, we must apply the specific SQL filters to ensure they only pick valid parcels.
// Inside public Collection<SgdataParcels> search(...)
// ...
if (MaintenanceReason.EXCISION.getMaintenanceReason().equals(reasonItemId)) {
// Get the valid record types defined in Step 2B
List<Long> recordTypeItemId = ReasonTypeToRecordTypeList.EXCISION.getRecordTypeItemId();
// Add specific SQL condition:
// Excision logic might require checking Parent_RECORD_ID
sql += "AND SP.Parent_RECORD_ID in (Select RECORD_ID from SGDATA_PARCELS where RECORD_TYPE_ID in (:recordTypeId) )";
map.put("recordTypeId", recordTypeItemId);
}
// ...
D. Implement Business Outcome Logic¶
File: com.dw.ngms.cis.service.maintenance.MaintenanceDraftService.java
Action: Create the method that finalizes the Excision in the database (e.g., changing parcel status to "EXCISED"). This method is called by the workflow engine when the process reaches the "Update Database" step.
@Transactional
public void setParentParcelStatusToExcised(Long draftId){
MaintenanceDraft maintenanceDraft = maintenanceDraftRepository.findByDraftId(draftId);
if (maintenanceDraft != null) {
// Loop through steps and requests
for (MaintenanceDraftSteps mds : maintenanceDraft.getMaintenanceDraftSteps()) {
mds.getMaintenanceDraftRequests().forEach(mdr -> {
if (mdr.getRecordId() != null) {
Long recordId = mdr.getRecordId();
// 1. Fetch relevant parcels
SgdataParcels sgdataParcel = sgdataParcelsRepository.findByRecordId(mdr.getRecordId());
SgdataParcels sgdataParentParcel = sgdataParcelsRepository.findByRecordId(sgdataParcel.getParentRecordId());
// 2. Perform updates (Update LPI, Documents, Statuses)
// ... (Migration logic for notes/documents) ...
if (sgdataParcel != null && sgdataParentParcel != null) {
// Set child to APPROVED
sgdataParcel.setStatusItemId(DocumentStatus.APPROVED.getDocumentStatus());
sgdataParcelsRepository.save(sgdataParcel);
// Set parent to EXCISED
sgdataParentParcel.setStatusItemId(DocumentStatus.EXCISED.getDocumentStatus());
sgdataParcelsRepository.save(sgdataParentParcel);
}
}
});
}
}
}
3. Database Updates (Non-Code)¶
- Workflow Studio: Create the "Excision" process diagram (Process ID 366).
- List Management: Ensure
LIST_ITEMentry2486exists for "Excision". - Workflow Matrix: Ensure Action definition exists for the final step to call
setParentParcelStatusToExcised(mapped via metadata or custom listener).
Maintenance Module Analysis¶
1. Architecture Overview¶
The backend follows a Modular Monolith or Service-Oriented Architecture (SOA) built with Spring Boot.
-
Primary Modules:
cis-api: The main application handling business logic, user management, and persistence.cis-workflow: A dedicated service for handling workflow state transitions and task routing.cis-emailer: A shared module for email notifications.cis-search: A module for search functionality (integrated intocis-api).
-
Communication:
cis-apiandcis-workflowinteract via HTTP REST APIs (e.g.,cis-apitriggers tasks incis-workflow).- Shared Database (Oracle) is used for persistence across modules.
-
Database: Oracle Database (
jdbc:oracle:thin). - Security: Spring Security with OAuth2 and LDAP authentication.
2. Reusable Services & Controllers¶
The following components can be reused or extended for the Maintenance Module:
Workflow Orchestration¶
- Controller:
RoutingController(incis-workflow)- Endpoints:
/triggerTask,/processtask,/getNodeDetails. - Role: Entry point for moving workflows forward.
- Endpoints:
- Service:
WorkflowProcessDraftService&WorkflowProcessingService(incis-workflow)- Handles the creation and updating of workflow drafts.
- Business Logic Hook:
CisBusinessService(incis-workflow)- Contains specific logic for Maintenance request types (e.g.,
EXCISION_REQUEST,ENDORSEMENT_REQUEST). - Action: Extend this service to handle new Maintenance-specific logic.
- Contains specific logic for Maintenance request types (e.g.,
Document Management¶
- Services:
FileStorageService,FileDownloaderService(incis-api)- Handles file upload/download.
- Supports local storage and DigitalOcean Spaces (S3 compatible).
- Entity:
UserDocument,MaintenanceDraftDocument.
Notifications¶
- Services:
NotificationsService,EmailServiceHandler,SmsServiceHandler(incis-api).- Manages email and SMS notifications.
- Architecture:
cis-emailermodule handles the actual sending of emailscsgdata@dalrrd.gov.za.
Audit Trail¶
- Services:
LoginAuditorService,SystemLogs(entity).- Recommendation: Implement a dedicated
MaintenanceAuditServiceusingSystemLogsor similar pattern for transaction auditing.
- Recommendation: Implement a dedicated
3. Database Schema¶
The schema already contains significant support for Maintenance entities in cis-api.
Key Entities Identified¶
- MaintenanceDraft (
MAN_DRAFTtable)- Links to
User,Province,Workflow,MaintenanceDraftSteps,MaintenanceDraftAnnexures.
- Links to
- MaintenanceDraftRequest (
MAN_DRAFT_REQUEST) - MaintenanceDraftPayment (
MAN_DRAFT_PAYMENT) - CaveatService and entities exist for Caveats.
- Parcels: Access via
LodgementSgDataParcelSearchServiceor views likeVwSgdataParcels.
Extensions¶
- The
MAN_DRAFTtable handles various request types (Excision, Endorsement, etc.) viaREQUEST_TYPE_ID. - Check: Verify if
MaintenanceDraftcolumns cover all specific fields for new maintenance types, or if a JSON/EAV extension is needed inMaintenanceDraftAnnexure.
4. Workflow Integration¶
- Engine: Custom implementation driven by
cis-workflow. - Configuration:
- Flows seem to be defined via
WorkflowMatrixService/WorkflowScreenService(metadata driven). - Orchestration is triggered via
RoutingController.
- Flows seem to be defined via
- Routing:
- Tasks are assigned and routed based on the
processIdandnodeIdpassed toRoutingController. cis-apicallshttp://localhost:8091/triggerTaskto initiate/advance steps.
- Tasks are assigned and routed based on the
5. Security & Compliance¶
- Implementation: Spring Security 5 + OAuth2.
- Authentication:
- LDAP integration (
LdapSecurityConfig) withActive Directory. - JWT Tokens used for stateless authentication.
- LDAP integration (
- Access Control:
- RBAC is implemented (
RoleService,UserSecurity). - Method-level security is available (
@PreAuthorize).
- RBAC is implemented (
- SSL/TLS: Not enforced at application level (based on
httpURLs in config), likely offloaded to Load Balancer/Reverse Proxy.- Compliance Check: Ensure production
application-prod.yamluseshttps.
- Compliance Check: Ensure production
6. Integration Points¶
- Deeds Office:
- Current State: Likely integration via shared Oracle Database (
sgtrndb) or FTP (10.10.20.205). - Code: No direct REST API client found. Relies on
Parcelsdata in DB.
- Current State: Likely integration via shared Oracle Database (
- GIS Updates:
- Integration:
cis-searchmodule points to internal GIS server (http://10.10.20.210/CSGGIS). - API:
LodgementSgDataParcelSearchServiceinteracts with spatial data.
- Integration:
- Archiving:
- Managed via
FileStorageService(Local or Cloud Object Storage).
- Managed via
7. Gaps & Recommendations¶
- Deeds Interface Abstraction:
- Gap: Direct interaction code is missing or implicit via DB/FTP.
- Recommendation: Create a dedicated
DeedsOfficeServiceinterface to wrap DB/FTP interactions for better testability and potential future API upgrade.
- Workflow Visualization:
- Gap: Hard to visualize flows purely from code (
CisBusinessServicegiant switch statement). - Recommendation: Ensure
Workflow Studio(frontend/config tool) is synchronized withcis-workflowlogic.
- Gap: Hard to visualize flows purely from code (
- Maintenance Business Logic:
- Gap:
CisBusinessServiceaggregates many request types. - Recommendation: Refactor
CisBusinessServiceto use a Strategy Pattern for different Maintenance Request types (e.g.,ExcisionHandler,CancellationHandler) to avoid a monolithic service class.
- Gap:
Audits & Reports
Engineering Audits & Quality Benchmarks¶
This section preserves deep-dive architectural evaluations, performance benchmarks, and remediation tracking.
Audit Directory¶
- Application Startup Performance: Startup optimization analysis for Spring Boot services, lazy initialization findings, and container startup benchmarks.
- Compiler Warnings Remediation: Zero-warning policy enforcement, deprecation cleanups, and MapStruct/Lombok configuration.
- Consistency Checks Audit: Verification of enum alignments, module contracts, and cross-service data models.
- Persistence Package Audit: JPA entity mapping audit, table indexing recommendations, and query performance.
- Reporting Performance Audit: Performance benchmarks of report generation and document compilation under load.
- Reporting Validation Performance: Analysis of validation constraints during batch reporting runs.
- Security Remediation Walkthrough: Historical evidence walkthrough of security hardening in
cis-authandcis-bff.
Application startup and remaining-module performance audit¶
Date: 7 November 2026. Scope: cis-api startup, shared enum converters, administration/reference data, historical archive, role mapping, and selected cis-workflow/cis-bff paths. This is a focused audit, not a load-test certification of every endpoint. Reporting work was committed separately as 2f02ba390 before this changeset.
Why startup appears to pause at the converters¶
The JPA attribute converters under cis-api/.../enums/converter and cis-search/.../enums/converters translate enum constants to stored numbers/strings. They contain no repository, JDBC, or network calls. Hibernate invokes their database-column conversion during mapping/bootstrap as well as normal persistence operations. The visible DEBUG messages identify the last logged operation; they do not time the rest of JPA bootstrap.
A fresh Spring context was profiled with BufferingApplicationStartup against disposable Oracle Free 23 and Redis 7 containers, Java 25, Spring Boot 4.1.2, a 1 GiB test JVM heap, and no JaCoCo instrumentation. Container startup and bootstrap SQL completed before the Spring context measurement. No production database was accessed.
Baseline measured steps (inclusive timings; nested steps overlap and must not be summed):
| Step | Time | Evidence |
|---|---|---|
| Spring context refresh | 25.251 s | spring.context.refresh |
| Entity manager factory creation | 7.051 s | beanName=&entityManagerFactory |
| Bean-factory post-processing | 5.155 s | spring.context.beans.post-process |
| Configuration parsing | 4.500 s | 806 parsed configuration classes |
| Dynamic scheduler bean/dependencies | 2.207 s | instantiated even with scheduling disabled |
| Web server creation | 1.657 s | Tomcat factory |
| JPA repository scanning | 0.707 s | 180 repositories |
All converter messages in this run appeared within the same second, between the start and completion of entity-manager-factory initialization. That observation is not a converter microbenchmark, but neither the source nor the timing supports a claim that converters query the database or consume the whole startup delay.
Boot's overall startup message was 25.694 seconds. The roughly two-minute test process also included container provisioning and schema creation; that is not application startup latency. These measurements use the integration profile with external integrations disabled, not the deployed UAT profile.
Post-change context-refresh samples were 25.977 s and 23.537 s. In the final sample, entity-manager-factory creation took 6.495 s and configuration parsing took 4.945 s across 805 classes; the disabled dynamic scheduler was absent. This variation does not establish a consistent startup speedup. JPA/configuration bootstrap remains the main measured work.
Fixes applied in this changeset¶
- Honor disabled scheduling.
DynamicTaskManagernow uses the samecis.scheduling.enabledcondition asSchedulingConfiguration. Previously its ready-event listener and private scheduler bypassed that flag. The two tasks now share one database setting read per poll, scheduler mutation is synchronized, and its private executor shuts down with the context. Start/cancel transitions are logged without a message for every poll. - Preserve migration validation without automatic repair.
PersistenceConfignow calls onlymigrate(). Startup previously ranrepair()against the history table before every migration check. The baseline repair operation itself took only about 58 ms, so this is primarily a correctness fix and removal of unnecessary database work, not the explanation for the multi-second startup delay. Existing migration drift will now fail validation and needs an explicit reviewed migration/recovery procedure; startup no longer silently accepts it. - Remove repetitive logging from hot paths. The production logback configuration defaults the two attribute-converter packages to INFO. Response advice diagnostics moved from two eagerly formatted INFO messages per response to one parameterized TRACE message. Response envelopes and converter behavior are unchanged. Targeted DEBUG/TRACE can still be enabled for diagnosis.
- Bound reference-code lookup at the database.
ListItemServicenow uses a Spring DatafindFirstByListCodeOrderByItemCodeDescprojection. Previously it fetched every code for the list and retained only the first. Prefix, sorting direction, initial code, and activation behavior are preserved. This does not solve the existing concurrent code-allocation race; that requires a separate uniqueness/allocation design. - Add a repeatable startup profiler.
startupPerformanceTestis opt-in and excluded from normal integration execution. It reports the 25 longest Spring steps and verifies disabled scheduling plus the bounded lookup against actual Oracle SQL. It does not expose startup internals through an HTTP endpoint.
High-priority remaining findings¶
Historical Archive: full-table read plus per-row enrichment¶
Evidence: HistoricalRecordsArchiveService.java:43 calls findAll() and then filters workflowId == null in Java. HistoricalRecordsArchiveEnricher.java:36,45,54,63,72 can call repositories five times per row, including two lookups of the same packet. Actual statement counts depend on persistence-context reuse, but the service does not establish a transaction spanning the list and all enrichment.
Recommended next slice: push the workflow-null predicate into the repository; use a read projection with left joins, or collect distinct IDs and load province/list-item/packet references in bounded batches. Preserve missing-reference behavior. Add an independently paginated endpoint before changing the existing response contract; avoid silently truncating legacy responses. Verify returned fields and SQL statement counts on a representative list with repeated and missing references.
Roles/User/Sitemap: eager navigation graph on ordinary role reads¶
Evidence: Roles.java:52 eagerly loads siteMapRoles; SiteMapRole.java:33 eagerly loads each sitemap. SiteRoleService.java:45 loads all roles. Callers such as user registration and user mapping also use the role repository for fields that do not require sitemap content.
Recommended next slice: add scalar projections for ordinary role checks and user mapping; use one explicit fetch graph/query for the sitemap administration view. Verify statement counts and preserve role/access ordering and authorization behavior. A global switch to LAZY without auditing callers risks lazy-loading failures because open-in-view is disabled.
Medium-priority remaining findings¶
- Workflow publish flushes inside its province loop.
cis-workflow/.../WorkflowProcessDraftService.java:110,112callssaveAndFlushtwice per province; the service has no encompassing transaction annotation. Review the publish operation as one transaction and batch persistence, including delete ordering and sequence allocation, with rollback fixtures before changing flush behavior. - Workflow SQL logging is always enabled. All four
cis-workflowapplication YAML files setshow-sql: true; its logback also enables JDBC DEBUG. Align deployment logging with explicit diagnostic flags, then measure log volume and write latency. This is a source-level risk, not a measured production bottleneck. - Startup remains dominated by JPA and configuration work. After correcting the scheduler flag, evaluate unused configuration/module inclusion and Spring AOT against a production-like launch. Keep repository validation at readiness; do not globally enable lazy initialization just to shift errors and latency onto the first request. Measure Oracle metadata/network time and repository query validation before deciding whether either needs further tuning.
Checks and rerun commands¶
.\gradlew.bat :cis-api:test --tests 'com.dw.ngms.cis.configuration.PersistenceConfigTest' --tests 'com.dw.ngms.cis.configuration.schedular.DynamicTaskManagerTest' --tests 'com.dw.ngms.cis.service.ListItemServiceTest'
.\gradlew.bat :cis-api:startupPerformanceTest --rerun-tasks
The profiler requires Docker, uses disposable schema fixtures, and rolls back its reference-data rows. Baseline and post-change measurements are single fresh-context samples and cannot establish a statistically reliable speedup. For deployed diagnosis, collect multiple comparable starts with the same profile, data, JVM resources, database latency, and logging levels. The test report is under cis-api/build/reports/tests/startupPerformanceTest/.
Final verification passed: 207 focused unit tests (including reporting regressions) and both startup/Oracle fixture tests, with no failures or skipped tests. The ancillary contract task also passed its two tests. The initial Oracle fixture failure was corrected by supplying the required parent list-master rows. git diff --check and XML parsing of the production logback configuration passed. No full application-wide test suite or production launch was performed.
Compiler warning audit - 2026-10-31¶
Scope and result¶
A forced offline compilation covered main and test Java sources in all six root Gradle modules. The separate cis-docs/dev-guide build, IDE-only Spring/JDT inspections, additional -Xlint:all categories, runtime JVM warnings, production deployment and live database behavior are outside this audit.
The ordinary baseline emitted 30 warnings (5 in cis-search and 25 in cis-api). Deprecation and unchecked notes were expanded with -Xlint:deprecation,unchecked -Xmaxwarns 10000; no suppression or reporting-policy changes were introduced. Repeated identical file/line/message diagnostics are deduplicated below, including repetitions from Lombok processing.
The expanded baseline contains 298 emitted / 207 distinct warnings in 98 files. This expanded baseline was captured after the builder default fix; the original ordinary baseline includes its warning. After the generic fixes: 295 emitted / 204 distinct warnings. There are 35 distinct warnings in test sources.
Assessment: further warnings have practical migration paths, but zero warnings is not yet achieved. The inventory is exhaustive for these compiler flags. The proposed fixes are triage recommendations, not a claim that every application contract has already been traced or every proposed migration verified.
| Category | Remaining distinct warnings |
|---|---|
| MapStruct | 25 |
| deprecation | 105 |
| removal | 2 |
| unchecked | 72 |
| Module | Remaining distinct warnings |
|---|---|
| cis-api | 132 |
| cis-auth | 23 |
| cis-bff | 31 |
| cis-search | 15 |
| cis-emailer | 0 |
| cis-workflow | 3 |
Fixes implemented¶
- Added
@Builder.DefaulttoSectionalTitleCrossSection.sectionalTitleCrossSectionDetails. The existing initializer was ignored by Lombok builders;SchemeUtilsconstructs this entity using the builder without specifying the collection. The fix preserves an independent empty collection unless explicitly supplied. - Typed
StatefulBeanToCsv<T>and its builder incis-search/CsvWriter; file format and method signatures are unchanged. - Typed
GenericObjectPoolConfigand its constructor calls inRedisConfig; no pool defaults, Redis serializer, cache key or serialized payload was changed. - Added the JUnit Platform launcher to cis-search test runtime so its first focused CSV export test can execute.
Review priorities¶
- Persisted formats and authentication. Redis uses
Jackson2JsonRedisSerializerin both the cache manager and RedisTemplate hash values. Both activate type metadata; retain legacy serialized bytes during any Jackson 3 transition.AesPrivateKeyCipherAdapteruses deprecatedEncryptors.textfor stored signing-key encryption; changing the factory must preserve decryption of existing ciphertext. Jackson JsonNode coercion warnings also affect token/error/claim parsing. These need fixture and security regression tests, not a blanket replacement. - Mapping contracts. There are 25 unmapped-target warning sites. Some concern generated IDs/timestamps or relationship backreferences; others may represent lost data.
HraScanningChecklistDTO.documentTypeIdis commented out while the entity still has that property.LpiNotes.noteIdis generated and absent from the DTO.CartService.addToFinalCartcurrently maps the DTO twice, then saves child records separately. These facts do not justify a global IGNORE policy. Review create/update paths before introducing mappings or documented per-field ownership exclusions. - Dates and Oracle types.
HolidayCalendar,LoginAuditandUserLeaveCalendaruse deprecated JPA Temporal annotations. DATE versus TIMESTAMP and existing JSON behavior must be preserved. Dropping the annotation without migrating the Java type can change persistence semantics. - Type safety. Reporting code contains mechanical raw-map constructor warnings; template export, Redis script execution, generic response wrappers and native query results need more specific type boundaries.
DataViewerCustomImplalso uses deprecated Hibernate result transformation. Keep column aliases and the public JSON result shape stable. - Supported API replacements. Commons Lang, scheduler, lazy JPA lookup and URL constructors can be migrated in smaller groups with null/case, timing, missing-row and URL-encoding tests. Deprecated internal controllers/types require an endpoint compatibility decision before deletion.
Validation and reproduction¶
.\gradlew.bat compileJava compileTestJava --rerun-tasks --offline --console=plain
.\gradlew.bat compileJava compileTestJava --rerun-tasks --offline --console=plain --init-script build/reports/warning-audit/compiler-lint.init.gradle
The audit-only init script adds -Xlint:deprecation,unchecked and -Xmaxwarns 10000 to JavaCompile tasks. It is in ignored build output, not a permanent compiler-policy change. Raw captures: build/reports/warning-audit/full-compiler-baseline.log, expanded-compiler.log, verified-compiler.log, and focused-tests.log.
The expanded baseline and all post-change Java compile tasks completed. The initial combined validation then failed to start cis-search tests because its test runtime lacked the JUnit Platform launcher; that dependency was added. The corrected focused run completed successfully: 5 tests passed (2 builder-default tests, 2 mapper-wiring tests and 1 typed CSV export test). See focused-tests.log. All main/test compile tasks completed; this was not a full test-suite run or a live Oracle/Redis integration test.
Remaining compiler inventory¶
Every row is one distinct file/line/message diagnostic from the post-change expanded compile. Line numbers refer to this working-tree snapshot. The table includes both production and test sources.
| Source | Category | Compiler warning | Proposed work |
|---|---|---|---|
| cis-api/src/main/java/com/dw/ngms/cis/configuration/redis/CacheConfig.java:37 | removal | [removal] Jackson2JsonRedisSerializer in org.springframework.data.redis.serializer has been deprecated and marked for removal | Migrate Redis serialization with legacy-byte fixtures and cache/hash compatibility checks. |
| cis-api/src/main/java/com/dw/ngms/cis/configuration/redis/RedisConfig.java:101 | removal | [removal] Jackson2JsonRedisSerializer in org.springframework.data.redis.serializer has been deprecated and marked for removal | Migrate Redis serialization with legacy-byte fixtures and cache/hash compatibility checks. |
| cis-api/src/main/java/com/dw/ngms/cis/configuration/schedular/DynamicTaskManager.java:69 | deprecation | [deprecation] PeriodicTrigger(long,@org.jspecify.annotations.Nullable TimeUnit) in PeriodicTrigger has been deprecated | Use the Duration-based constructor; preserve initial delay and fixed-delay scheduling. |
| cis-api/src/main/java/com/dw/ngms/cis/exception/ExceptionHandlingAsyncTaskExecutor.java:29 | deprecation | [deprecation] execute(Runnable,long) in AsyncTaskExecutor has been deprecated | Use supported execution API while preserving wrapper behavior and compatibility with existing timeout callers. |
| cis-api/src/main/java/com/dw/ngms/cis/health/WorkflowHealthIndicator.java:43 | deprecation | [deprecation] URL(String) in URL has been deprecated | Use URI conversion; retain handling of malformed/encoded URLs and stream cleanup. |
| cis-api/src/main/java/com/dw/ngms/cis/persistence/domains/HolidayCalendar.java:26 | deprecation | [deprecation] Temporal in jakarta.persistence has been deprecated | Migrate Date to LocalDate/LocalDateTime with repository, Oracle column and JSON timezone tests; do not merely delete @Temporal. |
| cis-api/src/main/java/com/dw/ngms/cis/persistence/domains/HolidayCalendar.java:26 | deprecation | [deprecation] TemporalType in jakarta.persistence has been deprecated | Migrate Date to LocalDate/LocalDateTime with repository, Oracle column and JSON timezone tests; do not merely delete @Temporal. |
| cis-api/src/main/java/com/dw/ngms/cis/persistence/domains/LoginAudit.java:37 | deprecation | [deprecation] Temporal in jakarta.persistence has been deprecated | Migrate Date to LocalDate/LocalDateTime with repository, Oracle column and JSON timezone tests; do not merely delete @Temporal. |
| cis-api/src/main/java/com/dw/ngms/cis/persistence/domains/LoginAudit.java:37 | deprecation | [deprecation] TemporalType in jakarta.persistence has been deprecated | Migrate Date to LocalDate/LocalDateTime with repository, Oracle column and JSON timezone tests; do not merely delete @Temporal. |
| cis-api/src/main/java/com/dw/ngms/cis/persistence/domains/user/UserLeaveCalendar.java:37 | deprecation | [deprecation] Temporal in jakarta.persistence has been deprecated | Migrate Date to LocalDate/LocalDateTime with repository, Oracle column and JSON timezone tests; do not merely delete @Temporal. |
| cis-api/src/main/java/com/dw/ngms/cis/persistence/domains/user/UserLeaveCalendar.java:37 | deprecation | [deprecation] TemporalType in jakarta.persistence has been deprecated | Migrate Date to LocalDate/LocalDateTime with repository, Oracle column and JSON timezone tests; do not merely delete @Temporal. |
| cis-api/src/main/java/com/dw/ngms/cis/persistence/domains/user/UserLeaveCalendar.java:41 | deprecation | [deprecation] Temporal in jakarta.persistence has been deprecated | Migrate Date to LocalDate/LocalDateTime with repository, Oracle column and JSON timezone tests; do not merely delete @Temporal. |
| cis-api/src/main/java/com/dw/ngms/cis/persistence/domains/user/UserLeaveCalendar.java:41 | deprecation | [deprecation] TemporalType in jakarta.persistence has been deprecated | Migrate Date to LocalDate/LocalDateTime with repository, Oracle column and JSON timezone tests; do not merely delete @Temporal. |
| cis-api/src/main/java/com/dw/ngms/cis/persistence/repository/NotificationRepository.java:22 | deprecation | [deprecation] NonNull in org.springframework.lang has been deprecated | Use the project JSpecify annotation with equivalent null contract. |
| cis-api/src/main/java/com/dw/ngms/cis/persistence/repository/SiteMapRepository.java:9 | deprecation | [deprecation] SiteRole in com.dw.ngms.cis.persistence.domains.sitemap has been deprecated | Review deprecated application route/type compatibility before removing or replacing its use. |
| cis-api/src/main/java/com/dw/ngms/cis/persistence/repository/SiteRoleRepository.java:7 | deprecation | [deprecation] SiteRole in com.dw.ngms.cis.persistence.domains.sitemap has been deprecated | Review deprecated application route/type compatibility before removing or replacing its use. |
| cis-api/src/main/java/com/dw/ngms/cis/persistence/repository/SiteRoleRepository.java:8 | deprecation | [deprecation] SiteRole in com.dw.ngms.cis.persistence.domains.sitemap has been deprecated | Review deprecated application route/type compatibility before removing or replacing its use. |
| cis-api/src/main/java/com/dw/ngms/cis/persistence/repository/dataviewer/DataViewerCustomImpl.java:31 | unchecked | [unchecked] unchecked conversion | Use typed native query results and TupleTransformer; test Oracle aliases and returned JSON. |
| cis-api/src/main/java/com/dw/ngms/cis/persistence/repository/dataviewer/DataViewerCustomImpl.java:47 | deprecation | [deprecation] |
Review deprecated application route/type compatibility before removing or replacing its use. |
| cis-api/src/main/java/com/dw/ngms/cis/persistence/repository/dataviewer/DataViewerCustomImpl.java:47 | deprecation | [deprecation] AliasToEntityMapResultTransformer in org.hibernate.transform has been deprecated | Review deprecated application route/type compatibility before removing or replacing its use. |
| cis-api/src/main/java/com/dw/ngms/cis/persistence/repository/dataviewer/DataViewerCustomImpl.java:47 | unchecked | [unchecked] unchecked call to |
Use typed native query results and TupleTransformer; test Oracle aliases and returned JSON. |
| cis-api/src/main/java/com/dw/ngms/cis/persistence/repository/dataviewer/DataViewerCustomImpl.java:50 | unchecked | [unchecked] unchecked conversion | Use typed native query results and TupleTransformer; test Oracle aliases and returned JSON. |
| cis-api/src/main/java/com/dw/ngms/cis/persistence/repository/dataviewer/DataViewerCustomImpl.java:50 | unchecked | [unchecked] unchecked method invocation: method setData in class CustomQueryResultSetProjection is applied to given types | Use typed native query results and TupleTransformer; test Oracle aliases and returned JSON. |
| cis-api/src/main/java/com/dw/ngms/cis/security/RestMethodSecurityExpressionHandler.java:25 | deprecation | [deprecation] getTrustResolver() in DefaultMethodSecurityExpressionHandler has been deprecated | Migrate custom method-security integration with authorization and role-prefix regression tests. |
| cis-api/src/main/java/com/dw/ngms/cis/security/RestMethodSecurityExpressionHandler.java:25 | deprecation | [deprecation] setTrustResolver(AuthenticationTrustResolver) in SecurityExpressionRoot has been deprecated | Migrate custom method-security integration with authorization and role-prefix regression tests. |
| cis-api/src/main/java/com/dw/ngms/cis/security/RestMethodSecurityExpressionHandler.java:26 | deprecation | [deprecation] getRoleHierarchy() in AbstractSecurityExpressionHandler has been deprecated | Migrate custom method-security integration with authorization and role-prefix regression tests. |
| cis-api/src/main/java/com/dw/ngms/cis/security/RestMethodSecurityExpressionHandler.java:26 | deprecation | [deprecation] setRoleHierarchy(@org.jspecify.annotations.Nullable RoleHierarchy) in SecurityExpressionRoot has been deprecated | Migrate custom method-security integration with authorization and role-prefix regression tests. |
| cis-api/src/main/java/com/dw/ngms/cis/security/RestMethodSecurityExpressionRoot.java:20 | deprecation | [deprecation] SecurityExpressionRoot(@org.jspecify.annotations.Nullable Authentication) in SecurityExpressionRoot has been deprecated | Migrate custom method-security integration with authorization and role-prefix regression tests. |
| cis-api/src/main/java/com/dw/ngms/cis/security/RestMethodSecurityExpressionRoot.java:24 | deprecation | [deprecation] setDefaultRolePrefix(@org.jspecify.annotations.Nullable String) in SecurityExpressionRoot has been deprecated | Migrate custom method-security integration with authorization and role-prefix regression tests. |
| cis-api/src/main/java/com/dw/ngms/cis/security/RestMethodSecurityExpressionRoot.java:25 | deprecation | [deprecation] setDefaultRolePrefix(@org.jspecify.annotations.Nullable String) in SecurityExpressionRoot has been deprecated | Migrate custom method-security integration with authorization and role-prefix regression tests. |
| cis-api/src/main/java/com/dw/ngms/cis/service/CaveatService.java:55 | deprecation | [deprecation] equalsIgnoreCase(CharSequence,CharSequence) in StringUtils has been deprecated | Use matching null-safe Commons Lang Strings.CS/CI APIs; retain null/case behavior. |
| cis-api/src/main/java/com/dw/ngms/cis/service/CaveatService.java:100 | deprecation | [deprecation] equalsIgnoreCase(CharSequence,CharSequence) in StringUtils has been deprecated | Use matching null-safe Commons Lang Strings.CS/CI APIs; retain null/case behavior. |
| cis-api/src/main/java/com/dw/ngms/cis/service/CaveatService.java:117 | deprecation | [deprecation] equalsIgnoreCase(CharSequence,CharSequence) in StringUtils has been deprecated | Use matching null-safe Commons Lang Strings.CS/CI APIs; retain null/case behavior. |
| cis-api/src/main/java/com/dw/ngms/cis/service/ShareSearchDetailsService.java:66 | deprecation | [deprecation] URL(String) in URL has been deprecated | Use URI conversion; retain handling of malformed/encoded URLs and stream cleanup. |
| cis-api/src/main/java/com/dw/ngms/cis/service/archive/AttributeDataService.java:64 | deprecation | [deprecation] getById(ID) in JpaRepository has been deprecated | Use getReferenceById with equivalent lazy-proxy/not-found behavior and transaction tests. |
| cis-api/src/main/java/com/dw/ngms/cis/service/dto/examination/datacapture/SgdataParcelLineDeserializer.java:26 | deprecation | [deprecation] containsIgnoreCase(CharSequence,CharSequence) in StringUtils has been deprecated | Use matching null-safe Commons Lang Strings.CS/CI APIs; retain null/case behavior. |
| cis-api/src/main/java/com/dw/ngms/cis/service/examination/ExaminationService.java:84 | deprecation | [deprecation] DataCaptureCSVParserService in com.dw.ngms.cis.service.examination.datacapture has been deprecated | Review deprecated application route/type compatibility before removing or replacing its use. |
| cis-api/src/main/java/com/dw/ngms/cis/service/examination/ExaminationService.java:193 | deprecation | [deprecation] DataCaptureCSVParserService in com.dw.ngms.cis.service.examination.datacapture has been deprecated | Review deprecated application route/type compatibility before removing or replacing its use. |
| cis-api/src/main/java/com/dw/ngms/cis/service/examination/ExaminationService.java:516 | deprecation | [deprecation] equalsIgnoreCase(CharSequence,CharSequence) in StringUtils has been deprecated | Use matching null-safe Commons Lang Strings.CS/CI APIs; retain null/case behavior. |
| cis-api/src/main/java/com/dw/ngms/cis/service/examination/ExaminationService.java:1559 | deprecation | [deprecation] equalsIgnoreCase(CharSequence,CharSequence) in StringUtils has been deprecated | Use matching null-safe Commons Lang Strings.CS/CI APIs; retain null/case behavior. |
| cis-api/src/main/java/com/dw/ngms/cis/service/examination/ExaminationService.java:1568 | deprecation | [deprecation] equalsIgnoreCase(CharSequence,CharSequence) in StringUtils has been deprecated | Use matching null-safe Commons Lang Strings.CS/CI APIs; retain null/case behavior. |
| cis-api/src/main/java/com/dw/ngms/cis/service/lodgment/LodgementDraftService.java:807 | deprecation | [deprecation] getDocumentSummary(Long,Long) in LodgementDocumentSummaryService has been deprecated | Review deprecated application route/type compatibility before removing or replacing its use. |
| cis-api/src/main/java/com/dw/ngms/cis/service/lodgment/LodgementReservationSearchService.java:45 | unchecked | [unchecked] unchecked conversion | Remove raw generic boundaries/casts with explicit result types; verify caller contracts. |
| cis-api/src/main/java/com/dw/ngms/cis/service/lodgment/LodgementSchemeService.java:1153 | unchecked | [unchecked] unchecked call to writeCsvUsingDeclaredOrder(List |
Remove raw generic boundaries/casts with explicit result types; verify caller contracts. |
| cis-api/src/main/java/com/dw/ngms/cis/service/maintenance/MaintenanceDraftService.java:867 | deprecation | [deprecation] getOne(ID) in JpaRepository has been deprecated | Use getReferenceById with equivalent lazy-proxy/not-found behavior and transaction tests. |
| cis-api/src/main/java/com/dw/ngms/cis/service/maintenance/MaintenanceDraftService.java:880 | deprecation | [deprecation] getOne(ID) in JpaRepository has been deprecated | Use getReferenceById with equivalent lazy-proxy/not-found behavior and transaction tests. |
| cis-api/src/main/java/com/dw/ngms/cis/service/mapper/CartItemsMapper.java:36 | MapStruct | Unmapped target properties: "dispatchComment, dispatchStatus". | Review DTO/service ownership; map renamed fields or explicitly document server-owned fields. Preserve update semantics. |
| cis-api/src/main/java/com/dw/ngms/cis/service/mapper/CartMapper.java:14 | MapStruct | Unmapped target property: "requesterInformation". | Review DTO/service ownership; map renamed fields or explicitly document server-owned fields. Preserve update semantics. |
| cis-api/src/main/java/com/dw/ngms/cis/service/mapper/CartMapper.java:16 | MapStruct | Unmapped target properties: "addressData, requestorData". | Review DTO/service ownership; map renamed fields or explicitly document server-owned fields. Preserve update semantics. |
| cis-api/src/main/java/com/dw/ngms/cis/service/mapper/CartStageDataMapper.java:28 | MapStruct | Unmapped target property: "isProcess". | Review DTO/service ownership; map renamed fields or explicitly document server-owned fields. Preserve update semantics. |
| cis-api/src/main/java/com/dw/ngms/cis/service/mapper/CartStageDataMapper.java:38 | MapStruct | Unmapped target property: "workflowId". | Review DTO/service ownership; map renamed fields or explicitly document server-owned fields. Preserve update semantics. |
| cis-api/src/main/java/com/dw/ngms/cis/service/mapper/CartStageDataMapper.java:41 | MapStruct | Unmapped target property: "dataKeyValue". | Review DTO/service ownership; map renamed fields or explicitly document server-owned fields. Preserve update semantics. |
| cis-api/src/main/java/com/dw/ngms/cis/service/mapper/FeeTypeMapper.java:28 | MapStruct | Unmapped target property: "textBoxType". | Review DTO/service ownership; map renamed fields or explicitly document server-owned fields. Preserve update semantics. |
| cis-api/src/main/java/com/dw/ngms/cis/service/mapper/LpiNotesMapper.java:15 | MapStruct | Unmapped target property: "noteId". | Review DTO/service ownership; map renamed fields or explicitly document server-owned fields. Preserve update semantics. |
| cis-api/src/main/java/com/dw/ngms/cis/service/mapper/SystemConfigurationMapper.java:14 | MapStruct | Unmapped target property: "createdOn". | Review DTO/service ownership; map renamed fields or explicitly document server-owned fields. Preserve update semantics. |
| cis-api/src/main/java/com/dw/ngms/cis/service/mapper/archive/HistoricalRecordsArchiveMapper.java:94 | MapStruct | Unmapped target property: "isArchived". | Review DTO/service ownership; map renamed fields or explicitly document server-owned fields. Preserve update semantics. |
| cis-api/src/main/java/com/dw/ngms/cis/service/mapper/archive/HraScanningChecklistMapper.java:17 | MapStruct | Unmapped target property: "documentTypeId". | Review DTO/service ownership; map renamed fields or explicitly document server-owned fields. Preserve update semantics. |
| cis-api/src/main/java/com/dw/ngms/cis/service/mapper/archive/HraScanningChecklistMapper.java:19 | MapStruct | Unmapped target property: "documentTypeId". | Review DTO/service ownership; map renamed fields or explicitly document server-owned fields. Preserve update semantics. |
| cis-api/src/main/java/com/dw/ngms/cis/service/mapper/examination/DocketGroupRoleMapper.java:28 | MapStruct | Unmapped target properties: "groupId, docketId". | Review DTO/service ownership; map renamed fields or explicitly document server-owned fields. Preserve update semantics. |
| cis-api/src/main/java/com/dw/ngms/cis/service/mapper/examination/ExaminationConsistencyCheckMapper.java:20 | MapStruct | Unmapped target properties: "recordId, documentId". | Review DTO/service ownership; map renamed fields or explicitly document server-owned fields. Preserve update semantics. |
| cis-api/src/main/java/com/dw/ngms/cis/service/mapper/examination/ExaminationMasterMapper.java:28 | MapStruct | Unmapped target properties: "insertedDate, updatedDate". | Review DTO/service ownership; map renamed fields or explicitly document server-owned fields. Preserve update semantics. |
| cis-api/src/main/java/com/dw/ngms/cis/service/mapper/examination/SgdataDocketMapper.java:21 | MapStruct | Unmapped target property: "sgdataDocketRolesDtos". | Review DTO/service ownership; map renamed fields or explicitly document server-owned fields. Preserve update semantics. |
| cis-api/src/main/java/com/dw/ngms/cis/service/mapper/lodgment/scheme/SectionalTitleCrossSectionDetailsMapper.java:18 | MapStruct | Unmapped target property: "sectionalTitleCrossSection". | Review DTO/service ownership; map renamed fields or explicitly document server-owned fields. Preserve update semantics. |
| cis-api/src/main/java/com/dw/ngms/cis/service/mapper/lodgment/scheme/SectionalTitleCrossSectionMapper.java:18 | MapStruct | Unmapped target property: "sectionalTitleCrossSectionDetails". | Review DTO/service ownership; map renamed fields or explicitly document server-owned fields. Preserve update semantics. |
| cis-api/src/main/java/com/dw/ngms/cis/service/mapper/lodgment/scheme/SectionalTitlePlanFigureMapper.java:21 | MapStruct | Unmapped target property: "sectionalTitlePlanFigureCoordinates". | Review DTO/service ownership; map renamed fields or explicitly document server-owned fields. Preserve update semantics. |
| cis-api/src/main/java/com/dw/ngms/cis/service/mapper/report/ReportFilterConfigurationMapper.java:15 | MapStruct | Unmapped target property: "reports". | Review DTO/service ownership; map renamed fields or explicitly document server-owned fields. Preserve update semantics. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/Archive/ArchiveBusinessRuleReport.java:91 | unchecked | [unchecked] unchecked conversion | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/Archive/ArchiveNotificationReport.java:92 | unchecked | [unchecked] unchecked conversion | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/BusinessReport.java:91 | unchecked | [unchecked] unchecked conversion | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/Lodgement/LodgementBusinessRuleReport.java:92 | unchecked | [unchecked] unchecked conversion | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/Lodgement/LodgementMonthlyStatisticsReport.java:117 | unchecked | [unchecked] unchecked conversion | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/Lodgement/LodgementNotificationReport.java:92 | unchecked | [unchecked] unchecked conversion | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/Lodgement/LodgementProductionReport.java:93 | unchecked | [unchecked] unchecked conversion | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/Lodgement/LodgementUserReport.java:91 | unchecked | [unchecked] unchecked conversion | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/NotificationReport.java:92 | unchecked | [unchecked] unchecked conversion | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/ProductionReport.java:91 | unchecked | [unchecked] unchecked conversion | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/RequestStatisticalReport.java:92 | unchecked | [unchecked] unchecked conversion | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/UserHourlyLoginSummaryReport.java:91 | unchecked | [unchecked] unchecked conversion | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/UserLoginSummaryReport.java:89 | unchecked | [unchecked] unchecked call to put(K,V) as a member of the raw type HashMap | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/UserLoginSummaryReport.java:90 | unchecked | [unchecked] unchecked call to put(K,V) as a member of the raw type HashMap | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/UserLoginSummaryReport.java:91 | unchecked | [unchecked] unchecked call to put(K,V) as a member of the raw type HashMap | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/UserLoginSummaryReport.java:92 | unchecked | [unchecked] unchecked call to put(K,V) as a member of the raw type HashMap | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/UserLoginSummaryReport.java:93 | unchecked | [unchecked] unchecked conversion | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/UserLoginSummaryReport.java:93 | unchecked | [unchecked] unchecked method invocation: constructor |
Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/UserProductionReport.java:91 | unchecked | [unchecked] unchecked conversion | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/UserRegistrationQuarterlyReport.java:93 | unchecked | [unchecked] unchecked conversion | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/UserSummaryReport.java:93 | unchecked | [unchecked] unchecked conversion | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/UserUpdateHistoryReport.java:94 | unchecked | [unchecked] unchecked conversion | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/UserUpdateQuarterlyReport.java:93 | unchecked | [unchecked] unchecked conversion | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/maintenance/MaintenanceNotificationReport.java:92 | unchecked | [unchecked] unchecked conversion | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/maintenance/MaintenanceOverriddenBusinessRuleReport.java:92 | unchecked | [unchecked] unchecked conversion | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/maintenance/MaintenanceProductionReport.java:93 | unchecked | [unchecked] unchecked conversion | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/maintenance/MaintenanceUserReport.java:91 | unchecked | [unchecked] unchecked conversion | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/reservation/ReservationBusinessReport.java:92 | unchecked | [unchecked] unchecked conversion | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/reservation/ReservationProductionReport.java:93 | unchecked | [unchecked] unchecked conversion | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/reservation/ReservationStatusReport.java:95 | unchecked | [unchecked] unchecked conversion | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/report/reservation/UserReport.java:93 | unchecked | [unchecked] unchecked conversion | Add diamond/type parameters to maps and CSV/JDBC result collections; compare report output. |
| cis-api/src/main/java/com/dw/ngms/cis/service/reservation/algo/LeaseErven.java:492 | deprecation | [deprecation] equalsIgnoreCase(CharSequence,CharSequence) in StringUtils has been deprecated | Use matching null-safe Commons Lang Strings.CS/CI APIs; retain null/case behavior. |
| cis-api/src/main/java/com/dw/ngms/cis/service/reservation/algo/PublicPlaceClosure.java:52 | deprecation | [deprecation] equalsIgnoreCase(CharSequence,CharSequence) in StringUtils has been deprecated | Use matching null-safe Commons Lang Strings.CS/CI APIs; retain null/case behavior. |
| cis-api/src/main/java/com/dw/ngms/cis/service/reservation/algo/PublicPlaceClosure.java:58 | deprecation | [deprecation] equalsIgnoreCase(CharSequence,CharSequence) in StringUtils has been deprecated | Use matching null-safe Commons Lang Strings.CS/CI APIs; retain null/case behavior. |
| cis-api/src/main/java/com/dw/ngms/cis/service/reservation/algo/ReDesignation.java:79 | deprecation | [deprecation] equalsIgnoreCase(CharSequence,CharSequence) in StringUtils has been deprecated | Use matching null-safe Commons Lang Strings.CS/CI APIs; retain null/case behavior. |
| cis-api/src/main/java/com/dw/ngms/cis/service/reservation/algo/ReDesignation.java:148 | deprecation | [deprecation] equalsIgnoreCase(CharSequence,CharSequence) in StringUtils has been deprecated | Use matching null-safe Commons Lang Strings.CS/CI APIs; retain null/case behavior. |
| cis-api/src/main/java/com/dw/ngms/cis/service/workflow/AutoDispatchNotification.java:95 | deprecation | [deprecation] URL(String) in URL has been deprecated | Use URI conversion; retain handling of malformed/encoded URLs and stream cleanup. |
| cis-api/src/main/java/com/dw/ngms/cis/utilities/AlgoUtils.java:139 | deprecation | [deprecation] equalsIgnoreCase(CharSequence,CharSequence) in StringUtils has been deprecated | Use matching null-safe Commons Lang Strings.CS/CI APIs; retain null/case behavior. |
| cis-api/src/main/java/com/dw/ngms/cis/utilities/AlgoUtils.java:144 | deprecation | [deprecation] equalsIgnoreCase(CharSequence,CharSequence) in StringUtils has been deprecated | Use matching null-safe Commons Lang Strings.CS/CI APIs; retain null/case behavior. |
| cis-api/src/main/java/com/dw/ngms/cis/utilities/TemplateUtils.java:82 | deprecation | [deprecation] contains(CharSequence,CharSequence) in StringUtils has been deprecated | Use matching null-safe Commons Lang Strings.CS/CI APIs; retain null/case behavior. |
| cis-api/src/main/java/com/dw/ngms/cis/utilities/TemplateUtils.java:84 | deprecation | [deprecation] replace(String,String,String) in StringUtils has been deprecated | Use matching null-safe Commons Lang Strings.CS/CI APIs; retain null/case behavior. |
| cis-api/src/main/java/com/dw/ngms/cis/utilities/TemplateUtils.java:98 | deprecation | [deprecation] contains(CharSequence,CharSequence) in StringUtils has been deprecated | Use matching null-safe Commons Lang Strings.CS/CI APIs; retain null/case behavior. |
| cis-api/src/main/java/com/dw/ngms/cis/utilities/TemplateUtils.java:99 | deprecation | [deprecation] replace(String,String,String) in StringUtils has been deprecated | Use matching null-safe Commons Lang Strings.CS/CI APIs; retain null/case behavior. |
| cis-api/src/main/java/com/dw/ngms/cis/utilities/TemplateUtils.java:103 | deprecation | [deprecation] contains(CharSequence,CharSequence) in StringUtils has been deprecated | Use matching null-safe Commons Lang Strings.CS/CI APIs; retain null/case behavior. |
| cis-api/src/main/java/com/dw/ngms/cis/utilities/TemplateUtils.java:104 | deprecation | [deprecation] replace(String,String,String) in StringUtils has been deprecated | Use matching null-safe Commons Lang Strings.CS/CI APIs; retain null/case behavior. |
| cis-api/src/main/java/com/dw/ngms/cis/utilities/TemplateUtils.java:134 | deprecation | [deprecation] replace(String,String,String) in StringUtils has been deprecated | Use matching null-safe Commons Lang Strings.CS/CI APIs; retain null/case behavior. |
| cis-api/src/main/java/com/dw/ngms/cis/web/rest/ArchiveResource.java:262 | unchecked | [unchecked] unchecked call to ResponseResult(int,LocalDateTime,String,String,T) as a member of the raw type ResponseResult | Remove raw generic boundaries/casts with explicit result types; verify caller contracts. |
| cis-api/src/main/java/com/dw/ngms/cis/web/rest/ArchiveResource.java:265 | unchecked | [unchecked] unchecked call to ResponseResult(int,LocalDateTime,String,String,T) as a member of the raw type ResponseResult | Remove raw generic boundaries/casts with explicit result types; verify caller contracts. |
| cis-api/src/main/java/com/dw/ngms/cis/web/util/PaginationUtil.java:36 | unchecked | [unchecked] unchecked call to |
Remove raw generic boundaries/casts with explicit result types; verify caller contracts. |
| cis-api/src/main/java/com/dw/ngms/cis/web/util/PaginationUtil.java:37 | unchecked | [unchecked] unchecked call to |
Remove raw generic boundaries/casts with explicit result types; verify caller contracts. |
| cis-api/src/main/java/com/dw/ngms/cis/web/util/ResponseUtil.java:23 | unchecked | [unchecked] unchecked conversion | Remove raw generic boundaries/casts with explicit result types; verify caller contracts. |
| cis-api/src/main/java/com/dw/ngms/cis/web/util/ResponseUtil.java:25 | unchecked | [unchecked] unchecked conversion | Remove raw generic boundaries/casts with explicit result types; verify caller contracts. |
| cis-api/src/main/java/com/dw/ngms/cis/web/util/ResponseUtil.java:25 | unchecked | [unchecked] unchecked method invocation: method orElse in class Optional is applied to given types | Remove raw generic boundaries/casts with explicit result types; verify caller contracts. |
| cis-api/src/test/java/com/dw/ngms/cis/controller/archive/ArchiveResourceTest.java:2227 | unchecked | [unchecked] unchecked conversion | Type mocks/captors and collections; preserve security/error assertions. |
| cis-api/src/test/java/com/dw/ngms/cis/controller/archive/ArchiveResourceTest.java:2486 | unchecked | [unchecked] unchecked conversion | Type mocks/captors and collections; preserve security/error assertions. |
| cis-api/src/test/java/com/dw/ngms/cis/controller/archive/ArchiveResourceTest.java:3109 | unchecked | [unchecked] unchecked conversion | Type mocks/captors and collections; preserve security/error assertions. |
| cis-api/src/test/java/com/dw/ngms/cis/controller/archive/ArchiveResourceTest.java:3151 | unchecked | [unchecked] unchecked conversion | Type mocks/captors and collections; preserve security/error assertions. |
| cis-api/src/test/java/com/dw/ngms/cis/controller/unittests/controller/LodgementResourceTest.java:238 | deprecation | [deprecation] notifyForLodgement(LodgementNotificationVm) in LodgementDraftService has been deprecated | Review deprecated application route/type compatibility before removing or replacing its use. |
| cis-api/src/test/java/com/dw/ngms/cis/controller/unittests/controller/LodgementResourceTest.java:239 | deprecation | [deprecation] notifyForLodgement(@jakarta.validation.Valid LodgementNotificationVm) in LodgementResource has been deprecated | Review deprecated application route/type compatibility before removing or replacing its use. |
| cis-api/src/test/java/com/dw/ngms/cis/controller/unittests/controller/UserResourceTest.java:67 | deprecation | [deprecation] authenticateExternalUser(LoginVm) in UserService has been deprecated | Review deprecated application route/type compatibility before removing or replacing its use. |
| cis-api/src/test/java/com/dw/ngms/cis/controller/unittests/controller/UserResourceTest.java:68 | deprecation | [deprecation] authenticateUser(@jakarta.validation.Valid LoginVm) in UserResource has been deprecated | Review deprecated application route/type compatibility before removing or replacing its use. |
| cis-api/src/test/java/com/dw/ngms/cis/service/archive/ArchiveRecordsHandlerTest.java:54 | unchecked | [unchecked] unchecked conversion | Type mocks/captors and collections; preserve security/error assertions. |
| cis-api/src/test/java/com/dw/ngms/cis/service/archive/ArchiveRecordsHandlerTest.java:54 | unchecked | [unchecked] unchecked method invocation: method makeCallToWorkflowApi in class WorkflowApiCaller is applied to given types | Type mocks/captors and collections; preserve security/error assertions. |
| cis-api/src/test/java/com/dw/ngms/cis/service/archive/ArchiveRecordsHandlerTest.java:74 | unchecked | [unchecked] unchecked conversion | Type mocks/captors and collections; preserve security/error assertions. |
| cis-api/src/test/java/com/dw/ngms/cis/service/archive/ArchiveRecordsHandlerTest.java:74 | unchecked | [unchecked] unchecked method invocation: method makeCallToWorkflowApi in class WorkflowApiCaller is applied to given types | Type mocks/captors and collections; preserve security/error assertions. |
| cis-api/src/test/java/com/dw/ngms/cis/service/archive/AttributeDataServiceTest.java:123 | deprecation | [deprecation] getById(ID) in JpaRepository has been deprecated | Use getReferenceById with equivalent lazy-proxy/not-found behavior and transaction tests. |
| cis-auth/src/main/java/com/dw/ngms/cis/auth/service/adapter/AesPrivateKeyCipherAdapter.java:24 | deprecation | [deprecation] text(CharSequence,CharSequence) in Encryptors has been deprecated | Provide a versioned ciphertext migration; prove old stored signing keys still decrypt. |
| cis-auth/src/main/java/com/dw/ngms/cis/auth/service/adapter/OracleOAuth2AuthorizationService.java:117 | deprecation | [deprecation] DefaultLobHandler in org.springframework.jdbc.support.lob has been deprecated | Migrate Oracle LOB binding; test large authorization payload insert/update/read. |
| cis-auth/src/main/java/com/dw/ngms/cis/auth/service/adapter/OracleOAuth2AuthorizationService.java:120 | deprecation | [deprecation] SqlLobValue in org.springframework.jdbc.core.support has been deprecated | Migrate Oracle LOB binding; test large authorization payload insert/update/read. |
| cis-auth/src/main/java/com/dw/ngms/cis/auth/web/handler/OAuth2TokenEndpointErrorResponseHandler.java:119 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-auth/src/main/java/com/dw/ngms/cis/auth/web/handler/OAuth2TokenEndpointErrorResponseHandler.java:122 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-auth/src/main/java/com/dw/ngms/cis/auth/web/handler/OAuth2TokenEndpointErrorResponseHandler.java:125 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-auth/src/main/java/com/dw/ngms/cis/auth/web/handler/OAuth2TokenEndpointErrorResponseHandler.java:128 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-auth/src/test/java/com/dw/ngms/cis/auth/AuthorizationCodeSecurityIntegrationTest.java:162 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-auth/src/test/java/com/dw/ngms/cis/auth/AuthorizationCodeSecurityIntegrationTest.java:218 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-auth/src/test/java/com/dw/ngms/cis/auth/AuthorizationCodeSecurityIntegrationTest.java:223 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-auth/src/test/java/com/dw/ngms/cis/auth/AuthorizationCodeSecurityIntegrationTest.java:228 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-auth/src/test/java/com/dw/ngms/cis/auth/AuthorizationCodeSecurityIntegrationTest.java:281 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-auth/src/test/java/com/dw/ngms/cis/auth/AuthorizationCodeSecurityIntegrationTest.java:410 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-auth/src/test/java/com/dw/ngms/cis/auth/AuthorizationCodeSecurityIntegrationTest.java:411 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-auth/src/test/java/com/dw/ngms/cis/auth/web/filter/AuthRequestRateLimitFilterTest.java:27 | unchecked | [unchecked] unchecked conversion | Type mocks/captors and collections; preserve security/error assertions. |
| cis-auth/src/test/java/com/dw/ngms/cis/auth/web/filter/AuthRequestRateLimitFilterTest.java:27 | unchecked | [unchecked] unchecked method invocation: method execute in class RedisTemplate is applied to given types | Type mocks/captors and collections; preserve security/error assertions. |
| cis-auth/src/test/java/com/dw/ngms/cis/auth/web/filter/AuthRequestRateLimitFilterTest.java:39 | unchecked | [unchecked] unchecked conversion | Type mocks/captors and collections; preserve security/error assertions. |
| cis-auth/src/test/java/com/dw/ngms/cis/auth/web/filter/AuthRequestRateLimitFilterTest.java:39 | unchecked | [unchecked] unchecked method invocation: method execute in class RedisTemplate is applied to given types | Type mocks/captors and collections; preserve security/error assertions. |
| cis-auth/src/test/java/com/dw/ngms/cis/auth/web/filter/AuthRequestRateLimitFilterTest.java:50 | unchecked | [unchecked] unchecked conversion | Type mocks/captors and collections; preserve security/error assertions. |
| cis-auth/src/test/java/com/dw/ngms/cis/auth/web/filter/AuthRequestRateLimitFilterTest.java:50 | unchecked | [unchecked] unchecked method invocation: method execute in class RedisTemplate is applied to given types | Type mocks/captors and collections; preserve security/error assertions. |
| cis-auth/src/test/java/com/dw/ngms/cis/auth/web/handler/CredentialErrorPrivacyTest.java:26 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-auth/src/test/java/com/dw/ngms/cis/auth/web/handler/CredentialErrorPrivacyTest.java:28 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-auth/src/test/java/com/dw/ngms/cis/auth/web/handler/CredentialErrorPrivacyTest.java:39 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:73 | deprecation | [deprecation] asText(String) in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:220 | deprecation | [deprecation] asText(String) in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:227 | deprecation | [deprecation] asText(String) in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:228 | deprecation | [deprecation] asText(String) in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:251 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:255 | deprecation | [deprecation] asText(String) in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:260 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:261 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:262 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:264 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:269 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:282 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:284 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:286 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:293 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:299 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:303 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:342 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:384 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:388 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:390 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:393 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:394 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:396 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-bff/src/main/java/com/dw/ngms/cis/bff/service/adapter/RestAuthServerClientAdapter.java:401 | deprecation | [deprecation] asText() in JsonNode has been deprecated | Replace deprecated Jackson coercion API while preserving missing/null/numeric behavior; run OAuth/claim parser tests. |
| cis-bff/src/test/java/com/dw/ngms/cis/bff/integration/BffPublicAuthorizationFlowIntegrationTest.java:162 | unchecked | [unchecked] unchecked generic array creation for varargs parameter of type Optional |
Type mocks/captors and collections; preserve security/error assertions. |
| cis-bff/src/test/java/com/dw/ngms/cis/bff/integration/BffPublicAuthorizationFlowIntegrationTest.java:214 | unchecked | [unchecked] unchecked generic array creation for varargs parameter of type Optional |
Type mocks/captors and collections; preserve security/error assertions. |
| cis-bff/src/test/java/com/dw/ngms/cis/bff/web/filter/BffRateLimitingFilterTest.java:81 | unchecked | [unchecked] unchecked conversion | Type mocks/captors and collections; preserve security/error assertions. |
| cis-bff/src/test/java/com/dw/ngms/cis/bff/web/filter/BffRateLimitingFilterTest.java:81 | unchecked | [unchecked] unchecked method invocation: method execute in class RedisTemplate is applied to given types | Type mocks/captors and collections; preserve security/error assertions. |
| cis-bff/src/test/java/com/dw/ngms/cis/bff/web/filter/BffRateLimitingFilterTest.java:99 | unchecked | [unchecked] unchecked conversion | Type mocks/captors and collections; preserve security/error assertions. |
| cis-bff/src/test/java/com/dw/ngms/cis/bff/web/filter/BffRateLimitingFilterTest.java:99 | unchecked | [unchecked] unchecked method invocation: method execute in class RedisTemplate is applied to given types | Type mocks/captors and collections; preserve security/error assertions. |
| cis-search/src/main/java/com/dw/ngms/cis/mappers/SearchDocumentMapper.java:19 | MapStruct | Unmapped target properties: "sgDocumentId, userId". | Review DTO/service ownership; map renamed fields or explicitly document server-owned fields. Preserve update semantics. |
| cis-search/src/main/java/com/dw/ngms/cis/mappers/SearchDocumentMappingMapper.java:22 | MapStruct | Unmapped target properties: "mapId, documentType, documentTypeId, documentSubType, documentSubTypeId". | Review DTO/service ownership; map renamed fields or explicitly document server-owned fields. Preserve update semantics. |
| cis-search/src/main/java/com/dw/ngms/cis/mappers/SearchHistoryMapper.java:28 | MapStruct | Unmapped target properties: "id, dated". | Review DTO/service ownership; map renamed fields or explicitly document server-owned fields. Preserve update semantics. |
| cis-search/src/main/java/com/dw/ngms/cis/mappers/SearchMapper.java:18 | MapStruct | Unmapped target property: "sortId". | Review DTO/service ownership; map renamed fields or explicitly document server-owned fields. Preserve update semantics. |
| cis-search/src/main/java/com/dw/ngms/cis/mappers/SgDataParcelsMapper.java:53 | MapStruct | Unmapped target property: "status". | Review DTO/service ownership; map renamed fields or explicitly document server-owned fields. Preserve update semantics. |
| cis-search/src/main/java/com/dw/ngms/cis/service/SearchSingleRequestDownloadService.java:48 | deprecation | [deprecation] URL(String) in URL has been deprecated | Use URI conversion; retain handling of malformed/encoded URLs and stream cleanup. |
| cis-search/src/main/java/com/dw/ngms/cis/service/SearchSingleRequestDownloadService.java:78 | deprecation | [deprecation] URL(String) in URL has been deprecated | Use URI conversion; retain handling of malformed/encoded URLs and stream cleanup. |
| cis-search/src/main/java/com/dw/ngms/cis/service/TemplateSearchService.java:174 | unchecked | [unchecked] unchecked call to generateCsvResource(List |
Type CsvWriter and TemplateSearchResultDto per branch; verify all four export schemas. |
| cis-search/src/main/java/com/dw/ngms/cis/service/TemplateSearchService.java:189 | unchecked | [unchecked] unchecked call to setResults(Collection |
Type CsvWriter and TemplateSearchResultDto per branch; verify all four export schemas. |
| cis-search/src/main/java/com/dw/ngms/cis/service/TemplateSearchService.java:243 | unchecked | [unchecked] unchecked call to generateCsvResource(List |
Type CsvWriter and TemplateSearchResultDto per branch; verify all four export schemas. |
| cis-search/src/main/java/com/dw/ngms/cis/service/TemplateSearchService.java:260 | unchecked | [unchecked] unchecked call to setResults(Collection |
Type CsvWriter and TemplateSearchResultDto per branch; verify all four export schemas. |
| cis-search/src/main/java/com/dw/ngms/cis/service/TemplateSearchService.java:314 | unchecked | [unchecked] unchecked call to generateCsvResource(List |
Type CsvWriter and TemplateSearchResultDto per branch; verify all four export schemas. |
| cis-search/src/main/java/com/dw/ngms/cis/service/TemplateSearchService.java:330 | unchecked | [unchecked] unchecked call to setResults(Collection |
Type CsvWriter and TemplateSearchResultDto per branch; verify all four export schemas. |
| cis-search/src/main/java/com/dw/ngms/cis/service/TemplateSearchService.java:382 | unchecked | [unchecked] unchecked call to generateCsvResource(List |
Type CsvWriter and TemplateSearchResultDto per branch; verify all four export schemas. |
| cis-search/src/main/java/com/dw/ngms/cis/service/TemplateSearchService.java:398 | unchecked | [unchecked] unchecked call to setResults(Collection |
Type CsvWriter and TemplateSearchResultDto per branch; verify all four export schemas. |
| cis-workflow/src/main/java/com/dw/ngms/cis/cisworkflow/exception/ExceptionHandlingAsyncTaskExecutor.java:29 | deprecation | [deprecation] execute(Runnable,long) in AsyncTaskExecutor has been deprecated | Use supported execution API while preserving wrapper behavior and compatibility with existing timeout callers. |
| cis-workflow/src/main/java/com/dw/ngms/cis/cisworkflow/exception/ExceptionHandlingAsyncTaskExecutor.java:30 | deprecation | [deprecation] execute(Runnable,long) in AsyncTaskExecutor has been deprecated | Use supported execution API while preserving wrapper behavior and compatibility with existing timeout callers. |
| cis-workflow/src/main/java/com/dw/ngms/cis/cisworkflow/service/WorkflowProcessDraftService.java:71 | deprecation | [deprecation] getOne(ID) in JpaRepository has been deprecated | Use getReferenceById with equivalent lazy-proxy/not-found behavior and transaction tests. |
ConsistencyCheck audit and refactor — 2026-11-01¶
Scope and actual call path¶
Reviewed the complete service/examination/consistency/ConsistencyCheck.java, its calculation/result models, number-format utilities and current callers. Implemented a behavior-preserving internal refactor of this class and added characterization/concurrency tests.
The active application path found is ExaminationResource.getNextParcelLine → ExaminationService.getNextParcelLine → ConsistencyCheck.calculateNextParcelLine → the existing response mapper. No main-source caller of this class's two-argument doConsistencyCheck was found. The main figure-consistency flow uses ConsistencyHelper → GenericConsistencyCheckFactory → separate IConsistencyCheck algorithms. Those algorithms were not changed or certified by this refactor.
Findings addressed¶
| Priority | Original issue | Implemented change |
|---|---|---|
| High | A singleton Spring component stored perimeter, coordinate maps, residual maps and other request results in instance fields. Concurrent calls could overwrite another calculation's state. | Keep Messages as the only instance field, inject it through the constructor, and hold all calculations in local variables. Pass the five assessment maps through a private invocation-local record. |
| High | Both public calculation paths called shared mutable NumberUtils decimal formatters. |
Clone the existing configured formatters for each invocation. Only the copies perform formatting, retaining their existing symbols, patterns and rounding configuration. Other consumers of NumberUtils are outside scope. |
| Medium | Every X/Y residual calculation searched the entire input list for the matching start point. | Build a start-point index once, reducing expected lookup work from O(n²) to O(n). Keep case-sensitive matching and the original first-match behavior for duplicate labels. Null labels retain the old contextual-error scan path. |
| Low | Intermediate dy/dx/angle calculations were stored but never used in the returned outcome or final decision. Several comments described abandoned branches. | Remove unused intermediate calculations and obsolete comments; keep all formulas that contribute to returned values and decisions. |
| Low | A regulatory limit was assigned and then overwritten; an exception property was assigned to an outcome that was immediately discarded by rethrowing. | Remove those dead assignments while preserving the final regulatory limit and thrown exception behavior. |
| Low | Misclosure labels required multiple passes, and assessment construction used a stream with mutable exception-context side effects. | Collect misclosed side names once and build assessment rows with an explicit ordered loop. Retain list order, duplicate labels and existing output text. |
Java documents that DecimalFormat instances are generally unsynchronized and recommends separate instances for concurrent use. Java SE 25 reference
This is a structural concurrency/performance correction, not a benchmark result. No latency or production throughput claim is made.
Numerical and response behavior retained¶
- The same public method names/signatures and request/response model types remain. Only object construction changes to constructor injection.
- Angles use the existing DMS expression and four-digit format/parse rounding.
- Assessed X/Y coordinates still use the public
Math.round-basedroundAvoidat two places. Next-line coordinates still use the distinct decimal-format rounding path. Those rounding methods were deliberately not unified. - Coordinate residuals retain their four-digit formatting, lookup signs and first-duplicate semantics.
- Area retains its signed result, intermediate double/BigDecimal operations,
MathContext(15), map-key representation and two-digit formatting. No absolute-area substitution was introduced. - Closure tolerance remains
0.02 + perimeter * sqrt(sideCount) / 10000; area tolerance remains2 + perimeter² * sqrt(sideCount) / 80000. The perimeter is rounded at the same stage as before; expression order was preserved. - Existing
>and<=decisions, zero-denominator behavior, misclosed-side label order, start/end coordinate maps, area/line order fields, null/default fields and serialized numeric strings are retained for the characterized inputs. calculateNextParcelLinestill returns a new entity containing only the calculated coordinates; it does not copy source IDs or other metadata. Inputs remain unmodified.- Explicit validation/error messages and the empty-list failure type are covered by regression tests. This is not a guarantee that incidental JVM-generated null-dereference text is a stable API contract.
Logic concerns deliberately preserved¶
These findings need a separate domain decision because correcting them can change results. They were not silently folded into a behavior-preserving refactor.
High — Misclosure tests a ratio rather than residual magnitude¶
Assessed-row calculation sets dyByDx to zero when dx == 0, and getSideMisClosure tests whether the ratio is nonzero. A pure Y residual can therefore escape the line misclosure flag; a pure X residual also yields a zero ratio. Conversely, a nonzero ratio marks a line without comparing a residual distance against closure tolerance.
Recommended separate fix: establish the intended survey rule and units, then compare the approved residual magnitude/closure metric with its tolerance. Add explicit X-only, Y-only, diagonal and boundary tests. Do not assume a mathematically plausible replacement is the approved business rule. The golden vertical-only-residual case records the current behavior.
Medium — Area keys assume single-character labels¶
Area-key decoding uses fixed character offsets and single-character substrings. Multi-character point names can produce incorrect areas or failures.
Recommended separate fix: replace encoded strings with a typed point-pair representation and an explicitly ordered coordinate lookup. First decide how duplicate labels and mixed case should behave; retain a separate legacy path or migrate consumers with representative data fixtures.
Medium — Endpoint closure is not complete diagram validation¶
Validation compares the first start label with the final end label, ignoring case. It does not establish continuity of all intermediate sides, label uniqueness, minimum side count or finite coordinates/distances. Subsequent point lookup is case-sensitive.
Recommended separate fix: define supported diagrams and input validation at the application boundary, then validate all links and numeric values. Decide case normalization explicitly. Preserve error envelopes and coordinate response formats; expect acceptance/rejection behavior to change.
Medium — Locale-sensitive formatting is parsed as locale-independent numbers¶
Existing decimal symbols are preserved, including the inherited assumption that formatted output is acceptable to Double.parseDouble. Comma-decimal locales remain a concern. Double2dSerializer also formats through the default locale, separately from this class.
Recommended separate fix: define the application's numeric locale contract and standardize parsing/rounding and serialization together, with fixtures for decimal separators, negative ties and signed zero. Replacing format/parse rounding with BigDecimal.setScale can change binary-tie behavior and needs parity tests.
Verification¶
Before changing production code, captured two golden files from the original implementation:
- 12 full figure outcomes, each recording raw values and serialized JSON. Cases include square/triangle geometry, both orientations, incorrect area, fractional negative coordinates, duplicate start labels, DMS inputs, zero distance, pure-Y residual and area-tolerance boundaries.
- Six next-line results, covering cardinal directions, fractional DMS, negative coordinates/distances and negative rounding ties.
ConsistencyCheckTest now compares against those immutable captured expectations. It does not regenerate expected values during test execution.
The class has 17 passing tests, including raw/serialized parity, unchanged inputs, explicit failures, public-rounding behavior, 96 concurrent full calculations and 96 concurrent next-line calculations on shared instances. Eight workers synchronize their start to exercise overlapping requests. No Oracle/Redis services are involved.
The combined run also includes all six mapper migration checks: 23 tests passed, zero failures/errors/skips. Main and test compilation completed as part of that run, with existing unrelated deprecation notes. This was not a complete repository test suite, HTTP endpoint test, live-data survey verification or review of the other consistency algorithms.
cis-api persistence audit — 2026-11-01¶
Result and scope¶
The compilation blockers are fixed. The persistence audit covers the full cis-api/src/main/java/com/dw/ngms/cis/persistence tree, rather than a user-repository sample. Findings below are proposed work. The subsequent mapper constructor-injection migration changes dependency wiring and preserves the query/mapping behavior identified here; the persistence optimizations remain proposed work. Source line references below identify the audit snapshot before that migration.
| Package | Java files | Screening performed |
|---|---|---|
| domains | 193 | Associations, explicit/default eager loading, collection fetches, batching, identifiers, named native queries and result mappings |
| repository | 170 | Query annotations, derived methods, entity graphs, pagination/counts, scalar/entity returns, modifying queries, custom SQL implementation |
| projection | 168 | Getter/alias candidates, nested entity references, scalar read-model suitability |
| rowmapper | 43 | Repository access, duplicate column reads, nullable numbers/timestamps, producer SQL aliases |
| views | 5 | Association exposure, identity and mutability risks |
| Total | 579 | 25,246 source lines; 389 repository @Query declarations |
The complete inventory lists every file, source size, structural signals and repository query declarations. All files received structural screening; the concrete findings received targeted source and consumer review. An inventory entry without a finding is not a claim of runtime correctness. This is not a line-by-line business-rule certification of all 579 files.
Repeated application repository calls are confirmed from source. Actual SQL counts, row amplification, latency, database constraints/indexes, view uniqueness and Oracle execution plans were not measured. First-level identity reuse and query caches can affect SQL counts, so repository call counts below must not be reported as measured SQL counts.
Current build files select Java 25, Spring Boot 4.1.2 and Gradle 9.8.2. Older skill/version notes are not the authority for this snapshot.
Compilation fixes implemented¶
SearchDocumentMapperDecorator, SgDataParcelsDecorator and WorkflowNotesDecorator each had a constructor accepting the delegate plus another dependency. MapStruct's generated decorator subclass could not call those constructors. Simply adding an empty constructor would leave those dependencies uninitialized.
The three mappers now use constructor-injected collaborator components with @AfterMapping hooks. Existing enrichment is retained: document URL/image prefixes, parcel status captions and workflow usernames. The helper classes retain their existing names. Their repository lookup behavior is intentionally still visible in the audit below; changing the hook mechanism does not fix N+1 by itself.
Request models, response DTOs, controller signatures and repository query semantics were not changed. Generated implementations were inspected, not edited. The generated mapping handles null sources before running hooks; this also avoids the old document decorator's null dereference for a null source.
Validation:
./gradlew.bat :cis-api:compileJava— passed, with warnings../gradlew.bat compileJava compileTestJava— passed across all six root modules; some tasks were up to date../gradlew.bat :cis-search:test --tests '*MappingEnrichmentTest' :cis-api:test --tests '*WorkflowNotesMappingTest'— passed: three tests, zero failures/errors. These are isolated Spring wiring/mapping tests without Oracle.- Tests exercise forward mapping, enrichment, selected reverse mappings and null-source handling. They do not constitute full HTTP/JSON parity or a full application-context startup test.
High-priority findings and fixes¶
P01 — User lists perform per-user and per-role repository lookups¶
Evidence: UserService:121, UserMapperDecorator:134, User:91, Roles:52.
The page mapper queries status/type/title/province, organization/sector and each role's reference data. User roles are eager; metadata is a default-eager one-to-one. Loading roles can also load their eager collection. UserRoleMapperDecorator independently performs role/province/section lookups when used directly; do not assume it currently runs inside UserMapper (see P14).
Fix: load the page or a scalar page projection; batch roles/metadata and distinct reference IDs for those users; assemble lookup maps; map with no database calls. Use lightweight role/name projections to avoid pulling unrelated role data. Keep Page.map/page metadata and every existing nested DTO field. Chunk large IN requests for the deployed Oracle limits. Test multiple users with distinct and shared roles, missing lookup rows and empty metadata. Compare 1-user and 20-user cold-session statement counts.
P02 — Assistant listing adds another query per result¶
Evidence: UserService:139.
Each assistant is fully mapped, then findByUserIdAndAssistantId is called for that row.
Fix: query all relationships for the professional once, index by assistant ID, and combine with the batched user assembler from P01. Retain assistantId, assistantStatusId and current ordering. Test multiple assistants, duplicate/absent relationships and status values.
P03 — Lodgement and reservation list projections are followed by per-row entity reads¶
Evidence: LodgementDraftService:157, LodgementDraftDecorator:59, ReservationDraftDecorator:59.
The short draft projection is followed by a province and a full-user lookup per row. Full users bring P01's eager associations even when only a name is needed.
Fix: select the existing display fields in the projection using left joins, or batch name/province projections after paging. Keep full-name versus username behavior separate: the lodgement entity mapper assembles a full name, whereas its short-projection mapper uses userName. Preserve existing empty-string fallbacks. Test first/last pages, missing users/provinces and leading/trailing spaces.
P04 — Lodgement steps nest per-step lookups and per-building section loads¶
Evidence: LodgementDraftStepsDecorator:74, SchemeSchemeDecorator:30.
Each step looks up captions, counts documents and fetches a scheme. Each scheme loads all buildings and then loads each building's sections to calculate counts.
Fix: collect step and scheme IDs, batch schemes/captions, query document counts grouped by step, building counts grouped by scheme and section counts grouped by scheme. Use separate aggregates or COUNT(DISTINCT ...) to avoid multiplying counts across joins. Do not load section entities to call .size(). Preserve the current empty SchemeSchemeDto fallback and zero counts. Test two buildings with several sections and schemes without buildings.
P05 — Detail entity graphs fetch several sibling collections¶
Evidence: LodgementDraftRepository:20, ReservationDraftRepository:20.
These graphs include annexures/payments/steps/requests/documents or documents/steps/requests/outcomes. They can produce amplified result sets or substantial secondary loading. This is a fetch-plan risk, not a measured Cartesian product. Set de-duplication does not itself reduce transferred rows.
Fix: load the root once and fetch the required child groups in separate queries or controlled batches inside a read transaction. Keep detail responses complete, including empty collections and ordering. Avoid introducing multi-collection fetch joins into paged list queries. Measure returned SQL rows as well as statement counts; fewer statements can still be slower.
P06 — Leave pagination declares non-scalar count queries¶
Evidence: UserLeaveCalenderRepository:25.
Both explicit countQuery strings select * instead of a count. Pages requiring a count can fail or produce invalid totals; small result sets can mask this by avoiding the count execution.
Fix: replace only the count selections with COUNT(*), preserving each existing filter/subquery. Verify the reporting-user relationships separately before changing those predicates. Oracle integration tests must include more rows than the page size and verify totals and last-page headers.
P07 — Help auditing uses the globally latest login instead of the acting user¶
Evidence: UserLoginHistoryRepository:14, HelpService:32.
The query selects the user from the globally greatest login timestamp. Every help row repeats this lookup and inserts an audit row. Concurrent logins can attribute another user's help activity; tied timestamps can return multiple rows.
Fix: derive the actor once from the authenticated principal at service entry, then retain the existing per-help-row audit semantics while batching writes where appropriate. Remove the global-latest-login dependency from this consumer. Test simultaneous sessions, same-timestamp logins and empty login history. This changes incorrect audit attribution, not the response format.
P08 — Read-then-increment numbering is unsafe under concurrency¶
Evidence: LocationRepository:24, ArcPacketRepository:18, PacketService:77, UserMapperDecorator:57.
Location IDs use MAX+1; packet numbers read a maximum before incrementing; user codes read the last user. Packet maximum accepts provinceId but does not use it. The intended global/province/year number scope must be established before fixing that predicate.
Fix: use an approved Oracle sequence for technical IDs or a locked counter row for business numbers scoped by the actual numbering rule, with a matching unique constraint. Keep the existing formatted codes and response types. Handle empty tables. Concurrency tests must issue simultaneous creates. Inspect current sequence increments and ownership before any DDL; do not change applied migrations or broadly increase allocation sizes.
P09 — Data viewer executes raw SQL and materializes all results¶
Evidence: DataViewerCustomImpl:37, DataViewerService:97, DataViewerResource:76.
The object name is concatenated into a count query; the supplied query is executed directly, using deprecated setResultTransformer, and all rows are materialized. The count measures the whole object rather than the filtered query. The web request reaches this implementation. This audit does not establish the complete effective authorization or database-privilege boundary.
Fix: resolve approved objects server-side, enforce a defined read-only SQL/query feature contract with a database read-only principal, bind filter values, and use setTupleTransformer or a typed JDBC extractor preserving map keys/types. Stream background CSV exports with explicit resource/transaction lifetimes. Define whether totalCount means object rows or filtered results before changing it. Adding row caps or restricting supported query grammar needs a product/API behavior decision; it is not silently contract-neutral.
Medium-priority findings and fixes¶
P10 — Eager loading extends beyond users¶
Evidence: Cart:40, CartStage:40, MaintenanceDraft:79, MaintenanceDraftService:158.
Explicit eager associations occur in 19 domain files, including lodgement batch/request/document/step, scheme child collections, roles, province, sitemap and users. Default-eager to-one mappings add more; explicit FetchType.EAGER searches alone are insufficient. Maintenance list retrieval returns entities with user/province/list-item references, even though child collections use batching and lazy-aware mapping conditions.
Fix: use list projections or a deliberate to-one fetch plan, then examine child loads by endpoint. Preserve LazyLoadingAwareMapper conditions: switching fetch plans can change which response collections are populated. With open-in-view: false, mapping must finish inside the read-service transaction. Do not globally change associations to LAZY without endpoint parity and missing-row tests.
P11 — Notes, captions, report labels and fee conversion repeat lookups¶
Evidence: DocketNotesDecorator:28, WorkflowNotesDecorator, TemplateMapperDecorator:26, BusinessReport:74, CartJsonToCartItemConvertor:380.
Similar patterns occur in examination stamping/caveats, parcel figures, lodgement document/payment/annexure decorators and reservation step captions. Fee conversion queries by a multi-field pricing key per item.
Fix: batch lightweight user-name and reference projections per operation; for prices, batch or memoize by the complete pricing key within the request. Avoid shared mutable caches unless invalidation and fee effective-date behavior are defined. Keep username/full-name differences, missing-row handling and invoice rounding unchanged.
P12 — Productivity generation queries repeatedly for every action and day¶
Evidence: ProductivityReportGenerator:60.
The all-history path loads all action projections, deletes per action, then checks holiday/office/leave data and writes productivity rows in a day loop. This can grow with actions multiplied by days; it is an application query amplification problem rather than association traversal alone.
Fix: process stable action-ID chunks, preload calendars/office intervals/leave for each chunk's user/province/date range, bulk-delete the selected action IDs, and batch replacements. Retain interval precedence, open-action time handling and transaction/rollback behavior. Use a fixed clock and multi-day fixtures, including holidays overlapping leave.
P13 — Plan Safe draft query compares to null with equality¶
Evidence: PlanSafeDocTrackingRepository:47, consumer PlanSafeDocTrackingService.getAllPlanSafeDocTrackings.
t.workflowId=null is not the correct JPQL null predicate.
Fix: use t.workflowId IS NULL, leaving projection fields and joins unchanged. Verify with one unsubmitted and one submitted record. This deliberately repairs result membership; it does not alter the DTO format.
P14 — Mapper collaborators are declared as imports and response/write directions are coupled¶
Evidence: UserMapper:15, generated UserMapperImpl_ inspected during this audit.
imports makes types available to generated expressions; it does not delegate nested mapping. The current generated user mapper creates its own nested conversion methods. Replacing imports with uses can activate decorated mappings and change fields/query counts. Broad ReportingPolicy.IGNORE also hides missing target handling.
Fix: first lock down current DTO fixtures, then introduce pure read mappers with explicit uses, a shared @MapperConfig, constructor injection and unmappedTargetPolicy = ERROR for migrated mappers. Supply preloaded enrichment via explicit inputs or immutable @Context. Keep repository access out of new mapping helpers. Separate create/update mapping; load entities in services and use narrowly configured @MappingTarget updates. Preserve existing null/empty behavior rather than setting a global null-ignore policy. Registration password encoding, timestamps and identity generation belong in a service/factory. Do not use enriched response DTOs as automatic inverse write definitions.
P15 — Projection fields and selected aliases do not always match¶
Evidence: InvoicePerformaRepository:31, InvoicePerformaProjection:17.
getPerformaInvoiceByDraftId omits perItemCost, while the same projection's parent-history query selects it. Additional candidate omissions occur in dashboard monthly distributions, shared workflow/application projections, scheme history and document summaries. Shared projection supersets may intentionally leave some properties null; a textual alias mismatch is not automatically a defect.
Fix: verify each consumer before adding values; use smaller internal projections per query and map into the existing external response shape. Add native-query alias/type tests against Oracle. Preserve intentional nulls; filling a previously null field is a behavior change even with identical JSON keys.
P16 — Examination report row mapper reads the wrong column¶
Evidence: row mapper:23, producer SQL:95.
The SQL aliases ERVEN as survitudePlan; the mapper reads SURVEYRECORD for both the servitude and survey-record fields. This duplicates the wrong value.
Fix: read the existing SURVITUDEPLAN alias for that property. Separately confirm whether the business source should be ERVEN; do not rename the public property/CSV column during this fix. Test with different servitude and survey-record values.
P17 — JDBC row mapping loses null information and can dereference null timestamps¶
Evidence: ReservationOutcomeRowMapper:22, SgdataParcelsRowMapper.
getLong/getInt yield zero for SQL NULL unless wasNull is checked. The reservation mapper also calls toLocalDateTime() on issue/expiry timestamps without checking null. Whether affected columns can actually be null needs database confirmation. No repository access was found in the 43 row mappers themselves, so these are correctness/compatibility risks rather than direct N+1 generators.
Fix: use typed nullable getObject(..., Long.class) or wasNull, plus null-safe timestamp conversion, only where the contract expects null. Do not silently change established zero/default report values. Test null and non-null JDBC fixtures and compare serialized output.
P18 — Date predicates and month sorting need query-specific correction¶
Evidence: UserLeaveCalenderRepository:46, VwWorkflowProductivityRepository:128; similar monthly ordering in archive/examination dashboards.
Date-to-string-to-date predicates depend on formatting and can inhibit ordinary index access. Sorting by numeric MMYY puts January 2026 before December 2025 in an ascending cross-year series.
Fix: express date-only comparisons as equivalent bound ranges after confirming DATE/TIMESTAMP/timezone semantics; obtain Oracle plans before adding indexes. Sort monthly series by TRUNC(date,'MM') while retaining the existing display month and response aliases. Do not change inclusive end-date semantics casually. Test year boundaries, leap dates, midnight and end-of-day values.
P19 — Cart writes force a flush per child and map the same DTO twice¶
Evidence: CartService:132.
addToFinalCart maps twice, flushes the root, then saves and flushes every child before querying children again. This prevents effective batching and repeats mapping work.
Fix: map once and persist the aggregate in one service transaction, or explicitly save child batches after the parent ID is available. Preserve current association ownership, cart response content and invoice generation. Establish whether the intermediate flush is needed for constraints before removing it. saveAll alone does not guarantee JDBC batching. Test rollback after a child/invoice failure.
Package-wide follow-up controls¶
- Views: all five files are scalar entity mappings. Verify that each
@Iduniquely identifies a view row using live duplicate counts, especially role-expanded user views. Use read-only query transactions/projections; consider@Immutableonly after establishing that no consumer writes through the view. Missing immutability is not proof of an existing erroneous write. - Bulk updates/deletes: screen every
@Modifyingconsumer for a service transaction and for reading already-managed entities afterwards. Refresh/clear at an appropriate boundary only where needed; blanketclearAutomaticallycan detach pending work. Prefer grouped operations to per-row calls while preserving cascade/audit semantics. - Concurrency: no
@Versionor@Lockdeclarations were found in this persistence tree. Assess actual competing workflow/status writers and database-side safeguards before adding optimistic locking columns or changing write predicates. - Unbounded collections: several user searches, task queues, reports and exports return collections. First batch enrichments and process background workloads in chunks. Keep existing collection response contracts; adding a new page envelope, silently capping results or dropping fields requires a separate compatibility decision. Returning all rows still has output-size costs even after query optimization.
- Maintenance: retain the existing targeted entity graphs,
@BatchSizeannotations and lazy-aware mapping. Their presence is a useful baseline, not proof that every caller has a suitable fetch plan. - Scalar repositories/projections: dispatch/document/error/fee/list-management/system and many examination/archive/workflow reads do not have association-based N+1 merely because they use repositories or projections. Repeated calls in a consumer, broad entity reads, indexes and native-query execution plans must be assessed separately. Do not add fetch joins to scalar projection queries.
- Fetch batching:
hibernate.jdbc.batch_size=100batches compatible writes, not arbitrary read lookups. Association batching can help navigational reads but cannot replace P01/P04's explicit per-row repository calls. - Indexes: obtain current DDL, row counts and
DBMS_XPLANfor the selected slow query before proposing a concrete index. Candidate families are parent foreign keys and combined workflow/user/status predicates; index order and selectivity require live evidence. No migrations or data changes were made.
Current persistence compiler warnings¶
A forced offline compilation of cis-api and its main-source dependencies with -Xlint:deprecation,unchecked -Xmaxwarns 10000 passed after the fixes. The persistence warning inventory records nine distinct file/line/message diagnostics emitted within the persistence tree:
| Location | Distinct diagnostics | Fix approach |
|---|---|---|
DataViewerCustomImpl |
6 | Replace raw query/result types with explicit typed boundaries; replace deprecated Hibernate result transformation while preserving column aliases, value types and response maps (P09). |
SiteMapRepository / SiteRoleRepository |
3 | These still reference deprecated SiteRole. Trace active callers and its replacement before migration; retain compatibility while callers remain. Do not delete or suppress merely to obtain zero warnings. |
This is a compiler-emission inventory for those flags, not every IDE inspection or -Xlint:all category. Remaining MapStruct warnings are in mapper packages outside persistence; review generated IDs/backreferences separately from actual response-field omissions. The existing broader compiler-warning-audit.md describes an older snapshot and was not overwritten.
Contract-preserving implementation order¶
- Keep the compilation fixes and their three focused tests as the first reviewable slice.
- Add golden response fixtures for user lists, assistant lists, draft lists/details and scheme counts. Cover null versus empty, order, enum/date values, envelopes and pagination headers.
- Instrument representative Oracle-backed reads using the existing
JPA_GENERATE_STATISTICSswitch. Measure prepared statements, collection fetches, transferred rows and elapsed time with cold persistence contexts and production-like cache settings. Avoid logging credential bind values. - Fix scalar correctness separately: P06/P13/P16, with native-query/JDBC fixtures. Confirm intended result changes in P07/P08/P15/P18.
- Introduce the batched read assembler and pure MapStruct context for P01/P02/P03/P11. Assert mapping alone performs zero repository calls and total read counts grow by batches, not one lookup per result.
- Replace scheme/document entity counting with grouped aggregates (P04), then split detail fetch plans (P05/P10). Recheck JSON and row amplification after each change.
- Optimize background/calendar/cart workloads (P12/P19), then address numbering and data-viewer constraints with their database/feature contracts explicitly defined.
For query-count regressions, compare one item with twenty items, shared and distinct references, empty pages, missing optional data and multiple children. Account for legitimate count queries and batch boundaries rather than prescribing one universal SQL count. Oracle startup/integration tests remain necessary: compilation does not validate native SQL, repository initialization, schema mappings or production performance.
Framework references¶
- MapStruct 1.6.3 reference:
uses, mapping hooks, context, update/null semantics and constructor injection. - Hibernate ORM guide: fetch plans, association batching, JDBC batching and query/result transformation. Check the resolved Hibernate version before adopting version-specific APIs.
Coverage by persistence area¶
Counts include nested folders; historical Lodgement/lodgment spellings are grouped here. These are screening coverage and follow-up directions, not runtime pass statuses.
| Area | Domains | Repositories | Projections | Row mappers | Views | Follow-up |
|---|---|---|---|---|---|---|
| (root/shared) | 16 | 21 | 13 | 11 | 5 | User/role/province loading, assistant lookups, help attribution, view identity (P01/P02/P07/P10). |
| archive | 11 | 12 | 15 | 8 | 0 | Packet numbering, Plan Safe predicate, scalar DTO and named-native result mappings (P08/P13). |
| cart | 23 | 7 | 1 | 0 | 0 | Eager children, repeated mapping/flushing and fee enrichment (P10/P11/P19). |
| dashboard | 0 | 4 | 36 | 0 | 0 | Scalar aggregates/projections; month ordering and alias consistency (P15/P18). |
| dataviewer | 3 | 5 | 1 | 0 | 0 | Custom SQL, whole-object counts, raw result types and export materialization (P09). |
| dispatch | 1 | 1 | 0 | 0 | 0 | Scalar domain/repository screening; inspect caller result sizes before changing fetch behavior. |
| document | 1 | 1 | 0 | 0 | 0 | Scalar domain/repository screening; no association-fetch remedy inferred. |
| error | 2 | 1 | 0 | 0 | 0 | Scalar reference data screening; no association-fetch remedy inferred. |
| examination | 27 | 25 | 10 | 6 | 0 | Notes/caption enrichment, projection aliases and JDBC report columns (P11/P15/P16). |
| fee | 5 | 5 | 1 | 0 | 0 | Scalar pricing repositories; optimize repeated complete pricing keys in consumers (P11). |
| invoice | 1 | 1 | 0 | 0 | 0 | To-one loading and omitted unit-cost projection field (P10/P15). |
| listmanagement | 4 | 4 | 0 | 0 | 0 | Batch reference captions; preserve administrator-managed values (P01/P11). |
| lodgement | 29 | 31 | 26 | 6 | 0 | Draft/step graphs, scheme counts, user/province lookups and nullable outcome mapping (P03-P05/P17). |
| logo | 1 | 0 | 0 | 0 | 0 | Scalar model screening; no association-fetch remedy inferred. |
| maintenance | 9 | 9 | 3 | 5 | 0 | Targeted graphs/batching already exist; default-eager references and lazy-aware response parity (P10). |
| notification | 1 | 0 | 0 | 0 | 0 | Scalar model screening; bound background consumption rather than changing response format. |
| prepackage | 4 | 4 | 6 | 0 | 0 | MAX+1 boundary allocation; scalar subscription/query result-size review (P08). |
| province | 2 | 2 | 0 | 0 | 0 | Reference/address loading and repeated province lookup batching (P10/P11). |
| report | 6 | 3 | 42 | 0 | 0 | Per-province labels, per-action/day queries, scalar report projections (P11/P12). |
| reservation | 16 | 11 | 6 | 7 | 0 | Draft graphs, short-list enrichment, JDBC nullable outcomes and numbering scope (P03/P05/P08/P17). |
| sitemap | 3 | 0 | 0 | 0 | 0 | Eager role links and deprecated SiteRole references (P10; compiler inventory). |
| system | 2 | 2 | 0 | 0 | 0 | Scalar configuration/log screening; no association-fetch remedy inferred. |
| user | 12 | 11 | 0 | 0 | 0 | Leave count queries, role/metadata loading, global latest login and null/date semantics (P01/P06/P07/P18). |
| workflow | 14 | 10 | 8 | 0 | 0 | Scalar native projection counts/aliases, notes enrichment and productivity consumers (P11/P12/P15). |
CIS API reporting performance audit and architecture proposal¶
Date: 4 November 2026
Status: Source audit and proposed design
Audience: Backend engineers, database engineers and technical leads
Executive recommendation¶
Prioritize bounded CSV extraction and safe filter binding, followed by incremental productivity generation. Introduce durable background export jobs for large reports and consolidate compatible dashboard aggregates. Tune Oracle indexes and reporting views after collecting execution statistics. These changes target memory growth, repeated database work and competition with transactional API traffic.
The findings below describe source behavior, not measured production latency. No live database execution plans, deployed view definitions, row counts or load-test results were collected. Severity represents likely scaling impact. No runtime code or database changes are included in this proposal.
Scope and current flow¶
The audit covers ReportingResource, ReportingService, GenericReportFactory, representative archive and examination production exports, user summary exports, ReportUtils, productivity generation and general dashboard counters. It is not an exhaustive correctness certification of every report or the separate archive and examination dashboards.
flowchart TD
A[Client requests PDF or CSV] --> B[ReportingResource]
B --> C[ReportingService and report factory]
C --> D[Generator builds SQL and queries Oracle]
D --> E[All result rows loaded into a List]
E --> F{Format}
F -->|CSV| G[Write complete list to temporary file]
F -->|PDF| H[Build HTML then XHTML and PDF layout]
G --> I[Return file after generation completes]
H --> I
Findings and recommended remedies¶
F1 Complete result sets are retained in memory¶
Priority: High. ExaminationProductionReport.generateReportData and ArchiveProductionReport.generateReportData return a complete JDBC result List. CSV writers consume that list; PDF generators place the full collection in a Thymeleaf context. PDF additionally creates HTML, XHTML and renderer state. Memory use grows with matching rows and concurrent exports. Archive and examination production queries also sort by date, which can add database sort work.
Remedy: Process JDBC rows with a callback and write CSV incrementally to a buffered artifact file. Keep only a bounded fetch batch and output buffer in memory. Use proper CSV escaping, explicit UTF-8 and try-with-resources. Cap PDF rows or pages and offer detailed CSV for large datasets. Do not silently truncate an export. Keep deterministic ordering with a unique tie-breaker when chunking.
Acceptance: Compare 10 thousand and 100 thousand row exports under identical concurrency. CSV peak heap should remain within an agreed bounded budget rather than grow with the full dataset. Validate row counts, ordering, commas, quotes, newlines and Unicode. Fetch size alone does not remove the retained List.
F2 Productivity generation rebuilds historical actions¶
Priority: High. WorkflowRepository.getProductivityData selects all workflow actions. ProductivityReportGenerator.generateWorkflowProductivity runs in one transaction, deletes prior results per action and inserts daily results. Work grows with total action-days and retains a large persistence context. Existing Hibernate batching settings do not eliminate that algorithmic cost.
Remedy: Select changed actions plus open actions, using a stable checkpoint and keyset chunks. Bulk replace or merge derived rows within short transactions. Flush and clear between chunks when using JPA. Record successful checkpoints only after the corresponding writes commit. Add uniqueness at the agreed action and day grain after checking existing duplicates. Recalculate affected historical periods when calendars, leave or office hours change.
Acceptance: Reprocessing an identical chunk produces the same results without duplicates. Crash recovery neither skips actions nor exposes partially replaced results for an action. Track processed actions, generated days, elapsed time and failed chunks. Preserve source workflow data.
F3 Productivity loops repeat calendar database lookups¶
Priority: High. Each action-day can query national holidays, office holidays, user leave and office timings before saving a daily record. The loop is O(total action-days), with up to four reference reads per normal working day in the visible call path.
Remedy: Bulk-load relevant calendar dates, province timing intervals and leave intervals for each processing chunk. Resolve date membership in memory. Bound cache size and use run-scoped snapshots for reproducibility. Define business timezone, weekend behavior, partial-day treatment and retroactive calendar corrections before replacing the calculation.
Acceptance: Reference-query counts scale with chunks and required reference ranges rather than individual action-days. Cover same-day work, first and last partial days, after-hours periods, holidays, leave, open actions and missing office timings.
F4 Dynamic filter SQL contains request supplied structure and literals¶
Priority: High. ReportUtils.getQueryFromFilters concatenates dbCaption, dbOperation, prefixes and data supplied through ReportFiltersData. This creates SQL variations and an SQL injection risk. ReportingVm does not enforce a maximum date span, format enumeration or nonempty province list. The inspected dynamic production generators do not separately bind the top-level province and date fields.
Remedy: Accept stable filter identifiers and typed values. Resolve SQL columns, allowed operators and mandatory scope predicates from server-owned definitions. Bind values through NamedParameterJdbcTemplate. Validate report ID, format, date order, report-specific required filters, list sizes and authorized province scope. Never trust a supplied column or function name. Treat absent filters explicitly rather than emitting an empty WHERE clause.
Acceptance: Reject unknown filters and operators; preserve valid filter semantics. Verify that province restrictions cannot be omitted or widened through dynamic filters. Compare SQL text stability for requests differing only in values. Test malicious strings as bound data.
F5 Dashboard counters execute separate sequential queries¶
Priority: Medium to high. DashBoardService builds several counter responses from four repository calls, including registration, user summary, process, reservation and lodgement counters. Repeated requests can repeat scans over overlapping source populations. Actual scan cost depends on deployed views and Oracle plans.
Remedy: Consolidate compatible counters with conditional aggregation over a common filtered dataset. Aggregate each metric at its correct entity grain before joining to avoid inflated counts or money totals. Retain separate queries when populations differ. Add short-lived caching only where freshness requirements permit; include authorization scope, normalized filters, timezone and data version in the key.
Acceptance: Compare every old and new metric on fixtures with multiple roles, actions, invoices and payments. Record database calls and logical reads per dashboard response. Group months by a chronological month key; format labels at the presentation boundary.
F6 Date expressions and JDBC settings need targeted tuning¶
Priority: Medium. UserSummaryReport filters with trunc(USERCREATIONDATE) between date parameters. This can prevent an ordinary timestamp index from serving a range efficiently unless Oracle can transform the predicate or an appropriate function-based index exists. JDBC report queries do not inherit Hibernate fetch-size settings.
Remedy: Prefer timestamp >= :fromInclusive AND timestamp < :toExclusive with the next day as the exclusive end boundary, using the agreed timezone. Set report-specific JDBC fetch sizes and statement timeouts. Evaluate base-table composite indexes against real selectivity and execution plans. Do not add an index to every filter column or assume a view name implies precomputed data.
Acceptance: Inspect executed plans for narrow and broad date ranges and one or many provinces. Compare actual rows, logical reads, elapsed time and sort spills. Verify inclusion of the full final day. Choose indexes only after inspecting deployed view definitions, statistics and existing indexes.
F7 Synchronous generation and unmanaged artifacts reduce isolation¶
Priority: Medium. ReportingResource waits for generation before returning a file. ReportUtils and individual generators create temporary files; no successful-download cleanup is visible in the inspected report path. Report execution shares the application's database resources. The checked application configuration defaults the Hikari maximum to 15, but runtime overrides were not verified.
Remedy: Add durable asynchronous jobs for large exports with bounded database and rendering concurrency. Store completed files in managed artifact storage with retention expiry. Publish an artifact only after successful close and validation; remove partial files on failure. Use an explicit reporting connection budget, optionally a separate small pool or worker deployment after measurement. Increasing pool size alone can increase Oracle contention.
Acceptance: A burst of exports respects configured limits and does not exhaust transactional connection capacity. Retries, cancellations, process restarts and retention sweeps leave consistent job and artifact states. Test client disconnects and failed downloads.
Proposed export architecture¶
Retain the strategy registry around GenericReport, while separating query extraction, rendering and job orchestration. A ReportDefinitionRegistry owns allowed filters and report capabilities. A ReportQueryAdapter produces typed, authorized, bound queries. CsvArtifactWriter streams rows; PdfArtifactRenderer renders bounded datasets. ReportJobService owns durable lifecycle and ArtifactStore owns publication and expiry.
flowchart TD
A[Client] --> B[API validates report and authorizes scope]
B --> C{Small bounded report}
C -->|Yes| D[Synchronous compatibility route]
C -->|No| E[Persist durable job and return 202 with job ID]
E --> F[Worker claims job with lease]
F --> G[Query adapter with bound filters]
D --> G
G --> H[Oracle within reporting connection budget]
H --> I{Output format}
I -->|CSV| J[Row callback and buffered artifact writer]
I -->|PDF| K[Bounded dataset and limited PDF renderer]
J --> L[Validate and publish artifact]
K --> L
L --> M[Mark job succeeded or return synchronous file]
A --> N[Authorized status and download endpoint]
N --> M
L --> O[Retention service expires artifact]
Proposed API additions are POST /report/jobs, GET /report/jobs/{id}, GET /report/jobs/{id}/download and DELETE /report/jobs/{id} for cancellation. Keep existing POST /report behavior for supported bounded requests. Add the asynchronous route with a corresponding UI status and download flow; do not silently change a binary-response contract to JSON.
Persist job ID, requester, authorized scope, canonical filters, format, definition version, source cutoff, status, progress, attempts, lease expiry, timestamps, artifact reference and expiry. Use QUEUED, RUNNING, SUCCEEDED, FAILED, CANCELLED and EXPIRED states. Workers claim jobs atomically, renew leases and use bounded retries. Write attempt-specific staging artifacts so a stale worker cannot overwrite a newer result. A durable database job table is sufficient initially; a message broker is optional, with a transactional outbox if introduced.
Reauthorize download access. Never use an unprotected artifact URL as authorization. Recheck permissions before extraction; define how revoked access affects completed jobs. Deduplication and artifact reuse must include requester or equivalent authorization scope, report definition version, canonical filters, format and source version. Check cancellation between extraction chunks and rendering stages.
For a consistent export, prefer one cursor or an agreed Oracle snapshot mechanism. Multi-query keyset extraction needs an explicit source snapshot or cutoff policy; a timestamp cutoff alone does not freeze updates to existing rows. Long snapshots can consume undo and must be tested with the database team. Streaming to a file decouples Oracle connection time from a slow client download.
Initial implementation¶
The existing POST /report route resolves typed report strategies through ReportDefinitionRegistry and uses GenericReportFactory for legacy strategies. To enroll a report, register a Spring bean implementing ScopedReport with its own immutable ReportExportFilters type. The strategy adapts and validates the request, then receives the same typed filters after authorization. Reports that support jobs implement BackgroundCsvReport and own the versioned filter decoder. Each query adapter binds its report's typed values to server-owned SQL.
The pilot uses the shared immutable ReportFilters value object, accepting either the original top-level fields or a filters object with fromDate, toDate, provinces and userTypes. A specialized report can compose this standard scope with additional immutable criteria without changing the framework contract. Persisted version 1 filter JSON retains this shape.
User Summary requires a report grant from an assigned role in each requested province. An assignment with no province grants no scope through this path. The pilot accepts up to 366 inclusive dates and up to 100 provinces and user types per request. CSV uses a single cursor and a buffered UTF-8 file. PDF rejects results above 2,000 rows and directs users to CSV. The report endpoint removes temporary file artifacts when the request completes. These limits are initial implementation choices pending representative load tests.
Shared export contracts and the strategy registry live in reporting.core, with shared filters in core.filters and artifact writers in core.csv and core.pdf. Each migrated report owns its strategy and query adapter under reporting.reports.<domain>. Additive criteria such as Archive Production's document types live under that domain's filters subpackage. User Summary reuses the shared filter.
User Summary PDF rendering¶
The pilot PDF adapter renders the trusted Thymeleaf template, normalizes it to XHTML and uses Flying Saucer to lay out the document before allocating a temporary output file. It accepts the bundled report logo, flag and renderer stylesheet. Failed writes remove the partial artifact and return a sanitized HTTP 500. Completed downloads use the MVC cleanup interceptor.
The query reads at most 2,001 rows to detect the 2,000-row PDF limit. Province labels come from a scalar query. The cis.reporting.pdf.stage timer records extraction, template, layout and write separately. Use representative staging timings and heap measurements to decide whether PDF needs separate permits from synchronous CSV.
Background CSV pilot¶
Set CIS_REPORTING_JOBS_ENABLED=true in the CIS API module environment file on a deployment with migrations V5 and V6 applied, scheduling enabled and the existing Redis scheduler lock available. The feature defaults to off. Polling defaults to 10 seconds and is configurable with CIS_REPORTING_JOBS_POLL_DELAY. The other reporting job settings are listed in the CIS API environment examples for dev, UAT and production. Extraction and retention run on a dedicated scheduler. The worker processes one job per Redis scheduler lock and uses the shared Oracle pool. During extraction it can use a second connection briefly to check the claim every 5,000 rows.
POST /api/v1/report/jobsaccepts the existing User Summary CSV request and responds with 202 and a job location.GET /api/v1/report/jobs/{id}returns the owner's state and attempt count.GET /api/v1/report/jobs/{id}/downloadreturns CSV after rechecking the requester's current grants.DELETE /api/v1/report/jobs/{id}cancels an owned queued or running job.
The feature lives in the CIS API reporting package, with separate export, job, persistence and HTTP components. Spring Data JPA stores the requester, versioned filters and lifecycle metadata. JDBC streams the Oracle extraction cursor and transfers artifact BLOBs without loading them into entity state. A token-guarded update publishes the BLOB and success state together. The worker uses a ten-minute lease and retries up to three attempts. Each attempt reads one Oracle cursor using the data visible at execution time. A cancelled or superseded attempt cannot publish. Artifacts are capped at 64 MiB during generation, expire after one day and are cleared by the worker. Retention runs independently of extraction. Set app.reporting.jobs.maintenance-enabled=true to keep retention running while submission and extraction are paused. Downloads stage the BLOB locally before releasing the database connection and streaming the file.
Legacy dynamic filter SQL, additional report enrollment and frontend polling remain outside the pilot. Validate the Oracle migration, runtime role grants, restart recovery and representative concurrency before enabling the feature.
Full Platform Enrollment & Architectural Uniformity¶
All 35 reports across all CIS modules are now fully enrolled into the modern reporting framework: - Reservation (6 reports): Business Rule, Notification, Production, Status, Transfer, User. - Examination (6 reports): Business Rule, Divisional, Document Capture Per User Per Day, Notification, Production, User Production. - Lodgement (5 reports): Production, Monthly Statistics, User, Notification, Business Rule. - Workflow (5 reports): Production, User Production, Notification, Business Rule, Request Statistical. - User Management (6 reports): User Summary (relocated to user management), User Login Summary, User Hourly Login Distribution, User Registration Quarterly, User Update Quarterly, User Update History. - Archive (8 reports): Archive Production, Archive Business Rule, Archive Monthly Statistics, Archive Notification, Archive User, PSDT Details, Scanning Monthly Statistics, Scanning Production. - Maintenance (5 reports): Monthly Statistics, Notification, Overridden Business Rule, Production, User.
Architectural Packaging Standards¶
- Report Strategies:
com.dw.ngms.cis.reporting.reports.<domain>.<ReportName>Report - Query Adapters:
com.dw.ngms.cis.reporting.reports.<domain>.adapter.<ReportName>QueryAdapter(cleanly separated from the strategy package to eliminate parent package clutter). - Domain Filters:
com.dw.ngms.cis.reporting.reports.<domain>.filters.*(or the sharedReportFilterscontract). - Code Hygiene & Author Headers: Every strategy, query adapter, filter, and test class contains the required author header:
- Security & Performance: Strict bounded PDF generation (2,000 row ceiling), CSV artifact ceiling (64 MiB), semaphore concurrency caps (2 concurrent synchronous renders per report), formula injection escaping, parameter-bound sargable date queries (
>= :fromDate AND < :toExclusive), and zero legacy dynamic string interpolation. - Legacy Code Cleanup: All 35 legacy report implementations across
com.dw.ngms.cis.service.reporthave been removed.
Pilot operations¶
- Default admission permits 32 outstanding jobs across replicas, including retained successful artifacts, three active jobs per requester and six submissions per requester per rolling minute. Change these using
max-outstanding,max-active-per-requesterandmax-submissions-per-minuteunderapp.reporting.jobs. Admission uses a short Oracle lock and returns HTTP 429 withRetry-Afterwhen saturated. - The default artifact size ceiling is 64 MiB. The outstanding limit bounds committed artifacts to at most 2 GiB at default settings, excluding Oracle LOB allocation overhead. Each API instance allows four staged background downloads by default (
max-downloads) and two synchronous User Summary renders. Use an instance-local temporary volume with bounded capacity and platform cleanup after process termination. Background download responses are markedCache-Control: no-store. - Maintenance clears expired artifacts and deletes up to 500 old terminal rows each pass. It runs once per minute by default and keeps 30 days of terminal metadata (
maintenance-delay,history-days). - Report grant changes require an administrator authority. CSV rows are quoted, and formula-like text fields receive a leading apostrophe for spreadsheet viewing. Resaving in a spreadsheet can remove escaping, and downstream CSV consumers should account for the text prefix. OWASP CSV injection guidance
- Monitor
cis.reporting.jobs.queued,cis.reporting.jobs.oldest.queued.seconds,cis.reporting.jobs.eventsandcis.reporting.jobs.attemptthrough the existing Micrometer registry. Configure alerts using the target environment's latency and capacity objectives. Include Oracle tablespace and API temporary-volume usage in rollout checks. - The API returns a Location on submission. Poll the job resource until it reaches a terminal state, then download a successful artifact. Stop polling when the job is cancelled, failed or expired. On 429, honor Retry-After. Frontend integration is a separate deployment.
Generate a combined JaCoCo report for the framework with ./gradlew.bat :cis-api:jacocoReportingReport on a Docker-enabled host. The report combines unit and Oracle integration execution data for com.dw.ngms.cis.reporting.
For debugging, search application logs by jobId for queued, claimed, published and cancelled jobs, or by exportId for synchronous exports and PDF stage failures. Enable DEBUG for com.dw.ngms.cis.reporting and com.dw.ngms.cis.service.report.ReportingService to see PDF stage timings, rejected requests and download decisions. The reporting diagnostics use identifiers, state, elapsed time and exception types without emitting filter values or artifact contents.
Production readiness gates¶
- Migrate each exposed archive and examination dynamic-filter report to a server-owned definition and parameter binding. Verify report grants and mandatory province predicates with real report configuration and representative authorized fixtures. Treat the existing SQL concatenation paths as a security release blocker for a reporting-wide rollout.
- Run the Oracle job integration tests with migrations V5 and V6 and exercise submission through download with deployed authentication and Redis. Cover concurrent workers, stale leases, restart recovery, cancellation, revoked grants, expiry, failed uploads and disconnected downloads.
- Measure narrow and broad exports alongside transactional traffic. Establish limits for queue depth, submission rate, database connections, artifact storage and retention based on those results. Add metrics and alerts for oldest queued job, failures, retries, expiry and active connections.
- Connect the frontend polling, cancellation and download flow. Document operator recovery and retention behavior, including cleanup while job processing is paused. Enable the feature for a controlled User Summary pilot before expanding report enrollment.
The export framework currently enrolls User Summary, Archive Production, the full suite of Examination reports (Production, Notification, User Production, Divisional, Business Rule, and Document Capture Per User Per Day), and the full suite of Reservation reports (Production, Status, Transfer, Business Rule, Manager Notification, and User) with typed parameter-bound SQL queries and background CSV support. The productivity and dashboard phases below are separate implementation tracks.
Incremental productivity architecture¶
flowchart TD
A[Scheduled run with lease] --> B[Read checkpoint and capture run cutoff]
B --> C[Select changed and open actions in keyset chunks]
C --> D[Bulk load calendars office hours and leave]
D --> E[Calculate daily productivity in memory]
E --> F[Replace derived rows and commit checkpoint atomically]
F --> G{More chunks}
G -->|Yes| C
G -->|No| H[Mark run complete and publish metrics]
I[Calendar or leave correction] --> J[Queue affected actions and dates]
J --> C
Use a stable change sequence or a timestamp plus unique ID, with overlap and deduplication where timestamp precision requires it. Revisit open actions even without a new source change because elapsed work changes over time. Capture one business-time cutoff per run. Commit derived rows and checkpoint together; make replacement idempotent. Keep an explicit backfill command for historical rebuilds.
The existing scheduler lock has a 14 minute maximum. Confirm actual runtime and scheduler topology before choosing lease limits. Support renewal or a bounded execution contract and prevent concurrent writers for the same action. A scheduler lock alone does not coordinate separate workflow-triggered recalculation paths.
Dashboard read architecture¶
flowchart TD
A[Authorized dashboard request] --> B[Normalize filters and scope]
B --> C{Scoped cache hit}
C -->|Yes| D[Return values with data freshness time]
C -->|No| E[Consolidated aggregate query]
E --> F[Oracle reporting views or daily summary tables]
F --> G[Store bounded cache entry]
G --> D
H[Incremental summary refresh] --> F
H --> I[Advance data version or invalidate affected keys]
Start with query consolidation and measurement. Add daily summaries or materialized views only for expensive repeated aggregates with an agreed freshness contract. Choose dimensions and measures from actual dashboard requirements. Counts of distinct users cannot generally be obtained by summing daily distinct counts; averages need numerators and denominators. Detail exports should continue to use an appropriate detail source.
Correctness prerequisites¶
ReportingResource assigns PDF content type and then unconditionally overwrites it with text/csv. Correct response headers before validating downloaded files. MaintenanceProductionReport currently selects blank or null columns from VW_WH_BUSINESS_RULES with ROWNUM < 10; its parameters are not used. Treat this as incomplete reporting behavior, not a successful fast report.
ReportingService.getReport dispatches directly to a generator without a visible report-role permission check in that method. Verify the full security path and enforce report and province scope on execution, separately from metadata listing. This is a gap in the inspected execution path, not proof that every deployment exposes reports anonymously.
ProductivityReportGeneratorTest prints a duration, has no assertions and comments out the generator call. Add representative expected-result fixtures before changing calculations. Review the current partial-day loop for omitted final-day work, overcounted first days and negative after-hours durations.
Delivery phases and validation¶
Phase 1 establishes baseline telemetry and correct export headers, validation, safe filters and authorization checks. Add CSV extraction that writes incrementally, managed artifact cleanup and explicit limits. Preserve existing response envelopes and valid filter behavior.
Phase 2 adds durable jobs and bounded workers. Pilot a single high-volume CSV report before extending all generators. Add job status and download UI behavior. Keep the synchronous route behind a configured threshold or capability rule.
Phase 3 replaces full productivity rebuilds with incremental chunks, preloaded references and restart-safe writes. Compare derived totals and per-day records against reviewed fixtures and representative existing results before switching consumers. Preserve raw workflow records.
Phase 4 consolidates dashboard queries and introduces scoped caching. Add reporting summaries only if measurements justify them. New schema changes require new migrations; preserve applied scripts and follow repository ownership and deployment conventions.
Validate narrow and broad date ranges, one and many provinces, empty results, high row counts, repeated requests and concurrent exports alongside normal API traffic. Record p50 and p95 latency, SQL elapsed time, logical reads, returned rows, peak heap, GC pause time, active and pending connections, queue depth, oldest job age, renderer concurrency, temporary storage and failure rate. Set numeric service targets from measured workload and business freshness needs rather than promising an unverified speedup.
Use feature flags per report for safe rollout. Compare CSV content and aggregate totals before promotion. Roll back routing to the previous generator if needed while retaining job history and published artifacts under the retention policy. Database changes should be additive so rollback does not require deleting source data.
Evidence and technical references¶
Repository locations below are relative to cis-api/src/main/java/com/dw/ngms/cis unless stated otherwise. Line references identify the reviewed source snapshot and may move as development continues.
- F1: service/report/Examination/ExaminationProductionReport.java lines 47, 78 and 106; service/report/Archive/ArchiveProductionReport.java lines 78 and 159.
- F2 and F3: service/report/ProductivityReportGenerator.java lines 55 through 149; persistence/repository/workflow/WorkflowRepository.java lines 561 through 585; service/HolidayCalendarService.java line 62; service/OfficeTimingsService.java; service/user/UserLeaveCalendarService.java.
- F4: utilities/ReportUtils.java lines 78 through 130; persistence/domains/report/ReportFiltersData.java; web/vm/report/ReportingVm.java.
- F5: service/DashBoardService.java lines 53, 77, 178, 401 and 531; persistence/repository/dashboard repositories.
- F6: service/report/UserSummaryReport.java lines 92 through 118; cis-api/src/main/resources/application.yaml lines 65 through 107.
- F7: web/rest/ReportingResource.java lines 61 through 74; utilities/ReportUtils.java lines 38 through 47; service/report/ReportingService.java lines 87 through 90.
- Correctness: service/report/maintenance/MaintenanceProductionReport.java lines 95 through 119; service/report/ReportingService.java lines 81 through 85; cis-api/src/test/java/com/dw/ngms/cis/service/report/ProductivityReportGeneratorTest.java.
- Spring JDBC statement settings and row callbacks: https://docs.spring.io/spring-framework/docs/6.0.x/javadoc-api/org/springframework/jdbc/core/JdbcTemplate.html
- Oracle executed cursor plans and required privileges: https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/DBMS_XPLAN.html
Capture representative executed cursor plans with DBMS_XPLAN.DISPLAY_CURSOR and ALLSTATS LAST after collecting execution statistics. Inspect deployed view definitions, indexes and cardinality estimates before choosing physical database changes. The framework reference documents established JDBC capabilities; implementation should use the repository's current dependency versions.
Reporting validation and performance¶
Validated locally on 7 November 2026 using Docker Desktop 29.8.2 and disposable Oracle Free 23 containers. No production database was accessed. The benchmark test JVM has a 1 GiB maximum heap; Docker reported 9,945 MB available. JaCoCo is disabled for the performance task.
Repeatable commands¶
Run from the repository root with Docker available:
.\gradlew.bat :cis-api:test --tests 'com.dw.ngms.cis.reporting.*' --tests 'com.dw.ngms.cis.service.report.ReportingServiceTest'
.\gradlew.bat :cis-api:integrationTest --tests 'com.dw.ngms.cis.reporting.*'
.\gradlew.bat :cis-api:jacocoReportingReport -x :cis-api:test -x :cis-api:integrationTest
.\gradlew.bat :cis-api:reportingPerformanceTest --rerun-tasks
The coverage command consumes the preceding executions. Performance tests are opt-in and excluded from the normal integration task. Docker is mandatory for the performance task. --rerun-tasks prevents Gradle from returning cached/up-to-date measurements.
Functional verification¶
- 201 reporting and ReportingService unit tests passed.
- 10 Oracle-backed reporting integration tests passed, with no skipped tests: job persistence (3), HTTP contracts (5), Maintenance query adapters (2).
- Verified job admission under concurrent transactions, claim fencing, expired-lease recovery, cancellation, artifact ownership/expiry, submit/poll/download HTTP flow, grant revocation, legacy-form compatibility, and synchronous PDF output.
- Combined reporting coverage: 2,354 / 3,295 lines (71.4%); 861 / 1,556 branches (55.3%). This is not complete coverage.
The Maintenance query checks exercise the real Oracle syntax with an empty authorized scope. They do not establish business aggregation correctness on representative production records.
Benchmark method¶
ReportingPerformanceTest runs one warmup followed by three measured samples for each scenario. Durations exclude container startup, schema initialization, connection acquisition, output validation, and artifact deletion. Each artifact is deleted after verification. There are no timing assertions tied to workstation speed.
- Oracle to background CSV: generate 100,000 numbered technical rows using Oracle
CONNECT BY, fetch 250 rows per round trip, map to the 12-column User Summary projection, and write through the actual asynchronous CSV writer. Verify the header and row count. This includes row creation, JDBC fetching, annotation mapping, escaping, and disk output. - User Summary PDF: render 2,000 technical rows through the real User Summary Thymeleaf template, approved image loader, Flying Saucer renderer, and file writer. Parse the resulting PDF and verify it has multiple pages. This includes template processing, layout, and PDF writing.
Final measured samples (both benchmark tests passed; none skipped):
| Scenario | Rows | Sample 1 | Sample 2 | Sample 3 | Artifact bytes |
|---|---|---|---|---|---|
| Oracle to CSV | 100,000 | 1,202.29 ms | 941.00 ms | 1,013.62 ms | 16,277,920 |
| User Summary PDF | 2,000 | 3,014.11 ms | 1,181.75 ms | 1,135.29 ms | 1,382,835 |
The CSV median was about 98,656 rows/second. PDF layout was the largest measured rendering stage. Three samples provide a local baseline, not a statistically reliable tail-latency estimate.
Production performance checks still required¶
These synthetic single-export measurements do not exercise actual report SQL plans, production row widths/distribution, worker queue delay, BLOB publication/download throughput, peak heap, multiple instances, or concurrent maximum-size exports. Before capacity sign-off, measure those paths on a representative anonymized staging dataset with production indexes and resource limits. Capture query plans, p50/p95/p99 end-to-end latency, peak heap/GC, database pool utilization, temporary disk use, and queue age at the intended concurrency. Retain the current export and PDF bounds until that evidence supports changing them.
Centralized Semantic Versioning System Walkthrough¶
Summary¶
Implemented a unified, Git-tag driven Semantic Versioning (Major.Minor.Patch) system across all submodules in the cis-api-uam multi-module project. All submodules (cis-api, cis-auth, cis-bff, cis-workflow, cis-search, cis-emailer) now share the exact same version derived dynamically from Git release tags, with automatic snapshot incrementation, CI/CD override support, and complete offline capability.
What Changed¶
1. Versioning Engine (gradle/versioning.gradle)¶
Created a native Groovy resolution script plugin (zero third-party Gradle plugin dependencies):
- Resolution Hierarchy:
1. -PversionOverride or -Pversion (CLI / build flag override)
2. CIS_APP_VERSION or APP_VERSION (Environment variable override)
3. Git Describe: git describe --tags --always --long
- Exact tag match (v2.0.0-0-g...): Resolves to release version 2.0.0.
- Commits ahead of tag (v2.0.0-5-g...): Automatically increments patch and appends -SNAPSHOT (e.g. 2.0.1-SNAPSHOT).
4. Fallback from gradle.properties: defaultVersion=2.0.0-SNAPSHOT
- Helper Tasks:
- :printVersion: Clean output for scripts, CI pipelines, and Docker image tags (./gradlew printVersion -q).
- :showVersionDetails: Displays complete diagnostic metadata (resolved version, git describe, commit hash, active branch, group, and submodules).
2. Multi-Module Project Configuration (build.gradle)¶
- Applied
gradle/versioning.gradleat root level. - Replaced hardcoded
version = '0.0.1-SNAPSHOT'with: - Configured all
Jartasks across submodules to inject standard manifest attributes: Implementation-TitleImplementation-VersionBuilt-ByBuild-Timestamp
3. Baseline Tag¶
Created the major version baseline annotated tag:
- Git Tag: v2.0.0
- Commit: 92b8162cd (feat(build): implement centralized Git-tag based Semantic Versioning across all submodules)
Verification Results¶
1. Version Resolution¶
Output:==========================================================
CIS-API-UAM Centralized Version Details
==========================================================
Resolved Version : 2.0.0
Git Describe : v2.0.0-0-g92b8162cd
Git Commit Hash : 92b8162cd
Git Branch : feature/cis-auth-bff
Group : com.dw.ngms
Submodules : cis-api, cis-auth, cis-bff, cis-emailer, cis-search, cis-workflow
==========================================================
2. All Submodules Share Identical Version¶
./gradlew -q --offline :cis-api:properties :cis-workflow:properties :cis-auth:properties :cis-bff:properties :cis-search:properties :cis-emailer:properties | Select-String "version:"
cis-api: version: 2.0.0
- cis-workflow: version: 2.0.0
- cis-auth: version: 2.0.0
- cis-bff: version: 2.0.0
- cis-search: version: 2.0.0
- cis-emailer: version: 2.0.0
3. Property Override¶
4. Jar Artifact Generation & Manifest¶
Built :cis-emailer:jar producing cis-emailer-2.0.0.jar with manifest: