---
title: SAIF.Business.External.Users architecture
summary: Architectural responsibilities, boundaries, and interaction patterns.
status: draft
owner: <owner>
last_reviewed: 2026-07-24
library: SAIF.Business.External.Users
reference_type: package
---

# SAIF.Business.External.Users architecture

SAIF.Business.External.Users is a component-tier BOF business library (class library, no program entry point) that manages identity, credentials, and access-group data for external (non-employee) portal users, plus the auditor/zip-code assignment data used by claim audit-assignment workflows. It follows the standard SAIF BOF pattern of `clsBusinessBase`/`clsBusinessCollectionBase` subclasses with nested `IBusinessCriteria` classes carrying SQL and lifecycle `Before*`/`After*` methods.

## Responsibilities
- Manage external-user identity, credentials, status flags, and the `IsAuthorizedUser` authorization data flag.
- Manage security questions used for password recovery.
- Manage a deny-self-registration block-list checked during user registration.
- Manage user-type/role code classification and user access-group membership.
- Manage auditor entities, auditor zip-code geographic assignment, and audit-assignment overrides used by claim audit workflows.

## Component boundaries
- `clsUser` (+ nested `clsUserCollection`): core external-user entity — credentials, status, `IsAuthorizedUser` flag, CRUD lifecycle.
- `clsAuditor` / `clsAuditorCollection`, `clsAuditAssignmentOverride`, `clsAuditorZipCode` / `clsAuditorZipCodeCollection`: auditor entity, assignment overrides, and geographic (zip code) association for claim-audit assignment.
- `clsUserAccessGroup` (+ nested collection): group membership data for external users, including AD-group association tables.
- `clsUserDenySelfRegistration` (+ nested collection): deny-list entries checked during self-registration.*
- `clsUserSecurityQuestion` (+ nested collection): security question/answer records for password recovery.
- `clsUserType` (+ nested collection): user type/role code lookups.
- `clsZipCode`: standalone zip code lookup entity.
- `clsCredentials`, `clsPassword`, `clsNewUserArgs`, `clsAudit`: supporting value/argument objects.*
- `mdlAuditor`, `mdlCodeMaps`, `mdlExtensions`, `mdlGroupAssociation`: shared helper modules, code-table maps, and extension methods.
- Generated `Institutions` typed DataSet: excluded from hand-authored business surface.

## Interaction model
- This library sits at a comparatively high point in the dependency graph: it depends on numerous other `SAIF.BOF.Business.*` libraries (Claim, Claim.Authority, Claim.Maintenance, Claim.MedicalBill, Claim.Payment, Claim.Person, CustomerContact, EPay.USBank, Payment, Payment.EFT, Policy and Policy.* sublibraries, Provider.PaymentPreference, Tasks, Tasks.Claim, Utilities, View.Claim, View.Policy, View.Provider), aggregating identity concerns across claim/policy/payment/provider domains.*
- All persistence flows through the standard BOF `IBusinessCriteria` pattern (`CreateSQL`/`RetrieveSQL`/`InsertSQL`/`UpdateSQL`/`DeleteSQL`) against an Oracle database, evidenced by `:`-prefixed bind-variable syntax and Oracle client configuration sections.
- No presentation-layer types or WCF/Web API surface were detected in this library's own source; it is consumed by calling application layers that presumably enforce the `IsAuthorizedUser` flag and deny-self-registration checks.*

## Architecture diagram
The following diagram shows the high-level component grouping within the library and its position relative to consuming and Oracle persistence layers.

```mermaid
flowchart TD
    Caller[Consuming application / BOF layer] --> User[clsUser / clsUserCollection]
    Caller --> Auditor[clsAuditor / clsAuditorZipCode / clsAuditAssignmentOverride]
    Caller --> AccessGroup[clsUserAccessGroup]
    User --> UserType[clsUserType]
    User --> SecQ[clsUserSecurityQuestion]
    User --> DenyReg[clsUserDenySelfRegistration]
    User --> ZipCode[clsZipCode]
    Framework[SAIF.BOF.Framework<br>clsBusinessBase / clsBusinessCollectionBase] --> User
    Framework --> Auditor
    Framework --> AccessGroup
    User --> DB[(Oracle database)]
    Auditor --> DB
    AccessGroup --> DB
```

## Sequence diagram
The following diagram shows the primary retrieve/persist sequence for an external user record via the BOF lifecycle.

```mermaid
sequenceDiagram
    participant Caller
    participant clsUser
    participant Criteria as clsUser.Criteria (IBusinessCriteria)
    participant Oracle as Oracle database
    Caller->>clsUser: Retrieve / Save
    clsUser->>Criteria: BeforeRetrieve / BeforeInsert / BeforeUpdate
    Criteria-->>clsUser: RetrieveSQL / InsertSQL / UpdateSQL
    clsUser->>Oracle: Execute SQL (bind variables)
    Oracle-->>clsUser: Result set / row count
    clsUser-->>Caller: Populated object / persisted state
```

## Design constraints
- Targets Oracle exclusively; no other database provider evidence was found.*
- No security/authorization framework (`ISecurityManager`, `PrincipalContext`, AD) interaction was detected; the `IsAuthorizedUser` flag is a persisted data property only, not an enforcement mechanism — enforcement is presumed to occur in a calling application layer.*
- No configuration framework (`IEnvironmentService`, `ConfigurationManager.AppSettings`, `DbConnectionManager`) interaction was detected.
- Dependencies are resolved entirely as NuGet package references per the `.nuspec`; no local `<ProjectReference>`s were found.*

## 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)
- [Configuration](configuration.md)

> **Note:** Statements marked with `*` were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts.

## Sources
- `Business\SAIF.Business.External.Users\clsUser.vb`
- `Business\SAIF.Business.External.Users\clsAuditor.vb`
- `Business\SAIF.Business.External.Users\clsAuditorCollection.vb`
- `Business\SAIF.Business.External.Users\clsAuditAssignmentOverride.vb`
- `Business\SAIF.Business.External.Users\clsAuditorZipCode.vb`
- `Business\SAIF.Business.External.Users\clsAuditorZipCodeCollection.vb`
- `Business\SAIF.Business.External.Users\clsUserAccessGroup.vb`
- `Business\SAIF.Business.External.Users\clsUserDenySelfRegistration.vb`
- `Business\SAIF.Business.External.Users\clsUserSecurityQuestion.vb`
- `Business\SAIF.Business.External.Users\clsUserType.vb`
- `Business\SAIF.Business.External.Users\clsZipCode.vb`
- `Business\SAIF.Business.External.Users\mdlAuditor.vb`
- `Business\SAIF.Business.External.Users\mdlCodeMaps.vb`
- `Business\SAIF.Business.External.Users\mdlExtensions.vb`
- `Business\SAIF.Business.External.Users\mdlGroupAssociation.vb`
- `Business\SAIF.Business.External.Users\SAIF.BOF.Business.External.Users.nuspec`