---
title: SAIF.Services.CleanAddress architecture
summary: Architectural responsibilities, boundaries, and interaction patterns.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-07-24
library: SAIF.Services.CleanAddress
reference_type: package
---

# 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.

```mermaid
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.

```mermaid
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.

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [API reference](api/index.md)

## Sources
- `Services\SAIF.Services.CleanAddress\clsCleanAddress.vb`
- `Services\SAIF.Services.CleanAddress\app.config`
- `Services\SAIF.Services.CleanAddress\Web References\CleanAddressSvc\Reference.vb`