ALPA Mobile — Backend API Mapping Report

Why: Figma design shows "Welcome Captain Johnson". Rank is a first-class design element, not metadata.

Change: Add Rank (string, nullable) to the UserInfo auth/profile API response.

Possible values: "Captain", "First Officer", "Second Officer", null (omit greeting prefix if absent).

Impact: Auth service only. The client reads UserInfo.Rank when composing the welcome card (the Pilot Card domain control, which maps onto a Card). If null, the greeting falls back to "Welcome {FirstName} {LastName}".

Mobile model: UserInfo.cs — add public string? Rank { get; set; }

Why: CardTextViewModel (backed by MenuItem) needs a description/subtitle field for the "Eyebrows" and "Simple" variants. card-sm itself doesn't show description, but TextCard does.

Change: Add description (string, nullable) to the MenuItem API response.

Impact: Menu API endpoint only. No schema-breaking change — nullable field, existing consumers unaffected.

Mobile model: MenuItem.cs — add public string Description { get; set; } = string.Empty;

Delivered 2026-07-08: MobileMenu.ApiClient 1.0.7 — GetItemTypesAsync/GetFavoritesAsync/AddFavoriteAsync/RemoveFavoriteAsync. Mobile side wired the same day (WI 2182): IFavoritesQueries port, the Favorites screen (heterogeneous card-lg/card-sm rendering + remove + empty state), heart-toggle across the card library (D31), and the Off the Radar item-unavailable fallback.

⚠ Document imagery gap (found in live validation 2026-07-09): every document in the live GET /v2/api/doc/getdocuments response carries image: null (42/42 sampled) — the card-lg document carousel has no real cover art to render and falls back to placeholder imagery. The Home feed design (card-lg) presumes per-document images; raise with backend alongside the AB#2133 dynamic-feed work so magazine covers/article art ship with the content.

⚠ Gateway rollout pending (found in live validation 2026-07-09): the delivered endpoints are not reachable on the production gateway — GET https://gateway.alpa.org/v2/api/mobilecontent/favorites, …/itemtypes, and POST all return 404 (verified with a valid member bearer token). This affects the whole MobileMenu.ApiClient surface: …/mobilecontent/menuitems/getallforuser 404s too (the app falls back to its offline menu list). The mobile slice is validated against the mock router; live end-to-end (including the dead-favorite → Off the Radar flow, which needs a server-seeded favorite) is blocked until the backend deploys the service behind the gateway. Follow up with the backend team on rollout timing.

Why (historical): The favorite (heart) affordance appears across many controls — MEC card-btn, card-md and media card-lg, FAQ / "Did You Know", and others. On Home it is hidden (decision D7); later screens show it. This was the single highest-leverage backend gap surfaced by the screen-set analysis — solved once, as a shared capability, not per control.

Delivered contract:

• Toggle — POST /api/mobilecontent/favorites { itemTypeId, itemId, sortOrder, title } and DELETE /api/mobilecontent/favorites/{itemTypeId}/{itemId}.
• Read — GET /api/mobilecontent/favorites → id/userId/itemTypeId/itemTypeDescription/itemId/sortOrder/title + audit fields (ID-only-ish, not a hydrated payload — see below). GET /api/mobilecontent/favorites/itemtypes → the known item types.
• Item identity — confirmed, exactly 3 types: 1=Menu Item, 2=Document Item, 3=Notification Center Message. No separate "button" type — card-btn vs card-sm is a presentation choice on Menu Item favorites, not data-driven.

Impact: New member-scoped endpoints, delivered. Each list reconciles its items against the member's favorites set client-side; the affected item view-models expose IsFavorite + a toggle command. The individual content models needed no change (they already carry stable IDs).

Mobile model: IFavoritesQueries (GetFavoritesAsync() / AddFavoriteAsync(Favorite) / RemoveFavoriteAsync(itemTypeId, itemId)) + IsFavorite/ShowFavorite/OnFavoriteToggle parameters on Card/CardSmall/HeroCard/ButtonCard (D31). IsFavorite now sources from the live API, not local storage.

Dedicated consumer: the Favorites screen (5287:15227, see favorites-screen-data-gap.html) renders the member's favorites by native control — card-lg / card-sm; Notification favorites render as a title-only row (no card component for that type). The condensed 5287:15454 list variant was not built this pass. Design point resolved: the read returns (itemType, itemId) + title only, not a hydrated payload — the client hydrates from IDocumentsQueries/IMenuQueries by itemId. sortOrder exists as the ordering field.

Status (2026-06-24): This requirement has been abandoned. The "Did You Know?" feature is no longer planned. No endpoint will be built; remove from all planning.

