Filings integration BTR-LEAR-FIlingUI - Pre RFC

[hfekete]

Goal

Describe plan how to handle filings and data exchange between LEAR, Filings UI and BTR services; from perspective of BTR.

Current projects

LEAR - The service responsible for maintaining accurate business information, such as contacts, names, and states, as well as overseeing business filings. This includes sending reminders for required filings and enforcing rules, such as company dissolution for prolonged failure to submit necessary documents.

Filings UI - UI responsible for delivery, among other things of TODO's and business document filings details

BTR - The service we are building Business Transparency Registry will hold details about individuals significantly involved in the company ownership and voting structure.

Requirements

Display on Filing UI of

• TODO's
• Filing

Plan

Since BTR is standalone service, our aim is to ensure users experience consistency, such as locating filings and todo items in one central location, using familiar flows for doing filing etc... To achieve this, we will maximize the use of existing services wherever feasible.

Leveraging LEAR

As previously mentioned, LEAR already handles TODOs, filings, and associated business rules. Our objective is to maintain this arrangement. To ensure consistency in the filing process and present users with the necessary minimum data, we'll utilize LEAR as a service without altering its functionality, except for incorporating the new filing type and expanding rules related to BTR filings.

We'll approach this by establishing communication between the BTR API and the LEAR API, with BTR acting as a user of LEAR. When a user fills out the necessary details for a BTR filing in the BTR UI, the BTR API will collect and validate the data. Acting as an intermediary, it will create a filing in LEAR with only the essential details required to track the filing. Any non-required data, aside from business details already stored in LEAR, will not be shared or transmitted to LEAR.

All the current business logic, like dissolutions, or reminders, will be easily reused for BTR filings as the flow in LEAR already exist.

Leveraging Filings UI

To keep display logic for TODOs and filings consistent with current, we'll ensure that all BTR TODOs and filings are also visible in the Filings UI. This will be accomplished through existing LEAR flows. BTR will have no direct connection to the Filing UI; instead, the Filings UI will access the necessary data through LEAR, ensuring consistency and simple flow of data.

Changes in BTR

As we currently are handling payments(currently filing is free) and communication with Pay API to get invoices we will need to make some changes. Namely, we will drop the handling of Pay API inside BTR API.

Shared data (untested)

Current investigation of the code looks like data we will need to provide to Lear to create minimal filing is:

      filing (aka header)
        date: filing date,
        certifiedBy: string,
        name: FilingTypes.BTR_FILING ** new filing type,
      business: 
        identifier: business identifier,
        legalName: business legal name, ** optional data, but here for convenience

Example submission from BTR API to LEAR API:

{
  "filing": {
    "header": {
      "name": "alteration",
      "certifiedBy": "John Doe",
      "date": "2022-01-01"
    }
  },
  "business": {
    "identifier": "BC1234567",
    "legalName": "Corp Legal Name"
  }
}

Diagram

https://mermaid.live/

flowchart TD
    BUI[BTR UI: Add SIs] -->|Validate data| BTR(BTR API)
    BTR --> |Store BODS json| BODS(BODS repository)
    BTR --> |Create filing| LAPI(LEAR API)
    LAPI --> |TODO's| LUI
    LAPI --> |Handle invoice| LAPI
    LAPI --> |Filings| LUI(Lear UI)

[kialj876]

I wonder if it would be better to have the todos handled in the existing LEAR call. Especially since some of the rules will be dependent on the business information which is stored inside LEAR that BTR would need to call it for. I do agree that we should still save the filing id in case we need to produce filing pdfs later

Also you should mention that we are posting a completed filing to LEAR that has already done the payment flow so you should take pay-api out of the diagram and mention the work in LEAR for handling that flow so it doesn't put it on the pay queue and filer queue.

[thorwolpert]

You don't need what is listed there for a filing.
The JSONSchema for that can identified as:

filing:
    header: this the filing envelope details
    business: useful info for human reference, not used on creation filings
    oneof: creation filing
               anyof: legalFilings - meaning you can submit multiple legal filings in a single filing envelope

I would make a minimal filing for TR, processing equivalent to something like specialResolution or registrarsNotation that does not change the Business DB, or maybe we do want to set the last filed TR, like AR does
add a filingProcessor that just updates the filingMeta, which is displayed on the Ledger.
Filing def'n -> https://github.com/bcgov/business-schemas/blob/main/src/registry_schemas/schemas/filing.json

[thorwolpert]

I would pass it through the Queue (now PubSub) so that delivery is managed outside of the TR and we don't need to worry about retries, etc.

[kialj876]

Looks good to me! Thank you for the updates. I think the only thing to add would be the effectiveDate field inside the header as well

[thorwolpert]

It can be blank, and the system will apply it.
If the effectiveDate is in the future the system treats it as a FED and does not process it until the FED has arrived.