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

# SAIF.Business.Claim.Person architecture

SAIF.Business.Claim.Person packages the claim-person and worker aggregate for the claim domain, combining worker demographics, addresses, relationship records, eligibility history, and phonetic-name enrichment behind BOF business objects and Oracle-backed criteria classes.

## Responsibilities
- Maintain worker and claim-person identity records, including primary demographics and history.
- Manage subordinate person data such as names, addresses, tax ID history, health issues, beneficiaries, guardians, and power-of-attorney records.
- Generate and persist phonetic-name keys during claim-person name maintenance.
- Expose DTOs used by the CCClaimDataApi surface for downstream claim-center integrations.

## Component boundaries
- **Worker aggregate:** `clsWorker` anchors the library and coordinates worker-centric state for the claim person record.
- **Identity and history:** `clsClaimPersonName`, `clsClaimPersonAddress`, `clsClaimPersonAuditHistory`, and `clsPersonTaxIDHistory` isolate mutable identity history from the core worker object.
- **Relationship management:** `clsBeneficiary`, `clsGuardian`, `clsGuardianAddress`, `clsPowerOfAttorney`, and related collections manage dependent and legal representative records.
- **Eligibility and health:** `clsAwardEligibility` and `clsWorkerHealthIssue` capture award and exposure data that is persisted in dedicated Oracle tables.
- **Integration DTOs:** The `CCClaimDataApi` folder contains transfer models rather than persistence-heavy BOF entities.

## Interaction model
Higher-level claim workflows retrieve worker and person objects through BOF criteria classes, the library populates child collections from Oracle-backed history tables, and name maintenance performs an additional scalar call to `pk82028_phonetic_name.createPhoneticName` before writing the history and primary person records.

## Architecture diagram
The following diagram shows the high-level component interactions.

```mermaid
flowchart TD
    A[Claim application or service] --> B[Person and worker BOF objects]
    B --> C[Identity and history objects]
    B --> D[Relationship and eligibility objects]
    C --> E[BOF data portal and criteria]
    D --> E
    E --> F[Oracle claim-person tables]
    C --> G[pk82028_phonetic_name.createPhoneticName]
```

## Sequence diagram
The following diagram shows the primary request and persistence sequence.

```mermaid
sequenceDiagram
    participant Client
    participant Worker as clsWorker/collections
    participant Portal as IDataPortalInfo
    participant Oracle
    Client->>Worker: Load worker/person aggregate
    Worker->>Portal: Execute retrieve criteria
    Portal->>Oracle: Query person, history, and relationship tables
    Oracle-->>Worker: Return entity rows
    Client->>Worker: Save name change
    Worker->>Oracle: Call pk82028_phonetic_name.createPhoneticName
    Worker->>Portal: Insert/update person-name history and primary person row
    Portal-->>Client: Persisted business object state
```

## Inherited framework context (from Legends CLI)
- `clsBusinessBase`, `clsBusinessCollectionBase`, and `clsBusinessCollection(Of T)` supply the edit lifecycle, collection traversal, deleted-item tracking, and `IDataErrorInfo` validation surfacing used by the worker, relationship, and history objects.† Source: cached Legends CLI results for `saif-framework-core` (`library` docs; api/business-rules/operations-processes/dependencies queries for the named base classes).
- `IBusinessCriteria` defines the create/retrieve/insert/update/delete SQL contract implemented by the library's nested criteria classes, while `IDataPortalInfo` routes those requests to the configured data-access layer and exposes scalar/result-set helpers.† Source: cached Legends CLI results for `saif-framework-core` (`library` docs; api/operations-processes/dependencies queries for `IBusinessCriteria` and `IDataPortalInfo`).
- `clsAddress` is inherited as framework-managed address behavior, but the cached Core index exposes only indirect documentation rather than a dedicated address API page.† Source: cached Legends CLI results for `saif-framework-core` (`library` docs; api/business-rules/operations-processes/dependencies queries for `clsAddress`).
- Framework carrier and smart-value types such as `clsResultSet`, `clsSAIFDataReader`, `clsSmartDate`, and `clsSmartString` are documented as data-portal or DB-null-safe utility types rather than domain-specific business logic.† Source: cached Legends CLI results for `saif-framework-core` (`library` docs; api/dependencies queries for the named types).

## Design constraints
- Primary name maintenance is coupled to the Oracle phonetic-name function and must preserve that pre-save enrichment step.
- History tables and the primary claim-person row have to remain synchronized during name and tax-ID updates.
- The library relies on BOF base classes for validation and persistence orchestration instead of defining a separate service layer.

## 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)
- [API reference](api/index.md)

> **Note:** Statements marked with `†` are derived from dependency library documentation via the Legends CLI. They describe inherited behavior from the indicated origin library and should be verified if the dependency version changes.

## Sources
- `Business\SAIF.Business.Claim.Person\clsWorker.vb`
- `Business\SAIF.Business.Claim.Person\clsClaimPersonName.vb`
- `Business\SAIF.Business.Claim.Person\clsClaimPersonAddress.vb`
- `Business\SAIF.Business.Claim.Person\clsClaimPersonAuditHistory.vb`
- `Business\SAIF.Business.Claim.Person\clsPersonTaxIDHistory.vb`
- `Business\SAIF.Business.Claim.Person\clsAwardEligibility.vb`
- `Business\SAIF.Business.Claim.Person\clsBeneficiary.vb`
- `Business\SAIF.Business.Claim.Person\clsGuardian.vb`
- `Business\SAIF.Business.Claim.Person\clsPowerOfAttorney.vb`
- `Business\SAIF.Business.Claim.Person\clsWorkerHealthIssue.vb`
- `Business\SAIF.Business.Claim.Person\CCClaimDataApi\clsBeneficiaryAddress.vb`
- `Business\SAIF.Business.Claim.Person\packages.config`
- `Business\SAIF.Business.Claim.Person\SAIF.BOF.Business.Claim.Person.nuspec`