# Phase 3 — follow-up monitoring and management

Implemented on 16 October 2026 for `elderly.mam-app.org`, using registration images 1–3 as the parent source and monitoring checklist images 4–5 as the visit source. No photographed handwriting or patient examples were imported or used as defaults.

## Pages and workflow

- **Follow-up:** `/elderly-support/followup`. Choose a saved registration from this browser or search the server by program/General ID. You can also select **Follow up** from Manage Registration, including for an unsynced browser registration.
- **Manage Follow-up:** `/elderly-support/followup/manage`. Search browser records by snapshot name/ID, or server records by current registration program/General ID; filter by visit dates, parent registration and completion. View details, edit, delete, and start another visit.
- **Visits** on a registration opens follow-up management filtered to that parent. The main navigation includes all four registration/follow-up pages.

Use the existing MAM account and the same browser offline password. Saving remains explicit: Save draft or Complete & save, then Sync now when connected. No automatic upload was introduced. Sync handles both kinds of records from any page: registration upserts first, follow-ups second, registration deletions last. A failed/conflicted parent leaves its dependent follow-up pending and untransmitted until the parent is corrected.

An existing saved follow-up cannot be moved to another elder. Select New draft for another visit. The stable parent UUID survives changes to program IDs and names; multiple visits on the same day remain distinct records.

## Form and source mapping

The runtime definition is `resources/data/elderly-support-followup.json`: 36 logical fields in seven groups, including the hidden parent UUID. It retains all 33 non-derived workbook follow-up columns plus the two paper narrative details. Visit year/month remain derived concepts, not editable controls.

| Group | Source coverage |
| --- | --- |
| Visit and identity | Image 4: ID, date, name, age, address and phone; workbook sex. Identity/contact are copied once from the selected registration; name/program ID are read-only visit snapshots |
| Medical and food support | Image 4: MAM check-up need, regular attendance/nonattendance reason and food-support type |
| Social and household support | Image 4: need, receipt and nonreceipt reasons for social support and basic-needs household packages |
| Housing repair | Image 5: need, receipt and nonreceipt reason |
| Health and referrals | Image 5: new/worsening symptoms and narrative, hospital referral and narrative; workbook adds MAM clinic referral and General ID |
| Distribution | Workbook additions: food/household amounts, separate distribution dates and distributor |
| Collection details | Image 5: remarks, collection date, typed collector name and role/department |

Parent selection is required even for drafts. Completing a visit additionally requires its visit date; other supplied values are validated without inventing a new clinical completion policy. Age is an integer 0–130. Distribution amounts are integers 1–999, matching the workbook; no currency or package unit is assumed. Record units in Remarks. Dates display as DD/MM/YYYY in entry forms and use ISO transport/storage. The date filters use the browser's date picker.

Conditional receipt/reason questions respect the entire chain of controlling answers. Toggling a need to No hides its receipt and reason but retains earlier encrypted answers. Reports must interpret those answers through their controlling fields. Follow-up address, phone and age are visit values and do not overwrite registration. Collection/visit/food-distribution/household-distribution dates stay separate. Collector identity remains typed text; drawn signatures are outside this phase.

## Storage and sync

Only migration `2026_10_16_000200_create_elderly_support_followup_tables.php` is needed on the configured `MAM_NAP` connection. It adds three tables:

- `elderly_support_followups`: immutable parent UUID, visit/date/status projections, encrypted full payload, audit IDs, optimistic version and soft deletion. A foreign key prevents physical parent removal.
- `elderly_support_followup_sync_events`: encrypted versioned snapshots and idempotent operation receipts.
- `elderly_support_followup_sync_counters`: independent committed change-feed sequence, initialized with one row.

Registration tables and their feed are retained. Follow-up endpoints under `/elderly-support/followups/` use the same type 21/admin authorization and no-store responses. Their operation IDs, replay checks, conflicts, bounded download windows and tombstones follow the registration protocol. A follow-up write locks the parent before its child; registration deletion uses a current locking read of active follow-ups, preventing an active child from being orphaned by concurrent deletion.

IndexedDB upgrades from version 1 to 2 by adding `followups`, `followup_queue` and `followup_snapshots`. Existing vaults, wrapped keys, registration records/queue and registration cursor are retained. Both entities use the existing account key with distinct authenticated encryption contexts. Follow-ups have their own cursor and feed; no browser password reset is needed. Save open work before refreshing for this upgrade, and close older Elderly tabs if prompted.

The shared queue counts both entities. Delete protection applies in browser transactions and on the server, including draft visits. Delete/sync active follow-ups before deleting their registration. Clearing an account's browser data includes both entity stores and warns about both queues. Browser JSON export now has `registrations` and `followups` arrays with schema version 2; it remains an explicit readable export of this browser's data, not a complete server or source-format Excel export.

The PWA caches four non-personal shells and static assets, including the new shared `elderly-support-records.js` engine. APIs, records, session tokens, login responses and exports are excluded. Worker cache version is `elderly-support-shell-v5-followup-20261016`.

## Verification

All write tests run on disposable local MySQL with synthetic records. The QA bootstrap rejects production sockets and does not load the project `.env`.

| Check | Result |
| --- | --- |
| Core date/ID/validation/conditional checks | 6 passed |
| Existing registration backend checks | 31 passed |
| Follow-up backend checks | 35 passed |
| Existing registration browser scenarios | 20 passed |
| Follow-up browser scenarios | 20 passed |
| Read-only local origin/assets/auth checks | 24 passed |

Follow-up browser checks cover preserving a real version-one vault/key and unsynced parent, linked offline entry/reload, nested conditions, encryption, parent-first sync, blocked dependencies and correction, editing during upload, conflict review, management filters/details, responsive layouts, deletion/tombstones, cache privacy and account separation. Screenshots are in `outputs/elderly-support-phase3/`.

Run against an initialized disposable socket:

```bash
ELDERLY_QA_SOCKET=/tmp/elderly-support-phase2-<run>/mysql.sock php tests/elderly-support-followup-backend.php
ELDERLY_QA_SOCKET=/tmp/elderly-support-phase2-<run>/mysql.sock php -S 127.0.0.1:8876 -t public scripts/elderly-support/qa-router.php
ELDERLY_PLAYWRIGHT_MODULE=/path/to/playwright/index.mjs node tests/elderly-support-browser.mjs
ELDERLY_PLAYWRIGHT_MODULE=/path/to/playwright/index.mjs node tests/elderly-support-followup-browser.mjs
```

The follow-up backend script includes the registration fixture and resets only disposable tables. Never run it against production or expose the QA router. Deployment uses `scripts/elderly-support/deploy-phase3.py` and an explicit runtime manifest, followed by read-only origin checks. See `DEPLOYMENT.md` for the actual server result and backups.

Monthly reports, historical program outcomes, source-format Excel exports, signature images and cross-device recovery of offline keys remain later work. Native installation and a real device's offline cycle through Cloudflare Access still require device confirmation; automated offline flows were verified in real Chrome locally.
