---
title: SAIF.Application architecture
summary: Architectural responsibilities, boundaries, and interaction patterns for SAIF.Application.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-07-24
library: SAIF.Application
reference_type: package
---

# SAIF.Application architecture

`SAIF.Application` is an abstract application-manager library positioned between consuming applications or services and BOF business objects. Its architecture centers on manager base classes, keyed data-portal registration, cached authorization checks, and message/result helpers rather than direct business logic or SQL execution.

## Responsibilities
- Standardize application-manager lifecycle hooks for initialization, context changes, validation, retrieval, writing, and transaction boundaries.
- Centralize application-level accessibility state through `AppSecurityRole` and the `IsAccessible` / `IsUpdateable` / `IsViewOnly` / `IsRestricted` accessors.
- Provide keyed SQL Server and Oracle `IDataPortalInfo` registration through `ApplicationDataAccess`.
- Encapsulate reusable access-check caching through `UserAccess`.
- Support service-hosted manager implementations through `clsServiceAppManagerBase`, `ServiceMessage`, and `ServiceResponse`.

## Component boundaries
- `AppManagerBase`: Abstract base for classic application managers; owns lifecycle hooks, role-state accessors, message accumulation, and access to `ApplicationDataAccess`.
- `ApplicationDataAccess`: Data-portal factory and registry; creates `IDataPortalInfo` instances but does not issue SQL statements directly.
- `UserAccess`: Standalone authorization helper that delegates resource checks to `clsSecurityPrincipal` and caches results per resource name.
- `MessageFormatting`: Static helper for turning message collections into display strings.
- `clsServiceAppManagerBase`: Service-oriented base type for managers that operate with a single injected `IDataPortalInfo` instead of a keyed portal library.
- `ServiceMessage` / `ServiceResponse`: Result-object pattern for service consumers that need categorized response messages.

## Interaction model
- Consuming code initializes an `AppManagerBase` implementation, which delegates setup work to override hooks such as `OnInitialize()` and `OnCreateDataLayer()`.
- The manager uses `ApplicationDataAccess` to register one or more SQL Server or Oracle portals keyed for later retrieval.
- Security evaluation flows through subclass logic that assigns a single application role and can call `UserAccess.HasAccess(...)` when resource-based checks are needed.
- Classic managers expose accumulated message text directly, while service-based managers package outcomes through `ServiceResponse` and `ServiceMessage`.

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

```mermaid
flowchart TD
    Consumer[Consuming application or service] --> AppManager[AppManagerBase]
    Consumer --> ServiceManager[clsServiceAppManagerBase]
    AppManager --> DataAccess[ApplicationDataAccess]
    AppManager --> Access[UserAccess]
    DataAccess --> Portal[IDataPortalInfo]
    ServiceManager --> Portal
    Access --> Principal[clsSecurityPrincipal]
    Portal --> BusinessObjects[BOF business objects]
```

## Sequence diagram
The following diagram shows a typical application-manager sequence.

```mermaid
sequenceDiagram
    participant Consumer
    participant Manager as AppManagerBase
    participant Data as ApplicationDataAccess
    participant Access as UserAccess
    participant Principal as clsSecurityPrincipal
    Consumer->>Manager: Initialize()
    Manager->>Data: CreateSQLServerPortal(...) / CreateOraclePortal(...)
    Data-->>Manager: IDataPortalInfo registered
    Consumer->>Manager: OnCheckSecurity()
    Manager->>Access: HasAccess(resourceName)
    Access->>Principal: IsAuthorized(resourceName)
    Principal-->>Access: Boolean result
    Access-->>Manager: Cached access result
    Manager-->>Consumer: Retrieve() / Write() enabled by role
```

## Design constraints
- The library defines contracts and supporting infrastructure; consuming applications implement the concrete lifecycle behavior through override hooks.
- `ApplicationDataAccess` manages connectivity abstractions only; actual SQL and table interactions live in downstream business-object libraries.
- Role gating is intentionally centralized to a single effective `AppSecurityRole`, aligning the class behavior described by [BR-001](business-rules.md#br-001-single-effective-application-security-role).
- Message aggregation behavior follows the duplicate-suppression rule documented in [BR-002](business-rules.md#br-002-duplicate-message-text-is-suppressed).
- Authorization reuse relies on the per-resource cache documented in [BR-003](business-rules.md#br-003-authorization-results-are-cached-per-resource-name).

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

## Sources
- `Application\SAIF.Application\AppManagerBase.vb`
- `Application\SAIF.Application\ApplicationDataAccess.vb`
- `Application\SAIF.Application\MessageFormatting.vb`
- `Application\SAIF.Application\UserAccess.vb`
- `Application\SAIF.Application\Service Based\clsServiceAppManagerBase.vb`
- `Application\SAIF.Application\Service Based\ServiceMessage.vb`
- `Application\SAIF.Application\Service Based\ServiceResponse.vb`
- `Application\SAIF.Application\SAIF.BOF.Application.vbproj`