---
title: SAIF.Business.Policy.Premium architecture
summary: Architectural responsibilities, boundaries, and interaction patterns for the premium-domain policy library.
status: draft
owner: Technical Writer
last_reviewed: 2026-07-31
library: SAIF.Business.Policy.Premium
reference_type: package
---

# SAIF.Business.Policy.Premium architecture

`SAIF.Business.Policy.Premium` sits in the BOF business layer and owns the premium-side domain model of a policy period: what was rated, what adjustments applied, what premium amounts should be surfaced, and how premium-adjacent billing and reporting data is represented. It builds on `clsBusinessBase` and `IBusinessCriteria`† while consuming `SAIF.Business.Policy.Rating` for rating-factor contracts and calculations.

## Responsibilities
- Premium-set aggregate management and dual-database routing between Enterprise objects and Policy-side `@POLDB` objects.
- Class coverage modeling, rating-plan association, premium-summary adjustment modeling, and billing/reporting support.

## Component boundaries
- Upward: exposes business objects, collections, interfaces, and extension modules for higher policy/application layers.
- Persistence: routes all CRUD and ad-hoc SQL through BOF data-portal requests and criteria objects†.
- Sibling dependency: depends on [SAIF.Business.Policy.Rating](../saif-business-policy-rating/overview.md); Premium consumes Rating, not the reverse.
- Framework dependency: `clsCodeTableBase` and `clsAddress` are touched by this library, but indexed framework documentation for those types was not available.**

## Interaction model
Callers reach entities through shared factory methods and extension helpers. BOF lifecycle hooks (`BeforeRetrieve`, `AfterRetrieve`, `BeforeInsert`, `AfterInsert`, `BeforeUpdate`, `AfterUpdate`) provide the consistent retrieval and persistence pattern†, while Premium-specific helpers add subtotaling, weighted claim frequency, named premium-amount lookup, and rating-plan merging.

## Architecture diagram
The following diagram shows the library's primary collaborators and the Premium → Rating dependency direction.

```mermaid
flowchart TD
    Caller[Policy callers] --> Premium[SAIF.Business.Policy.Premium]
    Premium --> Rating[SAIF.Business.Policy.Rating]
    Premium --> Core[SAIF.Framework.Core / BOF]
    Core --> Enterprise[(Oracle Enterprise objects)]
    Premium -->|Routing via @POLDB| Policy[(Oracle Policy objects/views)]
```

## Sequence diagram
The following diagram shows the retrieve path for a premium-set-driven class-coverage request.

```mermaid
sequenceDiagram
    participant Caller
    participant Set as clsPremiumSet
    participant Coverage as clsClassCoverageCollection
    participant Portal as BOF data portal
    participant DB as Oracle
    Caller->>Set: GetMostRecentPremiumSet(...)
    Set->>Portal: Submit criteria SQL†
    Portal->>DB: Execute premium-set lookup
    DB-->>Portal: Set row
    Caller->>Coverage: GetClassCoverages(...)
    Coverage->>Portal: Submit class-coverage SQL†
    Portal->>DB: Execute coverage lookup
    DB-->>Caller: Hydrated objects
```

## Design constraints
- Runtime database target selection swaps base tables for `@POLDB`-suffixed objects or `_VIEW` variants.
- `clsPremiumSummaryAdjustment.Criteria.UpdateSQL` throws the BOF invalid-SQL message instead of issuing an update, so summary adjustments behave as insert-only objects.
- `Pipelines/build-vars.yml` contains an `AppName` value that does not match this library's solution/project naming.

> **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.

## 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)

## Sources
- `Business\SAIF.Business.Policy.Premium\clsPremiumSet.vb`
- `Business\SAIF.Business.Policy.Premium\clsClassCoverage.vb`
- `Business\SAIF.Business.Policy.Premium\clsClassCoverageBase.vb`
- `Business\SAIF.Business.Policy.Premium\clsPolicyPeriodRatingPlan.vb`
- `Business\SAIF.Business.Policy.Premium\clsPremiumSummaryAdjustment.vb`
- `Business\SAIF.Business.Policy.Premium\Pipelines\build-vars.yml`