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

# BankValidator architecture

BankValidator centers on a single façade class that wraps several generated ASMX SOAP clients and hides vendor-specific authentication, endpoint selection, and request sequencing from callers.

## Responsibilities
- Centralize bank-validation and lookup operations behind `SAIF.clsValidateBank`.
- Create, authenticate, invoke, and dispose vendor SOAP proxies for ABA, ATM, and SSN operations.
- Convert selected vendor SOAP faults into stable caller outcomes for bank-lookup methods.
- Expose typed bank-detail data through the generated `Institutions` DataSet.

## Component boundaries
- `SAIF.clsValidateBank`: Sole handwritten public entry point; owns credentials, endpoint URLs, retry settings, and all call orchestration.
- `ABAService.ABAService`: Generated SOAP client used for ABA validation, ABA verification, company lookup, and bank-detail retrieval.
- `ABAExpress.ABAService`: Generated SOAP client included in the project and disposed by `clsValidateBank`, but not invoked by any public method.
- `ATMService.ATMService`: Generated SOAP client used for ATM participation checks, status lookup, and status-code translation.
- `OFACService.OFACService`: Generated SOAP client included in the project and disposed by `clsValidateBank`, but not invoked by any public method.
- `SSNKeyService.SSNKeyService`: Generated SOAP client used for SSN validation.
- `SAIF.Institutions`: Auto-generated typed DataSet schema for bank-detail payloads returned by `GetBankFullDS`.

## Interaction model
- Callers construct `clsValidateBank` with company ID, user ID, password, and an optional retry limit.
- Each public operation selects one vendor service, performs a logon, issues one or more vendor calls, and then logs off.
- Service URLs are initialized to Lyons/CBIZ endpoints and can be overridden through public properties before use.
- Bank-detail methods catch `SoapException` and substitute empty results; most other vendor failures surface as `ApplicationException` or service exceptions.

## Architecture diagram
The following diagram shows the façade and its generated vendor service clients.

```mermaid
flowchart TD
    Caller[Calling application] --> Facade[SAIF.clsValidateBank]
    Facade --> ABA[ABAService.ABAService]
    Facade --> ABAExpress[ABAExpress.ABAService]
    Facade --> ATM[ATMService.ATMService]
    Facade --> OFAC[OFACService.OFACService]
    Facade --> SSN[SSNKeyService.SSNKeyService]
    Facade --> Institutions[SAIF.Institutions]
    ABA --> Vendor[Lyons/CBIZ SOAP endpoints]
    ATM --> Vendor
    SSN --> Vendor
```

## Sequence diagram
The following diagram shows the standard logon-call-logoff sequence used by an ABA validation request.

```mermaid
sequenceDiagram
    participant Caller
    participant Facade as clsValidateBank
    participant ABA as ABAService
    Caller->>Facade: IsValidABANumber(routingNum)
    Facade->>ABA: Logon(companyId, userId, password)
    ABA-->>Facade: logonToken
    Facade->>ABA: ValidateABA(logonToken, routingNum)
    ABA-->>Facade: Boolean result
    Facade->>ABA: Logoff(logonToken)
    Facade-->>Caller: Boolean result
```

## Design constraints
- The library has no dependency-injection seam or configuration-file binding for service endpoints; endpoint overrides are code-only property assignments.
- The retry counter is shared across logon helper methods through `m_LogonAttempts`.
- Each operation performs synchronous network calls and does not pool or reuse authenticated sessions across public method invocations.
- `GetBankFullDS` depends on XML returned by the ABA service and loads that payload into the generated `Institutions` DataSet schema.

## 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
- `Legacy\BankValidator\clsValidateBank.vb`
- `Legacy\BankValidator\Institutions.Designer.vb`
- `Legacy\BankValidator\Institutions.xsd`
- `Legacy\BankValidator\SAIF.Legacy.BankValidator.vbproj`
- `Legacy\BankValidator\Web References\ABAExpress\Reference.vb`
- `Legacy\BankValidator\Web References\ABAService\Reference.vb`
- `Legacy\BankValidator\Web References\ATMService\Reference.vb`
- `Legacy\BankValidator\Web References\OFACService\Reference.vb`
- `Legacy\BankValidator\Web References\SSNKeyService\Reference.vb`