Backend Architecture Overview

Backend Architecture Overview

The nr-forest-client-backend is a reactive, cloud-native REST service engineered with Spring Boot 4 and Java 17, compiled into a native binary via GraalVM Native Image. It provides the core API endpoints that power the frontend single-page application.

---

Technical Stack & Features

Component	Technology	Version	Purpose
Framework	Spring Boot	4.1.x	Reactive web application framework
Runtime	Java / OpenJDK	17 LTS	Core language runtime
Reactive Web	Spring WebFlux	4.1.x	Non-blocking, asynchronous reactive request handling
HTTP Client	Spring WebClient	4.1.x	Reactive client for external API communication
Database Driver	R2DBC PostgreSQL	Modern	Reactive non-blocking database access
Native Compilation	GraalVM Native Image	21+	Sub-second startup time and reduced memory usage
Security & Auth	Spring Security + Nimbus JOSE	6.5.x / 10.x	Bearer JWT decoding, validation, and role extraction
JSON Stack	Jackson 3	3.x	Reactive JSON serialization and deserialization
Tracing & Metrics	Micrometer + OpenTelemetry	1.17.x / 1.64.x	Distributed trace propagation and observability
Testing	JUnit 5/6, Mockito, Testcontainers	Latest	Unit, reactive StepVerifier, and containerized tests

---

Key Architectural Patterns

1. Reactive End-to-End Pipeline

Unlike traditional servlet containers (Tomcat), Spring WebFlux utilizes Project Reactor's Mono and Flux publishers built on Netty. From HTTP ingress to R2DBC database queries, threads are non-blocking, enabling high concurrency with low memory footprint.

2. GraalVM Native Image

The backend is configured with GraalVM Native Build Tools:

• Ahead-of-Time (AOT) compilation eliminates JVM bytecode interpretation overhead.
• Instantaneous container startup (typically under 100ms on OpenShift).
• Predictable memory footprint (~50-80MB RSS under load).

3. Security & Token Verification

• Inbound HTTP requests require an Authorization: Bearer <JWT> header containing an identity token issued by FAM (AWS Cognito).
• The SecurityConfiguration validates token signature, issuer, and expiry using Nimbus JOSE.
• User roles (CLIENT_VIEWER, CLIENT_EDITOR, CLIENT_ADMIN, CLIENT_SUSPEND) and provider claims (idir, bceidbusiness, bcsc) are parsed and mapped to Spring GrantedAuthority objects for method and route security.

4. Resilient External Integrations

All outbound communications to external services utilize configured WebClient instances with timeout and retry policies:

• BC Registry: Queries corporate registry status, incorporation number, and company name matching.
• Canada Post AddressComplete: Resolves street addresses, postal codes, and provincial jurisdictions.
• CHES (Common Hosted Email Service): Asynchronously dispatches transaction notification emails.
• Legacy Connector: Communicates with the nr-forest-client-legacy service to query historic Oracle records.

---

Observability & Tracing

• Distributed Tracing: OpenTelemetry traces and spans propagate through incoming headers (traceparent, X-B3-TraceId).
• Health Checks & Metrics: Spring Boot Actuator endpoints (/actuator/health, /actuator/metrics) expose readiness and liveness probes to OpenShift.