Health Diary — Patient Web Interface Design

Issue: #2291 Status: Built. The screens below ship in #2417; the failure states were reworked in #2518. Companion docs: Product spec · How a patient uses it · Developer guide · QA guide App: patient/ (Vite + React 19 + React Router 7 + TanStack Query + shadcn/Radix + Tailwind 4) Revised: 2026-09-15 — layout reworked to coexist with the app sidebar; dashboard and notification integration added.

Two jobs, one surface: the Health Diary for patients who use the web app, and a working harness that exercises every /patient/health-diary/* endpoint without a mobile build.

1. Why build this at allCopy Anchor Link

The mobile app is the primary client, but it is a slow loop to develop against: build, install, reproduce, read a device log. A web surface that speaks the identical API gives us:

• A faster debug loop. Every request visible in the network tab, every response inspectable.
• Contract verification before mobile integrates. If the web client can drive all 14 endpoints, the contract is real. Divergences (D-1 in the backend plan) surface here first.
• A place to see the safety rules. Disclaimer rendering, emergency banners, moderation refusals and rate-limit handling are UI problems as much as backend ones.
• Caregiver mode for free. The web app already carries X-On-Behalf-Of on every request.

It is a real patient surface, not a test page — but the diagnostics drawer (§8) exists because the debugging job is a stated goal, not an afterthought.

2. What the app already gives usCopy Anchor Link

Nothing new is needed at the infrastructure layer. This is a feature folder, a route, a sidebar entry and a services file.

3. Information architectureCopy Anchor Link

Route /health-diary (add HEALTH_DIARY: '/health-diary' to APP_ROUTES), sidebar entry Health Diary with the NotebookPen icon, placed after My Care — it belongs with care, not with records, because it is where a patient goes when something is happening now.

/health-diary                    workspace (opens the most recent thread)
/health-diary?thread=<id>        deep link to a thread — the shareable/debuggable URL
/health-diary?folder=<id|slug>   folder filter
/health-diary?tab=history        entries + summary view

Thread and folder live in the query string, not the path: it keeps deep links copy-pasteable into a bug report, and survives the cache wipe on a caregiver-context switch.

4. Layout — living inside the app shellCopy Anchor Link

The constraint. AppLayout already spends 16rem (256px) on AppSidebar before a feature gets any width. A folders rail plus a thread list plus a conversation would make four vertical columns: 256 + 240 + 300 = 796px of chrome before the patient reads a word. On a 1366px laptop — common for our users — the conversation is left with about 520px, and the page reads as a stack of rails rather than a conversation.

The resolution: two panes, folders as a filter strip.

┌──────────────┬────────────────────┬─────────────────────────────────────┐
│ AppSidebar   │ Threads (300px)    │ Conversation (fluid)                │
│ 16rem        │                    │                                     │
│ (existing,   │ ┌ folder strip ──┐ │  ┌ patient message ───────────┐    │
│  collapsible)│ │All·General 3·…+│ │  └────────────────────────────┘    │
│              │ └────────────────┘ │  ┌ assistant message ─────────┐    │
│ Dashboard    │ Headaches, 3 days  │  │ answer …                   │    │
│ Appointments │  "Let's look at…"  │  │ ── disclaimer ──           │    │
│ My Care      │ Trouble sleeping   │  │ [Talk to a Doctor] [Care]  │    │
│ ▸ Health     │  "How many hours…" │  └────────────────────────────┘    │
│   Diary      │ Knee pain          │  ┌ composer  ◎  ↑ ─────────────┐   │
│ Records …    │                    │  └─────────────────────────────┘   │
└──────────────┴────────────────────┴─────────────────────────────────────┘

Folders in this product are four defaults plus a handful of user-created topics with counts. A horizontal strip of filter chips carries that perfectly well, and it buys back 240px for the thing people actually came to read.

It also matches the phone. The mobile contract names a FolderSelector, not a folder rail. One mental model across both clients — which matters, because mobile is the primary client and we do not want two different ideas of what a folder is.

Folder management (create, rename, delete, see the thread count that moved) lives behind the + chip and a per-chip context menu, not in permanent furniture.

BreakpointsCopy Anchor Link

Rejected alternatives, and whyCopy Anchor Link

The other thing the shell doesCopy Anchor Link

AppLayout's main element is h-full overflow-y-auto bg-muted/30 p-6 — page-level scrolling and 24px of padding. A chat surface wants the opposite: no page scroll, and the message list owning the only scroll container, so the composer stays pinned and the header does not drift.

Fix: give AppLayout an optional contentClassName (defaulting to today's classes) and have the diary pass p-0 overflow-hidden. Three lines, no other page affected. The diary page is then flex h-full min-h-0 flex-col with min-h-0 on the scrolling child — not a calc(100vh - …), because ImpersonationBanner sits above main and changes its height whenever a caregiver is viewing a dependent.

5. The conversation, in its two difficult statesCopy Anchor Link

Ordinary replies are the easy case. Two states are where the product promises are kept or quietly broken:

• Emergency flag. The guidance renders above the answer, carries an icon and a label as well as colour, and must pass AA contrast in both themes. It is the one place in this UI where colour alone carrying the meaning would be a safety problem.
• AI unavailable. The patient's own words stay on screen, the copy says plainly that the note was saved, and retry is right there. A UI that drops the message on error breaks promise P9 that the backend is already keeping.

6. ComponentsCopy Anchor Link

patient/src/features/health-diary/

7. Data layerCopy Anchor Link

Mirrors features/health-records: a thin service module per resource, hooks over TanStack Query, keys centralised.

// lib/query/keys.ts — added
hdFolders:  ['health-diary','folders'] as const,
hdThreads:  (folderId?: string) => ['health-diary','threads', folderId ?? 'all'] as const,
hdMessages: (threadId: string)  => ['health-diary','messages', threadId] as const,
hdEntries:  (f: Record<string,unknown>) => ['health-diary','entries', f] as const,
hdSummary:  (days: number) => ['health-diary','summary', days] as const,

Three behaviours worth specifying, because they are where a chat UI gets it wrong by default:

1. Optimistic user turn, never an optimistic answer. The patient's message appears immediately with a pending marker; the assistant slot is a typing placeholder. We never render a speculative reply. If the request fails, their words stay on screen with a retry — and are already saved server-side.
2. One idempotency key per composed message. Generated once, held across retries, regenerated only when the composer clears. That is what makes the backend's idempotency real rather than theoretical — the client half of decision D-2.
3. Cursor paging, not page numbers. useInfiniteQuery keyed on the oldest loaded message id, with has_more driving the loader at the top of the scroll container.

Caregiver switching needs nothing new — useSwitchSubject already removes all queries. The one addition is a composer guard: a draft in progress when the subject changes is discarded with a visible notice, never silently sent into the wrong person's diary.

8. Diagnostics drawerCopy Anchor Link

A slide-over toggled from the diary header, enabled in dev or with ?debug=1, showing for recent requests: endpoint, status, duration, request_id, the X-RateLimit-* headers, the idempotency key and attempt number, thread/message ids, safety_flag, whether a disclaimer was present, the CTA actions returned, transcription source and confidence, and whether the response envelope matched the mobile contract.

Two actions: Copy as bug report (endpoint, request id, payload, response, app version) and Replay (same request, fresh idempotency key).

9. Dashboard integrationCopy Anchor Link

The dashboard is a bento grid where each card owns its own query (features/dashboard/pages/Dashboard.tsx). The diary earns one cell, one quick action, and an optional line in the activity feed.

9.1 The cardCopy Anchor Link

HealthDiaryCard — a col-span-1 cell with two states:

The composer is the point. A dashboard card that only displays diary data is a link with extra steps; a card that accepts the first sentence is the product's front door, and it is where a first-time patient will discover the feature at all.

9.2 One hard rule: the dashboard never triggers an LLM callCopy Anchor Link

GET /summary generates a summary — an LLM call, billed and slow. Mounting it on a dashboard that every patient loads on every visit would mean an AI call per session per patient, which is both a cost problem and a latency problem on a page that must feel instant.

So the card reads only cheap list endpoints (/entries, /threads) for its counts and topics, and links to the summary rather than rendering it. If we ever want the summary on the dashboard, it must come from the cached health_diary_summaries row and render nothing when no fresh one exists — never generate on read.

9.3 Where it sitsCopy Anchor Link

Adding a seventh card means reflowing the grid. Recommended (a product call, not a technical one):

Row 1   Welcome        │ Health Diary   │ Quick Actions     ← today / act now
Row 2   Vitals         │ Medications    │ Appointments      ← your numbers
Row 3   Activity Feed (2-span)          │ Wellness          ← what has happened

Row 1 becomes "what do I do now", which is exactly the diary's job, and it puts the card where a first-time user's eye already goes.

9.4 Quick actions and refreshCopy Anchor Link

• Add a Diary action (NotebookPen) to QuickActions — a one-line addition to the array.
• Add ['health-diary'] to the dashboard's refresh invalidation list, or the refresh button will silently skip the new card.

9.5 Activity feed — optional, and only if it is honestCopy Anchor Link

ActivityFeed reads useClinicalTimeline, which is clinic-sourced data. Diary entries are patient-authored. Merging them without distinction would let a self-recorded note read as a clinical record — a provenance problem, not a cosmetic one.

If we merge, the entries must carry the existing SourceChip marking them self-recorded (the health-records feature already solved exactly this problem). Client-side merge of the two most recent sources, sorted by date, capped at five. Recommended as optional for v1: the card is the important surface; the feed is nice-to-have.

9.6 Caregiver contextCopy Anchor Link

No special handling — every request already carries the on-behalf-of header, so the card shows the dependent's diary while impersonating, and ImpersonationBanner above the page already says whose data is on screen.

10. NotificationsCopy Anchor Link

10.1 What the app has todayCopy Anchor Link

• No notification inbox. No bell, no list, no unread count anywhere in patient/.
• Ably is used as a refetch signal only. PatientRealtimeProvider mounts one Ably client for the session; usePatientAppointmentRealtime subscribes to private:user:{id}, listens for notification.created, and invalidates appointment queries. The payload is {id, kind} — the client re-fetches rather than trusting pushed data.
• The backend has an inbox the app never calls: GET /notifications/me/inbox, mark-read, mark-all-read, with Notifications::Notification rows.
• Push exists: Shared::Notifications::PushService over AWS SNS, with app_type: 'patient' and per-device fan-out.
• Preferences exist but have no diary bucket: appointment_reminders, prescription_ready, payment_reminders, marketing, each with sms | push | email toggles.

10.2 What should notify — and what should notCopy Anchor Link

10.3 The refetch hint, concretelyCopy Anchor Link

Publish health_diary.thread.updated with { thread_id } on the recipient's private channel via Notifications::Realtime.user_channel_for — without creating a Notification row. Inbox rows are for things a person should see later; this is a cache signal.

Two implementation notes that will otherwise cost a day each:

1. Publish to both channels when caregiver and subject differ. The event naturally goes to the subject's user channel. If a caregiver wrote the message, their own other devices are on a different channel and will go stale. Publish to both when acting_user != subject_user.
2. Do not create a second Ably client. PatientRealtimeProvider exists precisely because mounting the hook per route was opening and closing a connection on every navigation. A new useHealthDiaryRealtime hook with its own new Ably.Realtime(...) would reintroduce that bug in a different shape. Extend the existing subscription with a second event handler — and this is the moment to rename usePatientAppointmentRealtime to usePatientRealtime, since it is no longer about appointments.

10.4 Rules for any diary notification we do sendCopy Anchor Link

1. No PHI in the preview. A lock-screen line reading "How is your chest pain today?" is visible to anyone holding the phone. Diary notifications are neutral — "Kulcare · A note from your health diary" — and the content lives behind the deep link.
2. Never imply clinical review. No "a doctor has seen your entry", no "we noticed something".
3. Deep link into the thread, using the same ?thread= parameter the web uses.
4. Opt-out must exist before the first one ships. An AI health assistant the patient cannot mute is a support ticket and a trust problem.

10.5 Backend work this impliesCopy Anchor Link

10.6 A language gap this surfacedCopy Anchor Link

SUPPORTED_LANGUAGES in patient preferences is ['en','hi','es']. The diary contract requires en, hi, ml, pa, ta, te, ar — five of which the app cannot express, and one of which (Spanish) the diary does not support. If the diary sends language from the app's locale preference, five of the seven promised languages are unreachable from the web client.

Options: expand the preferences allowlist (backend + frontend), or give the diary its own language selector that defaults to the app locale. This affects promise P7 and should be decided before F3.

11. One constraint, one settled questionCopy Anchor Link

Audio containers — settled. The contract named AAC/M4A because that is what the React Native app records, not as a restriction on the endpoint. The endpoint accepts a container allowlist covering both clients: audio/m4a, audio/mp4, audio/aac from mobile and audio/webm, audio/ogg (Opus) from browsers, since MediaRecorder in Chrome produces WebM. The validation exists to reject junk and oversized uploads, not to enforce one codec. Web voice ships in F4 with no caveat; the transcription provider must accept the browser containers too, which is part of U9's verification.

Fixtures, now that the backend exists. The UI was built against contract-shaped fixtures before the backend landed, and they stay as a development and testing tool rather than the only way to run it. The app has no MSW; its tests mock service modules with vi.mock, and at runtime the service module returns the fixtures, with an artificial delay, when VITE_HEALTH_DIARY_MOCK=true. Mock mode is forced off in any production build. The fixtures double as test fixtures, and their failure scenarios are still the fastest way to reach an error state on screen.

12. Build unitsCopy Anchor Link

F1 is not blocked on anything and can run alongside backend U1.

13. Accessibility and i18nCopy Anchor Link

• The conversation is a log region with aria-live="polite"; new turns are announced once, not per frame.
• Every CTA is a real <button> with a discernible name; the mic has an explicit recording state, not just a colour change.
• Full keyboard path: compose → send (Cmd/Ctrl+Enter) → focus moves to the new reply.
• prefers-reduced-motion disables the typing animation.
• Arabic is RTL — the conversation pane mirrors when the active language is ar. The one layout case not already handled anywhere in this app. See also the language gap in §10.6.

14. TestsCopy Anchor Link

Vitest + Testing Library, following Timeline.states.test.tsx: