Patient Journey

The home dashboard, your whole cross-border case at a glance.

<!-- GENERATED FILE. Do not edit by hand. Source: components/help/content/. Run npm run gen:docs. -->

Purpose & Business Context

The Journey screen is the patient's home base. A cross-border treatment is a long, anxiety-laden process spanning medical opinions, payments, visas, travel and recovery. This screen exists to collapse that complexity into a single, reassuring overview so the patient always knows what is happening now, what they must do next, and who is helping them.

Commercially it is the retention surface of the patient app: a confident next step and a visible coordinator reduce drop-off between the high-intent stages (quote accepted) and the revenue-bearing stages (escrow funded, surgery scheduled).

Screen Overview

A scrollable dashboard composed of: a Next step hero, a Care coordinator card, four status tiles (escrow, e-Visa, surgery date, documents), the interactive 14-stage care journey strip, a recent activity feed and a Concierge & stay card.

Every tile is a shortcut: tapping it deep-links to the screen that owns that part of the journey, so the dashboard doubles as the primary navigation hub.

Controls & Components

• Next step hero, gradient card naming the single most important pending action, with a primary button that routes to it.
• Coordinator card, the assigned care coordinator's name, photo and quick contact (message / call).
• Status tiles (×4), Escrow held, e-Visa status, Surgery date, Documents progress. Each is a clickable Card that routes to Payments, Visa, Care Plan and Documents respectively.
• 14-stage journey strip, a horizontal stepper; tapping any stage opens the stage-detail drawer.
• Stage legend, colour key grouping the 14 stages into phases.
• Recent activity feed, reverse-chronological events on the case.
• Concierge & stay card, a live summary of your chosen flights, accommodation, transfer and interpreter; tapping it opens the Travel & Stay screen to change them.

Field Definitions

• Escrow held: Amount currently secured in escrow vs. the total case price (e.g. $8,400 of $14,000). Read-only; sourced from the payments ledger.
• e-Visa: Current visa application state (e.g. In review) with an ETA. Read-only mirror of the Visa screen.
• Surgery date: Confirmed or provisional procedure date and the operating surgeon. Read-only mirror of the Care Plan.
• Documents: Verified document count over required (e.g. 9 / 11) and how many need action. Read-only mirror of the Documents wallet.
• Stage (1–14): The patient's position in the standard 14-stage care pathway; the active stage is highlighted and the strip shows percent complete.

User Actions & Workflows

1. Read the Next step hero and tap its button to act on the most urgent item.
2. Tap any status tile to jump to the owning screen (Payments, Visa, Care Plan, Documents).
3. Tap a stage dot to open the drawer and read what that stage involves and its status.
4. Message or call the coordinator from the coordinator card for help.
5. Scan the activity feed to confirm recent updates (uploads verified, payments released, messages).

Navigation & Relationships

Reached from: the sidebar Journey item (default landing after sign-in for patients), the brand logo, and post-login redirect.

Leads to: Payments (/portal/pay), Visa (/portal/visa), Care Plan (/portal/care), Documents (/portal/docs), Messages (/portal/messages) via the tiles, hero and coordinator card, and Travel & Stay (/portal/travel) via the Concierge & stay card.

Affected by: changes anywhere in the case, uploading a document, funding escrow, or a visa decision all update this screen's tiles and feed because portal state is shared across routes (see components/portal/PortalProvider.tsx).

Business Rules & Constraints

• Patient-only screen; gated by RequireAuth role="patient".
• All tiles are read-only summaries, the underlying values can only be changed on their owning screens.
• The active stage and progress percentage are derived from case state, not editable here.
• The Next step hero always reflects the highest-priority unmet action in the pathway.

Data Dependencies

Seeded from the mock data layer lib/data (patient, coordinator, stages, activity, concierge) via PortalProvider. In production these map 1:1 to case, payments, visa, documents and messaging services.

• patient, coordinator, profile + assignment
• stages + stageState(), pathway model
• activity, event feed
• journeyProgress(), percent complete

Error Handling & Edge Cases

• Unauthenticated or wrong-role access is redirected by RequireAuth before the screen renders.
• Missing optional data (e.g. no surgery date yet) shows a placeholder state rather than an empty tile.
• If a deep-linked target screen has no data, that screen, not the dashboard, handles its own empty state.
• Mobile: the sidebar collapses behind the menu button; tiles reflow to a single column.

User Roles & Permissions

• Patient: Full view access. Can navigate from tiles and contact the coordinator. Cannot edit summarised values here.
• Clinic / other roles: No access; the /portal/* tree is patient-only.

Related Features & Functionalities

Stage-detail drawer (shared portal component), notifications bell, the context Help panel and walkthrough, and every screen the tiles link to. The 14-stage model is the spine shared by Care Plan, Documents and Payments.

Flow & Screenshots

flowchart LR
  SignIn[Sign in] --> J[Journey dashboard]
  J -->|Next step / tiles| Pay[Payments]
  J --> Visa[Visa]
  J --> Care[Care Plan]
  J --> Docs[Documents]
  J -->|stage dot| Drawer[Stage detail drawer]
  J -->|coordinator| Msg[Messages]
  J -->|Concierge & stay| Travel[Travel & Stay]

Guided Walkthrough Steps

The in-app walkthrough for this screen has 7 steps (auto-advances every 5 seconds; Prev / Pause / Next; click outside to exit):

1. Your Journey home ([data-tour="nav.journey"])

This is your home base. The left sidebar is how you move between the parts of your case, Journey is selected now.

1. Your next step ([data-tour="journey.nextstep"])

We always surface the single most important thing to do next. Tap its button to act on it immediately.

1. Your care coordinator ([data-tour="journey.coordinator"])

A real person is assigned to your case. Message or call them from here whenever you need help.

1. Status at a glance ([data-tour="journey.stats"])

Escrow, visa, surgery date and documents, each tile is a shortcut. Tap one to jump straight to that screen.

1. The 14-stage pathway ([data-tour="journey.stages"])

Your whole cross-border journey, from first opinion to recovery. Tap any stage to see what it involves and where you are.

1. Recent activity ([data-tour="journey.activity"])

A running log of everything happening on your case, uploads verified, payments released, new messages.

1. Help is always here ([data-tour="topbar.help"])

Open this Help button on any screen for documentation, and press Play to replay a walkthrough like this one.