---
title: SAIF.Business.View.Provider architecture
summary: Architectural responsibilities, boundaries, and interaction patterns.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-07-24
library: SAIF.Business.View.Provider
reference_type: package
---
# SAIF.Business.View.Provider architecture
SAIF.Business.View.Provider is a mid-tier VB.NET class library implementing the SAIF BOF business-object layer for the provider domain (medical/insurance providers, provider locations, addresses, tax IDs, relationships, ineligibility periods, service contracts, and provider search). It follows the standard BOF pattern of `clsBusinessBase`/`clsBusinessCollection(Of T)` subclasses paired with nested `Criteria` classes implementing `IBusinessCriteria`, and is read-only from a database perspective — every live SQL statement discovered is a retrieval query.
## Responsibilities
- Retrieve and represent core provider entities: `clsProvider`, `clsProviderCollection`, `clsProviderAddress`/`Collection`, `clsProviderLocation`/`Collection`, `clsProviderRelationship`/`Collection`, `clsProviderIneligibilityPeriod`/`Collection`, `clsProviderTaxID`/`Collection`, `clsProviderType`/`Collection`.
- Orchestrate multi-criteria provider search (`clsProviderSearch`), dynamically assembling SQL joins across provider, address, tax ID, identity, service, and MCO plan tables based on supplied filters.
- Supply supporting DTO/list wrappers populated by parent business objects: `clsMCOProvider`'s list type, `clsDCBSCostCharge`'s list type, `clsProviderServiceContractInfo`/`List`, `clsProviderServiceInfo`/`List`.
- Expose a legacy typed `DataSet` (`Institutions.Designer.vb`, generated from `Institutions.xsd`) for tabular institution data, distinct from the BOF business-object pattern used elsewhere.
## Component boundaries
- **BOF business objects** (`clsProvider`, `clsProviderCollection`, `clsProviderAddress`/`Collection`, `clsProviderLocation`/`Collection`, `clsProviderRelationship`/`Collection`, `clsProviderIneligibilityPeriod`/`Collection`, `clsProviderType`/`Collection`): each inherits `clsBusinessBase` or `clsBusinessCollection(Of T)` and defines a nested `Friend Class Criteria` implementing `IBusinessCriteria`/`iBusinessCriteria`, supplying `CreateSQL`/`RetrieveSQL`/`InsertSQL`/`UpdateSQL`/`DeleteSQL` consumed through the standard BOF data-portal (`IDataPortalInfo.ProcessPortalRequest()`) lifecycle.
- **Retrieve-only boundary** (`clsProviderTaxIDCollection`): its `Criteria` class deviates from the standard pattern, inheriting `clsRetrieveOnlyBusinessCriteria` and calling `Me.SetRetrieveSQL(...)` directly rather than implementing all five `IBusinessCriteria` members — no create/update/delete path exists for tax-ID data through this collection.
- **Read-only reference boundary** (`clsProviderType`/`Collection`): `Criteria` throws `ApplicationException` for `CreateSQL`/`DeleteSQL`/`InsertSQL`/`UpdateSQL`, leaving only `RetrieveSQL` functional — reference-data lookup only.
- **Search orchestrator** (`clsProviderSearch`): builds dynamic SQL join clauses at runtime based on supplied search criteria (service type, MCO plan, business/person flag, tax ID, provider name, address, phone) rather than using static per-object CRUD SQL; defines nested `clsSearchResults` and a `ReadOnlyCollection(Of clsSearchResults)` result type.
- **Plain DTO/list wrappers** (`clsMCOProvider`'s list, `clsDCBSCostCharge`'s list, `clsProviderServiceContractInfo`/`List`, `clsProviderServiceInfo`/`List`): inherit directly from `Generic.List(Of T)`, with no BOF base class or `IBusinessCriteria` — populated by parent business objects rather than performing independent data access.
- **Legacy typed DataSet** (`Institutions.Designer.vb`): machine-generated ADO.NET typed-DataSet code, structurally separate from the BOF business-object pattern; its consumers within this library were not confirmed**.
- Responsibility boundary: this library is purely a data/business-object layer for provider-domain entities — no UI, no web hosting, no console entry point.
## Architecture diagram
The following diagram shows the high-level component interactions for the provider business-object layer.
```mermaid
flowchart TD
Consumer[Consuming application/library] --> Provider["clsProvider / clsProviderCollection"]
Consumer --> Search["clsProviderSearch
(dynamic SQL join orchestrator)"]
Consumer --> ListTypes["DTO list wrappers
(clsMCOProviderList, clsDCBSCostChargeList,
clsProviderServiceList, clsProviderServiceContractList)"]
Provider --> Address["clsProviderAddress / Collection"]
Provider --> Location["clsProviderLocation / Collection"]
Provider --> TaxID["clsProviderTaxID / Collection (retrieve-only)"]
Location --> Relationship["clsProviderRelationship / Collection"]
Location --> Inelig["clsProviderIneligibilityPeriod / Collection"]
Location --> ProviderType["clsProviderType / Collection (retrieve-only reference data)"]
Search --> DataPortal["IDataPortalInfo / data portal"]
Provider --> DataPortal
Address --> DataPortal
Location --> DataPortal
Relationship --> DataPortal
Inelig --> DataPortal
ProviderType --> DataPortal
TaxID --> DataPortal
DataPortal --> Oracle[(Oracle database)]
ListTypes --> Oracle
```
## Interaction model
- Business objects receive an `IDataPortalInfo` through their `Criteria` constructors/factory methods, consistent with the standard BOF data-portal pattern: a factory method builds `Criteria`, sets `DataRequest.SQLStatement` from the criteria's SQL property, executes via the data portal, and fills object state in `AfterRetrieve`/`BeforeRetrieve` lifecycle methods.
- `clsProviderSearch.searchForProvider()` dynamically composes a joined query across `PROVIDER_LOCATION`, `PROVIDER_TYPE_CODE`, `PROVIDER_ADDRESS`, `PROVIDER_TAX_ID`, `PROVIDER_IDENTITY`, `PROVIDER_SERVICE`, and `MCO_PROVIDER`, adding `JOIN` clauses and bind variables only when the corresponding filter is supplied by the caller.
- Collection-type business objects (`clsProviderAddressCollection`, `clsProviderLocationCollection`, etc.) each retrieve a set of child business objects via their own `RetrieveSQL`, independent of the search orchestrator.
- Simple DTO list types (`clsMCOProviderList`, `clsDCBSCostChargeList`, `clsProviderServiceContractList`, `clsProviderServiceList`) execute their own direct `StringBuilder`-composed retrieval queries from their constructors, filtered by a provider location ID, rather than going through the `IBusinessCriteria`/data-portal pattern.
The following diagram shows the primary provider-retrieval request sequence.
```mermaid
sequenceDiagram
participant Consumer
participant Provider as clsProvider
participant Criteria as Criteria (IBusinessCriteria)
participant DPI as IDataPortalInfo
participant DB as Oracle database
Consumer->>Provider: GetProvider(inDataportal, inProviderID)
Provider->>Criteria: BeforeRetrieve builds RetrieveSQL
Provider->>DPI: ProcessPortalRequest(RetrieveSQL)
DPI->>DB: Execute retrieval query
DB-->>DPI: Result rows
DPI-->>Provider: AfterRetrieve populates object state
Provider-->>Consumer: Populated clsProvider instance
```
## Design constraints
- No `` elements — all dependencies are NuGet package references; no internal cross-project dependency within this repository.
- All discovered SQL is read-only (CRUD type `R`) except `clsProviderType`, which explicitly blocks Create/Insert/Update/Delete via thrown exceptions, and `clsProviderTaxIDCollection`, which is structurally retrieve-only via `clsRetrieveOnlyBusinessCriteria`.
- Every SQL table reference is unqualified in source, and no local `.config` file exposes an Oracle `User ID`, so schema/link ownership cannot be confirmed from this library's scope alone**.
- Database type is Oracle, confirmed by bind-variable syntax (`:ServiceType`, `:MCOPlan`, `:Offset`), `sysdate` usage, the `Oracle.ManagedDataAccess` package reference, and ODP.NET provider registration in `app.config`/`Web.config`.
- No `IEnvironmentService`, `ConfigurationManager.AppSettings`, `DbConnectionManager`, or AD/security enforcement points were found — this library does not qualify for Phase 1c (security) or Phase 1d (config) documentation gates.
- Per `dependency-resolution.json`, BOF business base classes (`clsBusinessBase`, `clsRetrieveOnlyBusinessCriteria`, etc.) are not present in the Legends CLI index for this repository; their exact enforcement semantics are inherited from the `SAIF.BOF.Business` package but could not be independently confirmed*.
## 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)
> **Note:** Statements marked with `*` were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts. Statements marked with `**` could not be confirmed; treat as unknown until verified.
## Sources
- `Business\SAIF.Business.View.Provider\clsProvider.vb`
- `Business\SAIF.Business.View.Provider\clsProviderCollection.vb`
- `Business\SAIF.Business.View.Provider\clsProviderAddress.vb`
- `Business\SAIF.Business.View.Provider\clsProviderAddressCollection.vb`
- `Business\SAIF.Business.View.Provider\clsProviderIneligibilityPeriod.vb`
- `Business\SAIF.Business.View.Provider\clsProviderIneligibilityPeriodCollection.vb`
- `Business\SAIF.Business.View.Provider\clsProviderLocation.vb`
- `Business\SAIF.Business.View.Provider\clsProviderLocationCollection.vb`
- `Business\SAIF.Business.View.Provider\clsProviderRelationship.vb`
- `Business\SAIF.Business.View.Provider\clsProviderRelationshipCollection.vb`
- `Business\SAIF.Business.View.Provider\clsProviderSearch.vb`
- `Business\SAIF.Business.View.Provider\clsProviderServiceContract.vb`
- `Business\SAIF.Business.View.Provider\clsProviderServices.vb`
- `Business\SAIF.Business.View.Provider\clsProviderTaxID.vb`
- `Business\SAIF.Business.View.Provider\clsProviderTaxIDCollection.vb`
- `Business\SAIF.Business.View.Provider\clsProviderType.vb`
- `Business\SAIF.Business.View.Provider\clsProviderTypeCollection.vb`
- `Business\SAIF.Business.View.Provider\clsMCOProvider.vb`
- `Business\SAIF.Business.View.Provider\clsDCBSCostCharge.vb`
- `Business\SAIF.Business.View.Provider\Institutions.Designer.vb`
- `Business\SAIF.Business.View.Provider\SAIF.BOF.Business.View.Provider.vbproj`