Patient Onboarding & Signup

Patient Onboarding & Signup

Who this is for: support staff answering patient questions about signing up, PMs, new hires.

The two-phase journey

Every patient goes through two phases:

1. Getting started (acquisition) — the patient picks a service, answers pre-qualification questions, and creates an account. This ends when a case is created.
2. Completing the case (fulfillment) — the patient pays, books an appointment if required, fills out the official intake form, uploads documents, and tracks progress on a status page. This is covered in later chapters (Scheduling, Form filling, Payments).

A patient who already has an account and starts a second service repeats phase 1 for the new service but skips creating another account.

Step by step: getting started

1. Welcome — the patient lands on a page describing the chosen service (what it is, how it works, the price). No account exists yet.
2. Choose state — the patient selects their state. The system checks whether the service is actually offered in that state; if not, the patient is redirected to a “coming soon” page. (See Services catalog for how state availability is configured.)
3. Why this service (most services) — an optional value-proposition page.
4. Pre-qualification questions — a short, multi-page question form (radio buttons, checkboxes, short text, dates, file uploads, name fields) tailored to the chosen service and state. Answers are saved as the patient progresses; any files the patient uploads at this stage are held in the browser temporarily until the account is created.
5. Create account / sign in —
   • New patients: enter name, email, and phone. An account is created immediately and the patient is signed in — there is no password to set.
   • Returning patients (system detects the email is already registered): the patient is sent a one-time sign-in link by email instead of creating a new account.
6. Processing — a brief loading step while the case is created from the answers already collected, then the patient is routed into the case-completion phase.

How sign-in works (no passwords)

Patients never set a password. Signing in works like this:

1. The patient enters their email.
2. The system emails them a one-time link (a “magic link”).
3. Clicking the link signs them in and issues a short-lived digital signature (a signed token) stored in the browser as a cookie. This cookie is what keeps the patient signed in across future visits, and it expires after roughly a week.
4. The one-time link itself expires quickly (about 15 minutes) if unused, so it can’t be reused later.

Signed-in status shared across sites

If the patient portal and the public marketing website are hosted on the same root web domain, the sign-in cookie is deliberately made visible to every subdomain (not just the patient portal). This lets the marketing site check “is this visitor already signed in?” without asking the patient to log in a second time. Locally, or when the domain isn’t configured this way, the cookie stays scoped to just the patient portal, which is the safe default.

Open questions

• No dedicated “signup” chapter content describes what happens if a patient abandons pre-qualification questions partway and returns later — behavior wasn’t confirmed in code beyond “answers are saved as you go” for the current session. Whether that persists across browser sessions before an account exists is unconfirmed.

Where this comes from

• parkingmd-patient-portal/documentation/service-flow.md (sections 1–2)
• parkingmd-patient-portal/documentation/cross-site-auth-cookie.md
• parkingmd-patient-portal/documentation/routing.md (sections 3, 4, 7)
• parkingmd-patient-portal/src/auth/ (tokens, signup, login, verify-token, me, logout handlers)
• parkingmd-patient-portal/src/config.ts (auth.cookieDomain)