--- title: SAIF.Business.Claim.MedicalBill architecture summary: Architectural responsibilities, boundaries, and interaction patterns. status: draft owner: SAIF Doc Gen last_reviewed: 2026-07-28 library: SAIF.Business.Claim.MedicalBill reference_type: package --- # SAIF.Business.Claim.MedicalBill architecture `SAIF.Business.Claim.MedicalBill` is the medical-bill business component for retrieving claim bill data, loading audit-service and EOB detail, maintaining national-drug pricing tables, and enforcing confidentiality and authorization checks around medical-bill access. ## Responsibilities - Retrieve medical-bill collections and expose bill-level business objects to claim workflows. - Retrieve audit services, service adjustments, and EOB notes through `PK82396_MEDICAL_BILLS`. - Maintain national-drug, national-drug-price, and NDC price-history records through BOF CRUD objects. - Provide adjustment-code lookup collections used by medical-bill audit workflows. - Apply caller-classification and authorization-aware confidentiality rules around medical-bill data. ## Inherited framework context (from Legends CLI) Cached `resolvedTypes[].queries[]` results for `SAIF.Business.Claim.MedicalBill` indicate the following inherited framework behavior: - `IBusinessCriteria` provides the BOF criteria contract that supplies overridable create/retrieve/insert/update/delete request slots for database and API-backed requests.* (source: `saif-framework-core` library docs) - `IDataPortalInfo` supplies connection, data-access-layer, API-client, and scalar-execution context to business objects during persistence and retrieval.* (source: `saif-framework-core` library docs) - `IDataRequest` represents the request abstraction used by the Oracle and SQL portal implementations beneath BOF business objects.* (source: `saif-framework-core` library docs) - `clsBusinessBase` contributes edit lifecycle support and a per-object `clsRulesManager` used to surface validation state.* (source: `saif-framework-core` library docs) - `clsBusinessCollection(Of T)` contributes typed collection traversal, deleted-item tracking, and collection-level validation surfacing.* (source: `saif-framework-core` library docs) - `clsBusinessCollectionBase` contributes collection traversal, deleted-item tracking, and `IDataErrorInfo` validation surfacing for collection objects.* (source: `saif-framework-core` library docs) - `clsResultSet` is identified as a framework result-wrapper type, but no deeper indexed behavior was returned by the cached Legends results.* (source: `saif-framework-core` library docs) - `clsSAIFDataReader` is identified as a framework data-reader abstraction, but no deeper indexed behavior was returned by the cached Legends results.* (source: `saif-framework-core` library docs) - `clsSecurityPrincipal` is identified as the security principal abstraction referenced by the library's authorization helpers, but the cached Legends results did not return deeper indexed behavior for it.* (source: `saif-framework-core` library docs) - `clsSmartDate` is part of the BOF smart-value wrapper set used to carry null-safe date values through business objects.* (source: `saif-framework-core` library docs) - `clsSmartDecimal` is part of the BOF smart-value wrapper set used to carry null-safe decimal values through business objects.* (source: `saif-framework-core` library docs) - `clsSmartString` is part of the BOF smart-value wrapper set used to carry null-safe string values through business objects.* (source: `saif-framework-core` library docs) ## Component boundaries - **Medical-bill boundary**: `clsMedicalBill` and `clsMedicalBillCollection` own claim-bill retrieval and bill-level confidentiality behavior. - **Audit-detail boundary**: `clsAuditServiceCollection`, `clsEOBNoteCollection`, and `clsServiceAdjustmentCollection` expose procedure-backed retrieval of audit-facing medical-bill detail. - **Drug-pricing boundary**: `clsNationalDrug`, `clsNationalDrugPrice`, `clsNdcPriceHistory`, and related collections own pricing-table CRUD behavior. - **Lookup boundary**: `clsAdjustmentCode*` objects isolate adjustment-code lookups for audit-service processing. - **Security boundary**: `HasExposureAccess`, `HasHealthIssueAccess`, `IsSAIFEmployee`, and worker-name masking logic isolate confidentiality decisions from the rest of the model. ## Interaction model Callers retrieve medical-bill collections through framework access layers, collection objects classify the caller and propagate confidentiality flags to child bill objects, and procedure-backed collections retrieve audit detail from Oracle. Drug-pricing entities follow the standard BOF CRUD path directly against Oracle tables. ## Architecture diagram The following diagram shows high-level component interactions. ```mermaid flowchart TD A[Claim applications] --> B[Medical bill collection] B --> C[SecurityPrincipal checks] B --> D[Data API access layer] B --> E[Audit and EOB collections] E --> F[PK82396_MEDICAL_BILLS] D --> G[Medical bill data source] F --> H[Medical bill Oracle tables] ``` ## Sequence diagram The following diagram shows the primary request/response sequence. ```mermaid sequenceDiagram participant App as Claim application participant Bills as clsMedicalBillCollection participant Sec as clsSecurityPrincipal participant API as DataApiAccessLayer participant Child as clsMedicalBill App->>Bills: Retrieve medical bills for a claim Bills->>Sec: Check exposure and collateral-health access Sec-->>Bills: Authorization result Bills->>API: Retrieve bill result set API-->>Bills: Medical bill data Bills->>Child: Propagate employee and conflict flags Child-->>Bills: Masked or unmasked worker names Bills-->>App: Filtered bill collection ``` ## Design constraints - Retrieval is split between an API-oriented collection path and Oracle procedure-backed audit-detail collections, so medical-bill behavior spans two data-access patterns. - Authorization helpers for exposure and collateral-health access are present, but Stage 1c did not observe local call sites that actively deny or filter data through those helpers. - Worker-name masking relies on caller classification and conflict detection, so consumer-visible output can vary without any schema change. - `PK82396_MEDICAL_BILLS` is the sole traced package contract for audit-detail retrieval and must remain aligned with the BOF collection expectations. ## 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) - [Procedures](procedures/index.md) - [Security and authorization](security-authorization.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.Claim.MedicalBill\clsMedicalBill.vb` - `Business\SAIF.Business.Claim.MedicalBill\clsMedicalBillCollection.vb` - `Business\SAIF.Business.Claim.MedicalBill\clsAuditServiceCollection.vb` - `Business\SAIF.Business.Claim.MedicalBill\clsEOBNoteCollection.vb` - `Business\SAIF.Business.Claim.MedicalBill\clsServiceAdjustmentCollection.vb` - `Business\SAIF.Business.Claim.MedicalBill\clsNationalDrug.vb` - `Business\SAIF.Business.Claim.MedicalBill\clsNationalDrugPrice.vb` - `Business\SAIF.Business.Claim.MedicalBill\clsNdcPriceHistory.vb` - `Business\SAIF.Business.Claim.MedicalBill\packages.config` - `Business\SAIF.Business.Claim.MedicalBill\SAIF.BOF.Business.Claim.MedicalBill.nuspec` - `Business\SAIF.Business.Claim.MedicalBill\Pipelines\build-vars.yml` - `Business\SAIF.Business.Claim.MedicalBill\clsAdjustmentCode.vb` - `Business\SAIF.Business.Claim.MedicalBill\clsAdjustmentCodeCollection.vb` - `Business\SAIF.Business.Claim.MedicalBill\clsNationalDrugPriceCollection.vb` - `Business\SAIF.Business.Claim.MedicalBill\clsNdcPriceHistoryCollection.vb` - `Business\SAIF.Business.Claim.MedicalBill\SAIF.BOF.Business.Claim.MedicalBill.vbproj`