Why (historical): The "Did You Know?" screen was a new feature — it does not exist in the app today (no UI, no endpoint, not hard-coded). Unlike Changes 1–3 (small additions to existing models/capabilities), this is a net-new backend build, so it is called out separately.

Change: Add a new endpoint returning the DYK/FAQ feed — a list of items carrying a date, headline, and body/answer (plus a nav target). The shape is already modeled by the unwired KCMFAQItem { Question, Answer } and KCMAlertItem { headline, story, publishDate } classes in KCM.cs — a reasonable contract starting point.

Impact: New endpoint + content store. Blocking — the "Did You Know?" feature cannot be built until this endpoint exists. The client builds the list (listy) against it. Favorites on these rows reuse the shared capability from Change 3.

Mobile model: a DYK/FAQ item model (Q/A + date/headline) and a service method (e.g. GetDidYouKnowAsync()); the KCMFAQItem/KCMAlertItem shapes can seed it.

Why: Figma's banner component (D43, PromoBanner) is a solid-navy-fill (#05273e) card with a title ("Survey Now Open"), a subtitle/expiry line ("Closes June 10 at 11:59PM PT"), a small logo image, and a dismiss (X) control — four distinct pieces of structured content, not one flat image. Today's implementation renders this as a single full-bleed image (FeaturedImageLink) with the title/subtitle text baked into the image pixels — confirmed 2026-07-06 against the live app: it's just an image plus a click-through target, no separate text fields.

Domain source identified: this is not a new Dynamic Feed ItemDto or a dedicated announcements service (the two candidates D43 originally floated) — it's the richer version of the existing, already-shipped PageBanner model (ALPAMobile.Domain/Data/Models/PageBanner.cs), fetched via GET /api/pagebanner/list (IRestService.GetPageBannersAsync → RestService.cs:1194) and resolved per page in BannerPageViewModel via PageBanner.GetBannerForPage(PageName, banners). This is a generic per-page banner slot already used by ~20+ pages (Home, Jumpseat, Known Crewmember, Member Resources, MEC/LEC, Flight Search, Settings, Notification Center, Advocacy — see the Key_*PageBanner constants in PageBanner.cs), not a Home-only or one-off feature. That also resolves D43's "is this even a library component" question per D40: it's a recurring, reusable pattern, not static one-off content — it correctly stays a catalogued domain control.

Change: Add to the PageBanner API response:

• Title (string, nullable) — headline text, e.g. "Survey Now Open".
• Subtitle (string, nullable) — secondary line, e.g. "Closes June 10 at 11:59PM PT". Open sub-question: a pre-formatted display string from the backend, or a structured ExpiresAt (DateTimeOffset) the client formats itself (better for timezone/localization consistency, matches the pattern already used elsewhere in FTDT)? Needs a decision before implementation.
• LogoImageLink (string, nullable) — the small logo asset shown in the Figma design. Since the design's background is a solid fill (not a photo), this is likely a rename/repurpose of the existing FeaturedImageLink rather than an additional field — needs a decision on whether to reuse or add a second image field.
• Dismiss capability — resolved (2026-07-06), client-only, no API change: default behavior is per-session — dismissal is held in-memory only, so if the app restarts and /api/pagebanner/list still returns the banner as active, it shows again. If a given banner ever needs a true "dismiss once, never show again" behavior, that's a per-device local-storage flag (the app's existing local Settings/Preferences mechanism), keyed by banner Id — not a member-scoped API call. Neither mode touches the backend; no favorites-style storage/endpoint is needed here.

Impact: Title/Subtitle/LogoImageLink are additive/nullable — non-breaking, PageBanner API only, benefits every page's banner slot (not just Home). Dismiss is entirely client-side (session in-memory, or per-device local storage for permanent dismiss) — no backend involvement.

Mobile model: PageBanner.cs — add Title, Subtitle (or ExpiresAt), LogoImageLink. Navigation (Path, DocType, DisplayMode, PageBannerNavigationExtensions.PageBannerClicked) is unaffected — click-through behavior stays as-is. Dismiss state is tracked client-side only: per-session in-memory by default, or a per-device local-storage flag keyed by Id if permanent dismiss is ever needed for a given banner — no new model field required on PageBanner itself.

