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

# SAIF.Business.Menu architecture

`SAIF.Business.Menu` is a SAIF BOF (Business Object Framework) business library that models the SAIF web menu system: applications, menu categories, menu pages, menu items, per-item security groups, group memberships, and per-user favorites. Its central type, `clsMenuAuthorizedItemCollection`, resolves the set of menu items a specific user may reach by combining group-granted items, unsecured items, and the user's favorites into a single read-only projection over Oracle — this collection is the data behind the page-level authorization check performed by [SAIF.Presentation.Web.MVC](../saif-presentation-web-mvc/overview.md).

## Responsibilities
- Model the five-level menu domain: applications own pages; pages are placed into categories as items; items are optionally secured by groups; users belong to groups; users may favorite items.
- Resolve, per user, the effective set of reachable pages via a three-branch Oracle `UNION`: group-granted items, unsecured (no-grant) items, and the user's favorites (`clsMenuAuthorizedItemCollection.GetMenuAuthorizedItems`).
- Provide full CRUD administration of applications, categories, pages, items, security grants, group memberships, and favorites through standard BOF business objects.
- Expose per-item toolbar capability flags (print, download, help, save, insert, delete, save-preferences) consumed by presentation-layer menu rendering.

## Component boundaries
- **Maintenance objects** (`clsMenuPage`, `clsMenuItem`, `clsMenuSecurity`, `clsMenuSecurityUser`, `clsMenuFavorite`, `clsApplicationCode`, `clsMenuCategoryCode`, each inheriting `clsBusinessBase`, plus their `clsBusinessCollection(Of T)` collections): implement full or partial CRUD and are the write side of menu administration.
- **`clsMenuAuthorizedItem` / `clsMenuAuthorizedItemCollection`**: the read side — a denormalized, per-user projection with no CRUD of its own (all five `IBusinessCriteria` SQL properties on the item throw `ApplicationException`). This is the type consumed by the presentation layer for authorization and menu rendering.
- **`mdlUtilities`**: the only cross-cutting helper module, moving LINQ-filtered sequences back into strongly-typed BOF collections via the framework's `PerformForAll` extension.

## Interaction model
- All persistence follows the BOF data-portal pattern (`IBusinessCriteria`, `Before*`/`After*` lifecycle hooks); the library never opens a database connection itself — callers supply an `IDataPortalInfo` that already carries connection/portal configuration.
- `clsMenuItem.MenuPage`, `clsMenuItem.MenuCategory`, `clsMenuItem.SecurityGroups`, `clsMenuPage.Application`, and `clsMenuFavorite.MenuItem` each lazily fetch their related object on first access through a separate data-portal round trip, producing an N+1 access pattern when traversing a collection of items.*
- `clsMenuItem` treats `SecurityGroups` (`clsMenuSecurityCollection`) as a child collection: its `IsValid`/`IsDirty` fold in the child state, and `SaveMe` cascades with `SaveChildObject` after saving the parent.
- Downstream, [SAIF.Presentation.Web.MVC](../saif-presentation-web-mvc/overview.md)'s `NavigationContext` is the primary consumer within the packaged set, calling `GetMenuAuthorizedItems` and caching the result in session for per-request page authorization; `SAIF.Presentation.Web.Controls.V2.Menu` is the likely UI consumer of the toolbar capability flags.*

## Architecture diagram
The following diagram shows the five-level menu domain model and its relationships.

```mermaid
flowchart LR
	APP["clsApplicationCode<br>BUSONLINE_APPS_CODE"] --> PAGE["clsMenuPage<br>MENU_PAGE"]
	CAT["clsMenuCategoryCode<br>MENU_CATEGORY_CODE"] --> ITEM["clsMenuItem<br>MENU_ITEM"]
	PAGE --> ITEM
	ITEM --> SEC["clsMenuSecurity<br>MENU_SECURITY"]
	SEC --> USR["clsMenuSecurityUser<br>MENU_SECURITY_USER"]
	ITEM --> FAV["clsMenuFavorite<br>MENU_FAVORITE"]
	ITEM --> AUTH["clsMenuAuthorizedItem<br>query projection"]
	SEC --> AUTH
	FAV --> AUTH
```

## Sequence diagram
The following diagram shows the data-access flow for resolving a user's authorized menu set.

```mermaid
sequenceDiagram
	participant C as Caller (e.g. NavigationContext)
	participant F as Shared factory (GetMenuAuthorizedItems)
	participant DP as IDataPortalInfo.DataAccessLayer
	participant BO as Collection Before/AfterRetrieve
	participant DB as Oracle
	C->>F: GetMenuAuthorizedItems(dpi, menuUser)
	F->>DP: RetrieveObject(New Criteria(dpi, menuUser))
	DP->>BO: BeforeRetrieve(portalRequest)
	BO->>BO: choose RetrieveSQL vs RetrieveAllSQL, AddParm MenuUser
	DP->>DB: execute SQL
	DB-->>DP: IDataReader
	DP->>BO: AfterRetrieve(portalRequest)
	BO->>BO: loop Read, Load each clsMenuAuthorizedItem, MarkOld
	BO-->>C: populated collection
```

## Design constraints
- Every business object and collection in this library inherits from a `SAIF.Framework` base type (`clsBusinessBase` / `clsBusinessCollection(Of T)`), delivered by the `SAIF.BOF.Framework` package (see [Dependencies](dependencies.md)).
- Database access is Oracle-only, using `:`-bind variables, `SEQ.NEXTVAL FROM DUAL`, `SYSDATE`, and `NVL`; no stored procedures are called anywhere in this library.
- The library performs authorization resolution, not denial — the access predicate lives in the retrieval SQL `WHERE`/`UNION` clauses; enforcement (redirect/deny) is the responsibility of the consuming presentation layer.
- Items with no security grant at all are open to every user (deny-by-default except unsecured), and a favorited item remains reachable via the favorites branch even after its group grant is later removed, until the favorite itself is deactivated.*
- This library reads no configuration of its own; database connectivity is entirely externalized through the caller-supplied `IDataPortalInfo`.

## 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)
- [Security and authorization](security-authorization.md)
- [API reference](api/index.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
- SAIF.Business.Menu/SAIF.Business.Menu.vbproj
- SAIF.Business.Menu/clsMenuAuthorizedItemCollection.vb
- SAIF.Business.Menu/clsMenuItem.vb
- SAIF.Business.Menu/clsMenuPage.vb
- SAIF.Business.Menu/clsMenuFavorite.vb
- SAIF.Business.Menu/mdlUtilities.vb
- SAIF.Presentation.Web.MVC/NavigationContext.vb