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

# SAIF.Business.Provider architecture

`SAIF.Business.Provider` combines a BOF domain layer that owns provider persistence with an API integration layer that translates selected provider changes to ContactManager and ClaimCenter endpoints.

## Responsibilities
- Own provider-domain business objects and Oracle `IBusinessCriteria` CRUD behavior.
- Provide direct SQL utility lookups for selected provider, plan, specialty, and tax-ID queries.
- Synchronize address, identifier, membership, relationship, and TIN data with ContactManager.
- Retrieve payment data through the ClaimCenter API adapter.

## Component boundaries
- `clsBusinessBase` / `clsBusinessCollection(Of T)` types: Domain-layer objects that own provider business state and Oracle persistence.
- `clsProviderUtility`: Direct SQL helper that sits outside the BOF criteria pattern.
- `Api\` adapters: `clsBusinessApiBase` derivatives that build routes and call external APIs.
- `Api\ContactManagerDTOs` and `Api\ClaimCenterDTOs`: Payload contracts for external API serialization and deserialization.
- `ProviderTranslator`: Relationship-code translator used during ContactManager synchronization.

## Interaction model
- BOF factory methods retrieve and save business objects through the data portal.
- Address and tax-ID save paths invoke `CleanAddressHelper` before Oracle persistence.
- Tax-ID persistence triggers `clsTaxApi.UpdateTinContact()` after successful insert and update operations.
- `clsPaymentApi` uses the `ClaimCenterApi` client registration to retrieve payment history.

## Architecture diagram
The following diagram shows the core BOF domain layer, direct SQL helper, and external API boundaries.

```mermaid
flowchart TD
    Consumer[Consuming application] --> Domain[BOF domain layer<br>clsProvider, clsProviderLocation,<br>clsProviderAddress, clsProviderTaxID, and related types]
    Domain --> Oracle[(Oracle tables<br>PROVIDER, PROVIDER_LOCATION,<br>PROVIDER_ADDRESS, PROVIDER_TAX_ID, and related tables)]
    Domain --> Utility[clsProviderUtility<br>direct SQL lookups]
    Utility --> Oracle
    Domain --> CleanAddress[CleanAddressHelper]
    CleanAddress --> CleanAddressSvc[Clean Address service]
    Domain --> ApiLayer[API integration layer<br>clsAddressApi, clsIdentifierApi,<br>clsMembershipApi, clsPaymentApi, clsTaxApi]
    ApiLayer --> ContactManager[ContactManager REST API<br>ProviderApi client]
    ApiLayer --> ClaimCenter[ClaimCenter REST API<br>ClaimCenterApi client]
    ApiLayer --> DTOs[DTO payloads<br>ContactManagerDTOs and ClaimCenterDTOs]
```

## Sequence diagram
The following diagram shows the BOF retrieval path used to load a provider aggregate.

```mermaid
sequenceDiagram
    participant Caller
    participant Provider as clsProvider
    participant Portal as IDataPortalInfo.DataAccessLayer
    participant Oracle
    Caller->>Provider: GetProvider(providerSeqNum)
    Provider->>Portal: RetrieveObject(Criteria)
    Portal->>Oracle: Execute RetrieveSQL
    Oracle-->>Portal: Result set
    Portal-->>Provider: AfterRetrieve / Fill
    Provider-->>Caller: Populated clsProvider
```

The following diagram shows the tax-ID save path that persists Oracle data and then updates ContactManager.

```mermaid
sequenceDiagram
    participant Caller
    participant TaxID as clsProviderTaxID
    participant Clean as CleanAddressHelper
    participant Portal as IDataPortalInfo.DataAccessLayer
    participant Oracle
    participant TaxApi as clsTaxApi
    participant ContactManager
    Caller->>TaxID: Save()
    TaxID->>Clean: Validate / normalize address
    TaxID->>Portal: SaveObject(criteria)
    Portal->>Oracle: Execute InsertSQL or UpdateSQL
    Oracle-->>Portal: Rows affected
    Portal-->>TaxID: AfterInsert / AfterUpdate
    TaxID->>TaxApi: UpdateTinContact()
    TaxApi->>ContactManager: PUT provider/{providerNumber}/tin
    ContactManager-->>TaxApi: API result
    TaxApi-->>Caller: Synchronization complete
```

## Design constraints
- Database connections are selected outside this library through `IDataPortalInfo.PortalID`.
- The project resolves internal SAIF dependencies through NuGet packages rather than `<ProjectReference>` items.
- Authorization is not implemented in this library and must be enforced by consuming applications.
- Provider search stops after 300 results.

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [Database tables](database-tables.md)
- [SQL catalog](sql/index.md)
- [API reference](api/index.md)
- [Configuration](configuration.md)

## Sources
- `Business\SAIF.Business.Provider\clsProvider.vb`
- `Business\SAIF.Business.Provider\clsProviderSearch.vb`
- `Business\SAIF.Business.Provider\clsProviderAddress.vb`
- `Business\SAIF.Business.Provider\clsProviderTaxID.vb`
- `Business\SAIF.Business.Provider\clsProviderLocation.vb`
- `Business\SAIF.Business.Provider\clsProviderRelationship.vb`
- `Business\SAIF.Business.Provider\clsProviderUtility.vb`
- `Business\SAIF.Business.Provider\Api\clsPaymentApi.vb`
- `Business\SAIF.Business.Provider\Api\clsTaxApi.vb`
- `Business\SAIF.Business.Provider\Api\Translator\ProviderTranslator.vb`