---
title: SAIF.Application.Policy architecture
summary: Architectural responsibilities, boundaries, and interaction patterns for the policy application layer.
status: draft
owner: SAIF Documentation Generation
last_reviewed: 2026-07-31
library: SAIF.Application.Policy
reference_type: package
---

# SAIF.Application.Policy architecture

`SAIF.Application.Policy` is the policy-domain application/orchestration layer. It does not define a local persistence model of its own; instead it creates the policy portal, resolves and authorizes the active policy context, and composes business-layer policy, agency, view, and help-text services behind a single manager and policy-header abstraction.

## Responsibilities
- Establish the Oracle `Policy` portal and expose its `IDataPortalInfo` to downstream readers.
- Retrieve and cache policy data for the current policy number, then decide whether the context is valid and accessible.
- Compose lower-layer policy, agency, association, help-text, and financial services behind `PolicyAppManager`.
- Supply policy-header settings and data providers that apply demo masking, association filtering, and visibility gating.

## Component boundaries
- `PolicyAppManager`: orchestration boundary for policy retrieval, authorization, and portal lifecycle.
- `clsPolicySecurity`: role-classification boundary that answers what kind of user the principal is.
- `SAIF.Business.View.Policy.clsPolicySecurity`: delegated data-level authorization boundary that answers whether the user may see a particular policy.
- `PolicyHeader` classes: presentation-adjacent boundary for rendered header values, help text, associations, and test-information visibility.

## Interaction model
- The library is read-only: `OnWrite` always returns `False`, and transaction hooks only wrap read-side portal behavior.
- Consuming applications extend the library by inheritance through `PolicyAppManager` factory methods and overrides.
- Policy-level authorization is split between local role classification and delegated view-layer policy authorization.
- `UserCanAccessPolicy` grants access unconditionally when `HttpContext.Current Is Nothing`, so non-web hosts bypass the view-layer policy authorization check entirely.**
- `clsPolicyHeaderSecurityManager` and `clsStandardPolicyHeaderSettings` keep process-wide `Shared` caches for association types, user numbers, and per-user authorization results, and the findings show no cache invalidation path beyond process recycling.*

## Architecture diagram
The following diagram shows how `PolicyAppManager` composes lower-layer services behind a single application-layer surface.

```mermaid
flowchart TD
    Caller[Consuming application] --> Manager[PolicyAppManager]
    Manager --> Portal[(Oracle Policy portal<br>DB user GEN)]
    Manager --> ViewData[SAIF.Business.View.Policy<br>clsPolicyData]
    Manager --> ViewSecurity[SAIF.Business.View.Policy<br>clsPolicySecurity]
    Manager --> LocalSecurity[SAIF.Application.Policy<br>clsPolicySecurity]
    Manager --> Core[SAIF.Business.Policy.Core]
    Manager --> Agency[SAIF.Business.Policy.Agency]
    Manager --> HelpTexts[SAIF.BOF.Business]
    Manager --> Header[PolicyHeader subsystem]
    Header --> Settings[clsStandardPolicyHeaderSettings]
    Header --> Provider[clsStandardPolicyHeaderDataProvider]
    Header --> AssocSecurity[clsPolicyHeaderSecurityManager]
```

## Sequence diagram
The following diagram shows the primary policy-context retrieval and authorization sequence.

```mermaid
sequenceDiagram
    participant Caller
    participant Manager as PolicyAppManager
    participant ViewData as clsPolicyData
    participant ViewSecurity as View.Policy clsPolicySecurity
    Caller->>Manager: Retrieve() / set PolicyNumber
    Manager->>Manager: Reject missing policy number
    Manager->>ViewData: GetPolicyData(DPI, PolicyNumber, UserAccessLevel)
    ViewData-->>Manager: PolicyData
    Manager->>Manager: Reject invalid policy
    alt HttpContext.Current Is Nothing
        Manager->>Manager: Allow access unconditionally
    else Web request
        Manager->>ViewSecurity: IsPolicyValidForUser(PolicyData)
        ViewSecurity-->>Manager: access decision
    end
    Manager-->>Caller: ContextSet / NoAccess / Message
```

## Design constraints
- **Version drift (open question).** This library uses the 1.x package generation of `SAIF.BOF.Business.View.Policy`, while the documented dependency in this run is the 2.x library at [SAIF.Business.View.Policy](../saif-business-view-policy/overview.md). Behavioral differences between those generations were not assessed.**
- **Authorization gap.** `UserCanAccessPolicy` allows policy access whenever `HttpContext.Current Is Nothing`, which means batch, service, and test hosts bypass the delegated policy authorization path.**
- The portal always connects as the fixed Oracle database user `GEN`, so database-side identity does not vary by caller.
- `OnCheckSecurity` is overridden with an empty body, leaving `OnRetrieve` as the effective application-level security hook.**
- This library has `frameworkDensity = 0` for the run because its base class is `SAIF.Application.AppManagerBase`, which was explicitly out of scope for inherited-framework injection.

> **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)
- [Security and authorization](security-authorization.md)
- [Database tables](database-tables.md)
- [SQL catalog](sql/index.md)
- [Configuration](configuration.md)
- [API reference](api/index.md)

## Sources
- `Application\SAIF.Application.Policy\PolicyAppManager.vb`
- `Application\SAIF.Application.Policy\clsPolicySecurity.vb`
- `Application\SAIF.Application.Policy\PolicyHeader\clsPolicyHeaderSecurityManager.vb`
- `Application\SAIF.Application.Policy\PolicyHeader\clsStandardPolicyHeaderDataProvider.vb`
- `Application\SAIF.Application.Policy\PolicyHeader\clsStandardPolicyHeaderSettings.vb`
- `Application\SAIF.Application.Policy\packages.config`