Navigation & Routing Contract

1. Purpose

The content contract documents the MenuItem data shape, including its Path field, but stops short of explaining what Path actually does at runtime. This doc is that missing piece: how a MenuItem selected in the UI turns into a real screen — the Shell route table, how Path carries a query string for special targets, and how glyph data rides along into the destination page.

2. Two routing systems — do not confuse them

This app has two independent, parallel navigation systems. A doc or an engineer reasoning about "routing" needs to say which one they mean:

The two systems meet at AuthenticatedWebViewPage (AB#2591, replaced the legacy WebViewPage — a Shell-routed native page whose content is a native AutoLoginWebViewContentView/WebView, not a BlazorWebView), and at BlazorHomePage. A Shell GoToAsync can land you on a page that itself hosts Blazor routing underneath — but a MenuItem.Path targets a Shell route, never a Blazor route directly.

3. Shell route table

Every Shell-navigable page is registered once, by convention with nameof(PageType) as the route name, in the AppShell constructor:

public AppShell()
{
    InitializeComponent();
    ...
    Routing.RegisterRoute(nameof(MemberResourcesPage), typeof(MemberResourcesPage));
    Routing.RegisterRoute(nameof(AuthenticatedWebViewPage), typeof(AuthenticatedWebViewPage));
    Routing.RegisterRoute(nameof(BlazorHomePage), typeof(BlazorHomePage));
    // ...~45 registrations total
}

This table is the source of truth for valid route names — a MenuItem.Path (or any GoToAsync call) that doesn't match a registered name, or the special-cased targets in §5, will fail to navigate. It is intentionally not reproduced in full here (it would drift); read it directly at ALPAMobile/AppShell.xaml.cs.

This file (along with the rest of DotNet10's navigation/routing bug-fix history) is audited each sprint against imp/blazor-hybrid as part of the standing bug-fix rollup process — see WI 2238 for the current triage state and porting status of any open items.

The DI-registered implementation behind every registered route is ShellNavigationService (ALPAMobile/Services/Navigation/ShellNavigationService.cs), which implements INavigationService (ALPAMobile.Application/Abstractions/Navigation/INavigationService.cs). It also owns the BUG-2073 safe-lookup workaround (Shell.Current throws InvalidOperationException during startup before Shell attaches to a Window; the service resolves the Shell instance via Application.Current.Windows instead).

4. MenuItem.Path → navigation: standard vs. legacy pattern

MenuItem.Path (see content contract §3) is a route string that ultimately reaches Shell.Current.GoToAsync — but how it gets there matters. It is consumed from several native page ViewModels, each iterating a MenuItem's children and wiring a tap command, and every one of them already has INavigationService injected in its constructor — yet most still call Shell.Current.GoToAsync directly instead of using it:

Why this matters — it already caused a crash (DOTNET-MAUI-3BK)

HomePageViewModel.cs carries this comment at its MenuItem tap-command call site, explaining why it was moved off the direct-call pattern:

// DOTNET-MAUI-3BK: Use BasePageViewModel.GoToAsync instead of Shell.Current.GoToAsync
// directly — routes are API-driven and an invalid path triggers CannotCreateAbstractClasses
// inside ActivatorUtilities.CreateInstance, crashing the app. The base helper catches and
// reports the failure while logging the route value for Sentry breadcrumb diagnosis.
await GoToAsync(item.Path);

MenuItem.Path is API-driven content, not a compile-time-checked constant — a bad or stale value from the backend is entirely possible, and a direct Shell.Current.GoToAsync call has no guard against it. ShellNavigationService.GoToAsync wraps the call in try/catch, logs the route, and reports the exception (ex.Report()) instead of letting it crash the app.

5. Query properties — Path as a URI, not just a route name

Path is not always a bare route name. For two targets it is a full route?query=string, intercepted in AppShell.OnNavigating (ALPAMobile/AppShell.xaml.cs) before Shell would otherwise resolve it as a registered route. This is the real query-property mechanism tied to MenuItem — it is unrelated to Blazor's SupplyParameterFromQuery (§2).

Both cases are parsed the same way: the target's OriginalString is rebuilt into an absolute https://alpa.org/<target> URI purely so System.Web.HttpUtility.ParseQueryString can extract the query dictionary — the constructed alpa.org URL is never actually requested.

6. Glyph propagation into the destination page

Glyphs are resolved twice, not once:

1. For the menu tile itself — MenuItem.Glyph + GlyphFontFamily are set on MenuItemViewModel, which resolves them via GetImageFromGlyph() → Helpers.GlyphHelper.GetGlyph() against the MaterialIcons or FontAwesome font-constant classes, producing a FontImageSource (size 50, color #053C89).
2. For a WebViewPage destination — the same glyph, re-encoded as the ImageGlyph / ImageGlyphFontFamily query params (§5), is passed into the WebViewPageViewModelFactory. Since AB#2591, this no longer renders anywhere: the destination is AuthenticatedWebViewPage, whose header has no glyph slot (the legacy WebViewPage's blue title-banner did). The propagation still happens — the query param still reaches the ViewModel — it's just visually inert now.

Both paths bottom out in the same GlyphHelper + font-constants lookup — there is one glyph resolution mechanism, invoked from two call sites (one of which is now a no-op past the ViewModel). See naming decisions D3 for why glyph is modeled as data on the item rather than a separate icon-carrying type.

7. Blazor migration parity gap

The pattern in §4 is fully implemented in the legacy native XAML layer — e.g. MemberResourcesPage.xaml + MemberResourcesPageViewModel.cs, still DI-registered (PresentationServiceCollectionExtensions.cs) and Shell-route-registered. The newer Blazor counterpart, Components/Pages/MemberResourcesPage.razor, has not reached parity: it hardcodes Link = "/member-resources" (a self-link) for every tile instead of consuming MenuItem.Path. Source comments attribute this to Blazor→native navigation being deferred (DQ-19 / #2191) — i.e. it's a known, intentional gap during migration, not a bug, but it is not yet reflected in pages/member-resources.html, which currently implies the Blazor page already routes through MenuItem.

8. Open confirms & action items

• Fix the 5 legacy Shell.Current.GoToAsync call sites (§4) — highest priority, lowest effort: MemberResourcesPageViewModel, KCMHomePageViewModel, MyPilotGroupPageViewModel (×2), JumpseatInfoPageViewModel, AppShellViewModel (×3). Each already has INavigationService injected; this closes the same crash exposure DOTNET-MAUI-3BK fixed in HomePageViewModel, and moves the app closer to WI-2085 (service-locator removal).
• Blazor→native Shell bridge (DQ-19 / #2191) — how (or whether) a Blazor page will call through to INavigationService/Shell.Current.GoToAsync for MenuItem.Path targets once the migration reaches that screen.
• Query-param contract strength — whether the hand-typed query-string convention in §5 gets formalized (typed DTO, shared constant names) before more screens depend on it.
• Glyph catalog — no enumerated list of valid glyph names exists; needed once the new component-spec system needs to reference specific glyphs (blocked on DQ-17).
• pages/member-resources.html accuracy — should be corrected to describe the current self-link behavior, or updated once the Blazor page is wired to MenuItem.Path.