Architecture

Architecture Overview

This document describes the high-level architecture, component topology, communication protocols, and security model of the Forests Client Management System.

---

System Context Diagram

flowchart TD
    subgraph Users["User Layer"]
        Ext["External User\n(BCeID / BC Services Card)"]
        Staff["Ministry Staff\n(IDIR)"]
    end

    subgraph Security["Identity & Access Management"]
        FAM["BC Gov FAM / Keycloak\n+ AWS Cognito SSO"]
    end

    subgraph IngressLayer["Ingress & Routing"]
        Route["OpenShift Route / Ingress Controller"]
    end

    subgraph FrontendTier["Frontend Tier (SPA)"]
        FE["Vue 3 Single Page Application\nTypeScript + Vite + Carbon Design"]
    end

    subgraph BackendTier["Backend Services Tier"]
        BE["Main Backend API\nSpring Boot 4 WebFlux / Java 17\nGraalVM Native Image"]
        PROC["Background Processor\nSpring Integration Engine\nChannels #1 - #10"]
        LEGACY["Legacy Connector API\nSpring Boot 4 WebFlux / Java 21\nOracle DB Adapter"]
    end

    subgraph DataTier["Data Tier"]
        PG[("PostgreSQL\nPrimary Modern DB\n(Flyway Migrated)")]
        ORACLE[("Oracle Database\nLegacy Enterprise DB\n(THE Schema)")]
    end

    subgraph ExternalServices["External Integration Services"]
        BCREG["BC Registry API\n(Corporate Entity Validation)"]
        CPOST["Canada Post AddressComplete\n(Address Resolution)"]
        CHES["CHES Service\n(Common Hosted Email Service)"]
    end

    Ext -->|HTTPS| Route
    Staff -->|HTTPS| Route
    Route --> FE

    FE -->|SSO Login Flow| FAM
    FE -->|REST API with Bearer JWT| BE

    BE -->|Query / Persist Submissions| PG
    BE -->|Proxy Legacy Reads| LEGACY
    BE -->|Verify Business Number| BCREG
    BE -->|Address Lookup| CPOST
    BE -->|Send Email Requests| CHES

    LEGACY -->|Query / Update| ORACLE

    PROC -->|Poll Pending Submissions (#1)| PG
    PROC -->|Check Legacy Duplicates (#2)| LEGACY
    PROC -->|Auto-Approve (#4)| PG
    PROC -->|Persist Approved Submissions (#10)| LEGACY
    PROC -->|Trigger Notification (#5, #8, #9)| BE

Loading

---

Architecture Components

1. Ingress & Security

All traffic enters through the OpenShift Ingress Router over TLS 1.3. User authentication is managed through Forest Access Management (FAM), which bridges BC Gov IDIR, BCeID Business, and BC Services Card into standard OpenID Connect (OIDC) JWT tokens issued via AWS Cognito.

• External BCeID Business: Authenticates corporate applicants and resolves business metadata.
• External BC Services Card (BCSC): Authenticates individual applicants with verified identity attributes.
• Internal IDIR: Authenticates ministry staff. Role-based access control (RBAC) grants capabilities based on roles:
  • CLIENT_VIEWER: Read-only access to client search, summary views, and history.
  • CLIENT_EDITOR: Ability to register clients, add locations, and manage contacts.
  • CLIENT_SUSPEND: Authority to change client active/suspended lifecycle statuses.
  • CLIENT_ADMIN: Full administrative privileges, including manual submission review and adjudication.

2. Frontend Application (frontend/)

The frontend is a Vue 3 Single Page Application written in TypeScript and built with Vite.

• Component Architecture: Built using the Composition API (<script setup lang="ts">) and IBM's Carbon Design System (@carbon/web-components).
• Navigation Guarding: Vue Router controls access based on token claims and provider types.
• Offline / Stubs Mode: Developers can run completely disconnected from the Java backend using an embedded WireMock stub server (npm run preview / npm run stub).
• Read more: Frontend Architecture Overview and Frontend Structure.

3. Main Backend API (backend/)

The primary backend service provides high-performance, non-blocking REST APIs supporting frontend operations.

• Framework: Spring Boot 4 WebFlux built on Project Reactor.
• Compilation: Compiled as a native executable using GraalVM for minimal memory footprint and instantaneous startup.
• Persistence: Reactive database access via R2DBC directly into the PostgreSQL database.
• Integrations: WebClient connectors for BC Registry, Canada Post AddressComplete, CHES, and FAM.
• Read more: Backend Architecture Overview and Backend Structure.

4. Background Processor Service (processor/)

The processor service is an autonomous background engine that automates submission validation, duplicate detection, and post-review synchronization.

• Messaging Architecture: Employs Spring Integration message channels to implement an event-driven, queue-like pipeline without requiring heavyweight message broker infrastructure.
• Submission Channels (#1 – #10):
  • #1 Submission Loader: Polls newly created submissions with status Submission Pending Processing.
  • #2 Validation & Duplicate Matching: Cross-checks company names, addresses, contacts, and legal types against the legacy Oracle database to identify potential duplicates.
  • #3 Review Routing: If potential conflicts or ambiguous matches exist, routes the submission to manual staff review.
  • #4 Auto-Approval: If verification succeeds with 100% confidence, auto-approves the submission.
  • #5 Staff Notification: Dispatches notification requests to the backend for administrative alert emails.
  • #6 Match Loader: Picks up staff-reviewed submissions (approved or rejected).
  • #7 Post-Review Routing: Transitions the submission to persistence or rejection handling.
  • #8 Rejection Notification: Triggers notification email informing the applicant of rejection rationale.
  • #9 Approval Notification: Triggers confirmation email with the newly issued client number.
  • #10 Legacy Persistence: Commits approved client records, locations, and contacts into the Oracle THE schema.
• Read more: Processor Architecture Overview.

5. Legacy Connector Service (legacy/)

The legacy connector isolates direct Oracle database interactions into a dedicated microservice.

• Framework: Spring Boot 4 / Java 21 WebFlux service.
• Database: Connects to the ministry's Oracle Database housing the historic THE schema (forest tenures, timber marks, client tables).
• Purpose: Provides clean, modern REST and reactive APIs for querying legacy client records and executing transactional inserts upon submission approval.
• Read more: Legacy Architecture Overview.

6. Data Tier

• PostgreSQL: Primary data store for modern application state, user submissions, application drafts, and audit logs. Schema is version-controlled with Flyway.
• Oracle Database: Authoritative legacy repository of forest tenures and client accounts (THE schema).
• Read more: Data Model.