Proposed diff — ALPAMobile.Domain/Data/Models/PageBanner.cs (mobile-side model; the backend response shape should mirror this 1:1):

 public class PageBanner
 {
     public const string Key_HomePageBanner = "Home Page";
     // ...existing Key_*PageBanner constants unchanged (~30 more)...
 
     public PageBanner() { }
 
     public int Id { get; set; }
     public string Page { get; set; } = string.Empty;
     public string ContentType { get; set; } = string.Empty;
     public string DocType { get; set; } = string.Empty;
     public string Source { get; set; } = string.Empty;
     public string FileId { get; set; } = string.Empty;
     public string Path { get; set; } = string.Empty;
     public string FeaturedImageLink { get; set; } = string.Empty;
     public string DisplayMode { get; set; } = string.Empty;
+
+    // -- New fields requested for the PromoBanner design (D43 / Change 5) --
+    public string? Title { get; set; }
+    public string? Subtitle { get; set; }
+    // Alternative to Subtitle -- pick ONE, do not add both:
+    // public DateTimeOffset? ExpiresAt { get; set; }
+    public string? LogoImageLink { get; set; }
 
     public static PageBanner? GetBannerForPage(string page, ObservableCollection<PageBanner> banners)
     { /* unchanged */ }
 }

Sample GET /api/pagebanner/list response — one entry, before/after (all three new fields nullable/omittable, so existing rows for the other ~20 pages need no changes):

// Before (today)
{
  "id": 42,
  "page": "Home Page",
  "contentType": "webpage",
  "docType": "weblink",
  "source": "",
  "fileId": "",
  "path": "https://ual.alpa.org/upa27-survey",
  "featuredImageLink": "https://cdn.alpa.org/banners/upa27-survey-full.png",
  "displayMode": "Normal"
}

// After (Change 5)
{
  "id": 42,
  "page": "Home Page",
  "contentType": "webpage",
  "docType": "weblink",
  "source": "",
  "fileId": "",
  "path": "https://ual.alpa.org/upa27-survey",
  "featuredImageLink": "https://cdn.alpa.org/banners/upa27-survey-full.png",
  "displayMode": "Normal",
  "title": "Survey Now Open",
  "subtitle": "Closes June 10 at 11:59PM PT",
  "logoImageLink": "https://cdn.alpa.org/logos/upa27-logo.png"
}

featuredImageLink is left in place deliberately — it's still used as-is by every other page's banner (a full-bleed image, no separate text fields needed there). logoImageLink is additive so those existing banners keep working unchanged; only rows that want the richer PromoBanner treatment populate the three new fields.

Handoff package (canonical — this doc is the handoff, 2026-07-07)

Status: ON HOLD — pending design-intent confirmation (DQ-26, 2026-07-07): if a supplied flat image per campaign is adequate, Change 5 is withdrawn; if structured content is required, Change 5 proceeds as documented. When it proceeds, this section is the handoff; no separate email/Teams send (decision 2026-07-07) — the backend team is pointed here via the AB#1821 work item (see the Backend Handoff Tracker). The cover text below is the handoff summary; the technical payload is the Proposed diff and Sample response blocks above — reference those verbatim rather than forking a copy.

Subject: PageBanner API — request for 3 additive fields (mobile UI Refresh, AB#1821)

Ask: add Title, Subtitle, LogoImageLink (all nullable) to the PageBanner response from GET /api/pagebanner/list. The UI Refresh banner design (Figma PromoBanner, decision D43) is structured content — a solid-navy card with a headline ("Survey Now Open"), a secondary/expiry line ("Closes June 10 at 11:59PM PT"), a small logo, and a dismiss control. Today the same content ships as one full-bleed image (FeaturedImageLink) with the text baked into the pixels, which blocks the new design, accessibility, and text scaling.

Non-breaking: all three fields are additive and nullable. Existing banner rows for the other ~20 pages need no changes and keep rendering via FeaturedImageLink exactly as today. Dismiss behavior is entirely client-side — no API change, no per-member storage.

Technical payload: the proposed C# model fields are the Proposed diff block above (the backend response shape should mirror ALPAMobile.Domain/Data/Models/PageBanner.cs 1:1), and the before/after JSON is the Sample GET /api/pagebanner/list response block above.

Two decisions we'd like backend input on before implementation:

1. Subtitle (pre-formatted display string) vs ExpiresAt (DateTimeOffset the client formats)? We lean ExpiresAt for timezone/localization consistency — it matches the pattern already used elsewhere in the app — but a display string is fine if banner copy won't always be an expiry.
2. LogoImageLink as a new field vs repurposing FeaturedImageLink? The new design's background is a solid fill, not a photo, so the row could reuse the existing field for the logo — but a separate field keeps existing full-bleed banners untouched. We lean separate/additive (as drafted).

The package closes by pointing the backend team back to this section for the full analysis and domain-source rationale (branch imp/blazor-hybrid).