---
title: "SAIF.Business.Menu architecture"
summary: "Architectural responsibilities, boundaries, and interaction patterns."
status: draft
owner: SAIF documentation team
last_reviewed: 2026-08-17
library: SAIF.Business.Menu
reference_type: package
---

# SAIF.Business.Menu architecture

`SAIF.Business.Menu` is a mid-tier SAIF BOF business layer that models the application's navigation menu and computes which menu items are authorized for display through a database-table-driven security-group model. It performs no HTTP, UI, or session handling; callers supply `IDataPortalInfo`, and the library returns persisted business objects or authorized-menu projections.

## Responsibilities
- Define and persist application codes, menu categories, menu pages, and menu items.
- Persist the item-to-group and user-to-group rows that drive authorization.
- Build the authorized menu as the union of group-authorized items, public items, and active favorites.
- Cascade menu-item validation and save behavior to the child security-group collection.

## Component boundaries
- **Reference data**: `clsApplicationCode` and `clsMenuCategoryCode`.
- **Menu structure**: `clsMenuPage` and `clsMenuItem`.
- **Authorization data**: `clsMenuSecurity` and `clsMenuSecurityUser`.
- **Authorized-menu projection**: `clsMenuAuthorizedItemCollection`.
- **Favorites**: `clsMenuFavorite`.
- **Utility support**: `mdlUtilities.AddToList`.

## Interaction model
- Callers request `GetMenuAuthorizedItems` or `GetAllMenuAuthorizedItems`.
- The data-portal lifecycle selects the appropriate Oracle SQL.
- The returned rowset is materialized into `clsMenuAuthorizedItem` objects.
- Callers use `Favorites`, `ApplicationItems`, `AppItemsByCategory`, and `SecuredAppItems` without issuing new authorization SQL.
- Administrative callers use the entity and collection classes directly to maintain lookup, page, item, favorite, and membership rows.

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

```mermaid
flowchart TD
    Caller[Calling layer] --> Auth[clsMenuAuthorizedItemCollection]
    Auth --> DB[(Oracle menu tables)]
    Auth --> Views[In-memory filtered views]
    Admin[Administrative caller] --> Item[clsMenuItem]
    Item --> Sec[clsMenuSecurityCollection]
    Sec --> DB
    Admin --> Ref[Lookup and page classes]
    Ref --> DB
```

## Sequence diagram
The following diagram shows the primary request/response sequence for building a user's authorized menu.

```mermaid
sequenceDiagram
    participant Caller
    participant Menu as clsMenuAuthorizedItemCollection
    participant Portal as IDataPortalInfo
    participant Oracle as Oracle
    Caller->>Menu: GetMenuAuthorizedItems(dataPortal, menuUser)
    Menu->>Portal: BeforeRetrieve
    Portal->>Oracle: Execute authorized-menu SQL
    Oracle-->>Portal: Result rows
    Portal-->>Menu: AfterRetrieve loads rows
    Menu-->>Caller: Authorized menu collection
```

## Design constraints
- Authorization is enforced by Oracle SQL over `MENU_SECURITY` and `MENU_SECURITY_USER`, not by AD-resource lookups.
- Items with no `MENU_SECURITY` row are public by default through [BR-MENU-002](business-rules.md#br-menu-002-unsecured-menu-items-are-visible-by-default).
- Group matching is case-insensitive through [BR-MENU-003](business-rules.md#br-menu-003-security-group-matching-is-case-insensitive).
- Favorites participate in menu composition through [BR-MENU-004](business-rules.md#br-menu-004-favorites-are-always-included-and-ordered).
- Menu-item validation and dirty tracking cascade to child security groups through [BR-MENU-005](business-rules.md#br-menu-005-menu-item-validity-and-dirtiness-cascade-to-security-groups).
- The library targets Oracle-only SQL syntax (`NEXTVAL`, `SYSDATE`, `NVL`, `:ParamName`).

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

## Sources
- `SAIF.Business.Menu\clsApplicationCode.vb`
- `SAIF.Business.Menu\clsMenuAuthorizedItemCollection.vb`
- `SAIF.Business.Menu\clsMenuFavorite.vb`
- `SAIF.Business.Menu\clsMenuItem.vb`
- `SAIF.Business.Menu\clsMenuPage.vb`
- `SAIF.Business.Menu\clsMenuSecurity.vb`
- `SAIF.Business.Menu\clsMenuSecurityUser.vb`
- `SAIF.Business.Menu\mdlUtilities.vb`
- `SAIF.Business.Menu\\SAIF.Business.Menu.vbproj`