Technical reference. For task-based help, see the corresponding user guide.

Documentation status: complete for the current implementation

Reviewed: 2026-07-21

Primary users: family members and assigned coaches with family-write permission

Surfaces: mobile web app, native wrapper and platform API

Allergy Ladders provide a baby-scoped plan for recording staged food reintroduction. A ladder defines ordered stages, tracks progress dates, links Solids exposure logs and reaction notes, and can schedule device notifications for a stage.

This feature records a plan and its observations; it does not decide whether or when an exposure is clinically appropriate. The in-app explanation directs families to work at the pace recommended by their care team.

The family uses its saved selected baby. Coach view-as uses route-local baby context and does not change the family's preference. Without a baby, family self-mode is directed to add one before creating a ladder.

The default query returns non-archived ladders for the selected baby, newest-updated first. Each card shows:

1. title, icon, description and stage count;
2. the active/in-progress stage, or next incomplete stage when none is explicitly active;
3. completed stages out of total stages;
4. the count of server reminder records whose status is scheduled.

Archived ladders can be requested through the API with includeArchived=true, but the current screen has no archived-list/restore UI.

Users can begin with a blank custom ladder or either built-in five-stage preset:

The preset text is editable; choosing a preset does not create a locked clinical protocol. Current editor fields are:

1. required ladder name (trimmed), optional description and ladder icon;
2. one or more ordered stages;
3. stage icon, title and optional description.

The editor starts with one stage, permits adding/removing stages but never fewer than one, and assigns array order as stage order. There is no drag/reorder control in the current UI. A blank stage title is serialized to Stage N; the platform still requires every submitted stage to have a non-empty title.

When editing, existing stage IDs are sent back so their status, dates, linked-entry IDs, reaction summary and reminders survive. New stages start as Pending. Removing the active stage clears activeStageId; see the lifecycle caveats below for linked records/native reminders belonging to a removed stage.

The platform rejects completing a stage that has not first been started. It does not require previous stages to be completed before a later stage starts, and starting another stage updates the active-stage pointer without automatically rewriting other stage statuses.

For a started/completed stage, Edit dates requires a start time and, when completed, a completion time. Neither may be in the future (the API allows a two-minute clock-skew tolerance), and completion cannot precede start. Resetting one stage does not delete its linked Solids logs.

Add solids exposure opens the Solids tracker prefilled with ladderId, ladderStageId and the stage title as the initial note. Saving creates an ordinary Solids activity for the same baby. The stage sheet then shows up to 100 matching records, newest first, using both server-reported linked IDs and matching ladder/stage details.

Each linked item can show:

1. logged date/time and family note;
2. Reaction / Accidental / No reaction badges;
3. allergic-reaction notes and accidental-exposure notes.

The ladder service derives each stage's linked IDs and reaction summary from current Solids activities. Editing/deleting a linked activity through tracking changes future ladder summaries. Analysis can also filter/display ladder-stage and reaction context.

Stage reminders are a hybrid of server metadata and device-local delivery.

1. Choose a future local date/time and optional note. A new reminder defaults to approximately the next day on the hour.
2. The WebView creates a stable reminder/notification ID and schedules a one-off native notification first.
3. It then saves scheduledAt, note, timezone offset, notification ID and scheduled status to the platform stage.
4. If the platform save fails, the newly scheduled native notification is cancelled as rollback.
5. Editing first cancels the old native ID, then schedules the replacement and updates the server metadata.

The notification deep-links to the exact ladder/stage. Browser fallback can store/display a reminder-shaped localStorage record but cannot deliver an OS notification; the server record alone is not proof of delivery.

1. Done cancels the native notification and changes server status to completed, clears its notification ID and records triggeredAt.
2. Cancel removes the reminder metadata through the DELETE endpoint after cancelling native delivery.
3. A completed item can be Removed from the stage list.
4. The shared model also supports cancelled status, though the current screen's cancel action deletes the record.

A native notification firing does not call the platform. Therefore its server record remains scheduled until a user marks it Done, edits it or removes it. The card's active-reminder count reflects server status, not a verified list of triggers still present on every device.

Returns only that stage to Pending and clears start/completion dates. Linked Solids activities and reminders remain.

Sets every stage to Pending, clears progress dates/active stage/reaction summaries, and deletes every Solids activity linked to the ladder. It does not merely unlink those activities. There is no restore path in the current product.

The current whole-ladder reset is destructive. The editor states that linked Solids entries will be removed, but the action is sent directly from the Reset button and cannot be undone in the UI.

Current reset logic preserves stage reminder metadata and does not cancel native notifications. Users must cancel those separately when they should no longer fire.

Remove calls DELETE /allergy-ladders/:id, which archives rather than hard-deletes the ladder. It disappears from the default list while its ladder/stage data and linked Solids activities remain. Archiving does not currently cancel native stage reminders, and the app has no unarchive control.

1. Family self-mode reads ladders for its own babies and can write when its subject permissions allow family activity writes.
2. A coach can list ladders only for a current assigned family with active coach/support access and log-view permission.
3. Ladder creation/edit, stage status/date changes, reminder metadata and archive/reset all require the resolved subject's family-write permission (represented in the client by canWriteActivities).
4. Coach routes send an explicit familyUserId, but the API independently resolves the assignment and baby ownership.
5. Ladder/stage links on Solids activities must belong to the same authorized baby/family.
6. Device notification delivery occurs on the actor's device. A coach scheduling from view-as does not install a notification on the family's phone.

1. Resetting or archiving a ladder does not cancel its native stage notifications.
2. A fired native notification does not automatically change server status, so activeReminderCount can become stale relative to the device.
3. Native scheduling and server metadata cannot be one database transaction. During edit/Done/delete, native cancellation can succeed before a later API failure; reopening and resaving may be required to reconcile.
4. Removing a stage drops its embedded reminder metadata from the ladder definition but does not cancel native notifications or delete Solids activities that still reference that removed stage.
5. Archived ladders are API-readable with includeArchived, but cannot currently be restored in the UI.

1. Presets create the documented editable stages and custom ladders retain at least one valid stage.
2. Existing stage IDs preserve progress/reminders when a ladder definition is edited.
3. Stage transitions and timeline edits satisfy start-before-complete and date-order rules.
4. Linked Solids records/reaction summaries are baby-, ladder- and stage-scoped.
5. Whole-ladder reset communicates that it deletes linked Solids and cannot be undone.
6. Reminder UI distinguishes server metadata from actual device delivery and rolls back a failed create save.
7. Family/coach reads and all writes are enforced for the live actor/subject relationship.
8. Release testing covers the documented reminder cleanup/reconciliation caveats.

• mobile-web/src/routes/AllergyLaddersScreen.tsx
• mobile-web/src/components/AllergyStageTimelineEditor.tsx
• mobile-web/src/routes/ActivityTrackingScreen.tsx
• mobile-web/src/webview/native-messages.ts
• mobile-wrapper/src/native/reminders.ts
• platform/apps/api/src/routes/family-routes.ts
• platform/apps/api/src/services/allergy-ladder-service.ts
• platform/apps/api/src/services/allergy-ladder-stage-update.ts
• platform/apps/api/src/services/prisma-invite-flow-service.ts
• platform/packages/shared/src/allergy-ladders.ts

• 05 — Family home
• 06 — Baby profiles and switching
• 07 — Activity tracking
• 09 — Analysis and trends
• 10 — Device reminders