Backend Architecture Overview

Backend Architecture Overview - Waste Plus Backend Applications

Purpose

This document describes the common architecture used across the Waste Plus backend applications and clarifies where each application has distinct responsibilities.

The platform currently runs two backend services:

• nr-waste-plus-backend (Spring Boot 4, Java 21, PostgreSQL)
• nr-waste-plus-legacy (Spring Boot 3, Java 17, Oracle)

Both services are part of the same domain and share conventions, package organization, security model, and several DTO contracts.

Application Landscape

Application	Primary Role	Runtime and Data
nr-waste-plus-backend	Main BFF for frontend access; orchestrates modern APIs and user preferences	Spring Boot 4, Java 21, PostgreSQL
nr-waste-plus-legacy	Legacy search and code-table API over Oracle data model	Spring Boot 3, Java 17, Oracle

Common Architecture Foundations

Layered design

Both applications follow the same layered approach:

• Controller layer: REST endpoints under /api/**
• Service layer: business logic and orchestration
• Repository/provider layer: persistence and external integrations
• DTO layer: records and enums shared by API contracts

This keeps HTTP concerns, domain logic, and data access concerns separate.

Package and naming conventions

Both services use the same root namespace and naming style:

• Root package starts at ca.bc.gov.nrs.hrs
• Class naming is role-based (for example: *Controller, *Service, *Repository, *Configuration)
• API DTO naming is consistent across apps, enabling shared semantics between frontend and backend services

Spring architecture patterns

Shared Spring patterns include:

• @SpringBootApplication entrypoints
• Constructor-based dependency injection
• @ConfigurationProperties for typed configuration domains
• Security customizers assembled into a SecurityFilterChain
• ProblemDetails enabled for RFC 7807 style error responses
• AOP-based observability with @Observed, @Timed, and @NewSpan

Security model

Both backends use a common security strategy:

• OAuth2 Resource Server with JWT validation against AWS Cognito JWKs
• Authorities sourced from cognito:groups
• Route-level authorization in security customizers
• Stateless request handling with no server-side session state

Observability model

Both services expose operational telemetry through:

• Micrometer metrics (Prometheus-compatible)
• Distributed tracing with B3 propagation
• Structured logging in container profile
• Common application tags (for example app, version, zone)

Testing model

Both applications follow similar testing principles:

• JUnit 5 for unit and integration tests
• Testcontainers for realistic integration environments
• Security test helpers for JWT-based request simulation
• JaCoCo minimum line coverage gate at build time

Build and deployment model

Both applications align on deployment style:

• Maven-based builds with profile-driven pipelines
• GraalVM native image support
• Distroless runtime containers
• OpenShift deployment using ConfigMaps, Secrets, Services, and Routes

Shared Request Lifecycle

The request flow is intentionally similar across both services.

sequenceDiagram
    participant FE as Frontend or API Consumer
    participant SEC as Security Filter Chain
    participant CTL as Controller
    participant SVC as Service
    participant DATA as Repository or Provider
    participant EXT as DB or External API

    FE->>SEC: HTTP request with JWT
    SEC->>SEC: Validate token and resolve authorities
    SEC->>CTL: Authorized request
    CTL->>SVC: Delegate business operation
    SVC->>DATA: Execute domain query or integration call
    DATA->>EXT: Access DB or upstream API
    EXT-->>DATA: Return data
    DATA-->>SVC: Return mapped result
    SVC-->>CTL: Return DTO or page
    CTL-->>FE: JSON response or ProblemDetails error

Loading

Shared Structural Diagram

graph TB
    C[Controllers] --> S[Services]
    S --> R[Repositories]
    S --> P[Providers]
    R --> D[(Database)]
    P --> X[(External APIs)]

Loading

Intentional Differences

Runtime and platform versions

• nr-waste-plus-backend runs on Spring Boot 4 and Java 21
• nr-waste-plus-legacy remains on Spring Boot 3 and Java 17 due to Oracle-related constraints tracked in issue #341

Data and integration boundaries

• nr-waste-plus-backend owns user preference persistence in PostgreSQL and acts as the frontend-facing BFF
• nr-waste-plus-legacy is centered on Oracle-backed reporting and code-table retrieval

Integration style

• nr-waste-plus-backend includes external provider integration patterns (Forest Client API + legacy forwarding)
• nr-waste-plus-legacy primarily exposes Oracle-backed search capabilities directly

Architectural Contract Across Backends

Across both applications, teams should preserve:

• Shared API vocabulary and DTO semantics
• Consistent endpoint naming and package structure
• Uniform authentication and authorization behavior
• Common observability and error-handling practices
• Equivalent testing rigor for controller, security, and integration paths

This contract allows the platform to evolve each backend at different speeds while preserving a coherent behavior to frontend and downstream consumers.

Evolution Direction

Current architecture supports a staged modernization model:

• Keep legacy stable for Oracle-backed capabilities
• Continue advancing the main backend on modern Spring runtime and integration patterns
• Converge shared concerns (security, DTOs, tracing, testing conventions) to avoid behavioral drift

When Oracle and dependency constraints are fully resolved, this model supports incremental consolidation with minimal impact on API consumers.

Runtime and Configuration References

To avoid duplication, profile activation, environment variables, local YAML samples, and IDE setup instructions are maintained in:

• Profiles and Environment Separation

---

Architecture Documentation Map

Document	Purpose
Backend Architecture Overview (this page)	Shared architecture narrative, diagrams, contract, and governance
Backend Structure	Code structure tree, naming conventions, architectural rules, and review checklist
Profiles and Environment Separation	Runtime and build profiles, environment variables, local configuration examples
Feature Flags	Cross-cutting toggle strategy, release controls, and operational governance

Optional changelog target:

• changes/Backend Architecture Changelog.md — create when tracking architecture evolution over time is needed.

---

Documentation Maintenance Triggers

Use these triggers to determine which document to update when the codebase changes.

Diagram updates

Trigger	Target
New entity class or relationship change	Update ERD in this page
New controller, endpoint, or route mapping	Update layered architecture and request lifecycle diagrams
New security customizer, filter, or JWT converter	Update security filter chain diagram
New service, provider, or repository	Update layered architecture diagram
Flyway migration added (main or test scope)	Re-check ERD and persistence sections
Dockerfile or deployment template change	Update deployment pipeline diagram
pom.xml plugin, profile, or dependency scope change	Update build pipeline diagram

Recent change — bookmarks feature:

The codebase now introduces a new persistence table hrs.user_bookmarks represented by UserBookmarkEntity and its composite id. This requires regenerating the ERD and validating the security filter chain (new /api/users/** routes). Trigger files: backend/src/main/java/ca/bc/gov/nrs/hrs/entity/users/UserBookmarkEntity.java, backend/src/main/java/ca/bc/gov/nrs/hrs/repository/UserBookmarkRepository.java, backend/src/main/resources/db/migration/V1.0.2__bookmarks.sql, backend/src/main/java/ca/bc/gov/nrs/hrs/controller/UserController.java, backend/src/main/java/ca/bc/gov/nrs/hrs/service/UserService.java.

Structure tree updates

Trigger	Target
Any Java source file added, moved, or removed	Regenerate structure tree in Backend Structure
New package or package rename	Update taxonomy and naming-convention commentary
New test file or test resource	Update test tree and test-resource sections
New SQL constants or query module	Reflect the change in repository package commentary

Rules and guidelines updates

Trigger	Target
New architectural pattern adopted	Add explicit rule and placement convention to Backend Structure
Convention violation identified and resolved	Strengthen the relevant rule in Backend Structure
New framework or library adopted	Add dependency-specific constraints to Backend Structure
Security model change	Update security architecture sections in Overview and Structure

Changelog updates (when present)

Trigger	Target
New migration strategy or major migration set	Add entry
Major dependency or runtime version bump	Add entry
New architectural layer or package taxonomy introduced	Add entry
Security boundary or auth-flow change	Add entry

---

Alignment Policy

Both backend applications share this architecture intentionally. Differences are only acceptable where they are inherent to the data-source or integration model of each service.

Application	Allowed differences
nr-waste-plus-backend	Provider-centric external integration, PostgreSQL preference model, BFF role
nr-waste-plus-legacy	Oracle-native query and repository model, MapStruct-centric mapping layer

The Spring Boot 3 vs Spring Boot 4 runtime split is intentional and tracked in issue #341. All other convention differences should be treated as drift and resolved toward alignment.