Skip to content

SAIF.Services.CleanAddress architecture

SAIF.Services.CleanAddress is a thin service-adapter library. Its public facade creates a generated SOAP client on demand, calls the CorrectAddress service, and converts vendor-specific output fields into library DTOs and enum values that are easier for callers to consume.

Responsibilities

  • Expose a compact public API for health checks, batch execution, proper-case conversion, ZIP lookup, and address cleansing.
  • Centralize vendor interaction in one facade so consuming applications do not call the generated SOAP proxy directly.
  • Normalize vendor outputs into clsCleanAddressInfo, clsCityStateCountyInfo, and clsBatchReturnInfo.
  • Apply address-classification and barcode-derivation logic after the vendor service returns its raw fields.

Component boundaries

  • clsCleanAddress: Sole public behavior class; constructs CleanAddressSvc.clsCAServices, sets redirect and credential behavior, and maps results.
  • CleanAddressSvc.clsCAServices: Generated SOAP proxy whose constructor loads the endpoint URL from My.Settings.
  • clsCleanAddressInfo: Data carrier for normalized address-cleanse output.
  • clsCityStateCountyInfo: Data carrier for parsed ZIP lookup rows.
  • clsBatchReturnInfo and BatchReturnTypes: Data carrier and enum for normalized batch outcomes.

Interaction model

  • Each public method creates a new CleanAddressSvc.clsCAServices instance rather than reusing a shared client.
  • The generated proxy constructor sets Url from Global.SAIF.Services.CleanAddress.My.MySettings.Default.SAIF_Services_CleanAddress_CleanAddressSvc_clsCAServices.
  • clsCleanAddress sets AllowAutoRedirect = True and UseDefaultCredentials = True before invoking each vendor operation.
  • CleanAddress() performs additional post-call logic locally by parsing USPS error codes, classifying the result, and deriving the POSTNET barcode.

Architecture diagram

The following diagram shows the library's high-level component interactions.

flowchart TD
    Caller[Calling application] --> Facade[clsCleanAddress]
    Facade --> Proxy[CleanAddressSvc.clsCAServices]
    Proxy --> Settings[My.Settings / app.config endpoint]
    Proxy --> Vendor[CorrectAddress SOAP service]
    Facade --> AddressInfo[clsCleanAddressInfo]
    Facade --> ZipInfo[clsCityStateCountyInfo]
    Facade --> BatchInfo[clsBatchReturnInfo + BatchReturnTypes]

Sequence diagram

The following diagram shows the primary request/response sequence.

sequenceDiagram
    participant Caller
    participant Facade as clsCleanAddress
    participant Proxy as clsCAServices
    participant Vendor as CorrectAddress service
    Caller->>Facade: CleanAddress(line1, line2, city, state, zip, zip4, mixedCase)
    Facade->>Proxy: New clsCAServices()
    Proxy->>Proxy: Load Url from My.Settings
    Facade->>Proxy: Set AllowAutoRedirect / UseDefaultCredentials
    Facade->>Vendor: CleanAddress(..., ByRef outputs)
    Vendor-->>Facade: Return code, error codes, address fields
    Facade->>Facade: Parse codes and derive status flags/barcode
    Facade-->>Caller: clsCleanAddressInfo

Design constraints

  • A new SOAP proxy instance is created for every public-method call.
  • CleanAddress() swallows service-call exceptions and converts them into return code -999 instead of rethrowing the exception.
  • USPS error-code descriptions are hardcoded in a Select Case block inside CleanAddress().
  • ZIP lookup parsing depends on fixed-width rows in a preallocated output buffer.

Sources

  • Services\SAIF.Services.CleanAddress\clsCleanAddress.vb
  • Services\SAIF.Services.CleanAddress\app.config
  • Services\SAIF.Services.CleanAddress\Web References\CleanAddressSvc\Reference.vb