Processor Architecture Overview

Processor Architecture Overview

The nr-forest-client-processor is an autonomous background processing microservice responsible for orchestrating submission evaluation, duplicate detection, automated approvals, and legacy persistence.

---

Architecture Pattern: Spring Integration Channels

To minimize coupling between components and eliminate the overhead of external message brokers (such as RabbitMQ or Kafka), the processor uses Spring Integration message channels. Submissions transition through ten logical channels (#1 through #10), each handled by specialized event listeners.

flowchart TD
    subgraph Ingestion["1. Ingestion Phase"]
        CH1["Channel #1: Submission Loader\n(Polls PostgreSQL for Pending Submissions)"]
    end

    subgraph Evaluation["2. Verification & Matching Phase"]
        CH2["Channel #2: Validator & Duplicate Matcher\n(Evaluates Against Legacy Oracle Data)"]
        CH3["Channel #3: Manual Review Router\n(Marks for Staff Attention)"]
        CH4["Channel #4: Auto-Approval Pipeline\n(Validates Clean Submissions)"]
    end

    subgraph StaffReview["3. Staff Review Phase"]
        CH5["Channel #5: Staff Notification Dispatcher\n(Alerts Ministry Administrators via Email)"]
        CH6["Channel #6: Reviewed Submission Loader\n(Picks up Adjudicated Submissions)"]
        CH7["Channel #7: Post-Review Evaluator"]
    end

    subgraph Completion["4. Completion & Legacy Sync"]
        CH8["Channel #8: Rejection Notification Dispatcher\n(Sends Explanation Email to Applicant)"]
        CH9["Channel #9: Approval Notification Dispatcher\n(Sends Success Email with Client Number)"]
        CH10["Channel #10: Legacy Oracle Persister\n(Commits Approved Client Record to THE Schema)"]
    end

    CH1 --> CH2
    CH2 -->|Ambiguous or Conflicts| CH3
    CH2 -->|100% Clean Match| CH4

    CH3 --> CH5
    CH4 --> CH7

    CH6 --> CH7
    CH7 -->|Rejected| CH8
    CH7 -->|Approved| CH10
    CH10 --> CH9

Loading

---

Detailed Channel Descriptions

Channel #1: Submission Loader

• Trigger: Periodic polling timer (ca.bc.gov.nrs.processor.poolTime, defaults to 5M).
• Action: Queries PostgreSQL for submissions with status code Submission Pending Processing. Extracts submission metadata and payloads, then dispatches them into Channel #2.

Channel #2: Validator & Duplicate Matcher

• Action: Performs deep verification of client information:
  • Validates incorporation number and entity status against BC Registry data.
  • Queries the legacy Oracle service for potential duplicate client numbers, names, or addresses.
  • Generates a confidence match score.
• Routing:
  • If potential duplicate or ambiguity detected: routes to Channel #3.
  • If 100% clean with no conflicts: routes to Channel #4.

Channel #3: Manual Review Router

• Action: Updates submission status to Under Review in PostgreSQL, attaching the duplicate match details and reasons for manual inspection.
• Next Step: Forwards message to Channel #5.

Channel #4: Auto-Approval Pipeline

• Action: Updates submission status to Approved.
• Next Step: Moves submission directly into Channel #7 (Post-Review Pipeline).

Channel #5: Staff Notification Dispatcher

• Action: Triggers an administrative alert to ministry staff informing them that a submission requires manual review.

Channel #6: Reviewed Submission Loader

• Action: Picks up submissions that have been reviewed and adjudicated by ministry staff in the Staff Review portal (SubmissionReviewPage.vue).
• Next Step: Forwards to Channel #7.

Channel #7: Post-Review Evaluator

• Action: Evaluates the decision recorded on the submission:
  • If decision is Rejected: routes to Channel #8.
  • If decision is Approved: routes to Channel #10.

Channel #8: Rejection Notification Dispatcher

• Action: Issues an email request via the backend's CHES client informing the applicant of the rejection reason.

Channel #9: Approval Notification Dispatcher

• Action: Issues an email request with the newly assigned Forest Client Number to the applicant.

Channel #10: Legacy Oracle Persister

• Action: Calls the legacy service to insert the new client record, assign the client number from the Oracle sequence, and save associated locations and contacts into the THE schema. Once successfully committed, triggers Channel #9.