ADR-005: Family and delegated healthcare access (backend)
Consequences¶
Positive¶
- The service and data layers need no change; the decision point generalises a resolver the ingest path already uses.
- No migration of existing health data. Existing users receive no delegations, so "membership grants nothing" holds from day one by default.
- The doctor PIN contract is untouched, so mobile clients need no change there.
- The audit table already separates actor from subject, so the extension is purely additive.
- Attribution improves for everyone, not only caregivers, because the authorisation basis is now recorded.
Negative¶
- Every route that currently treats the caller as the patient must be converted. A missed route is a potential bypass, so an automated check asserting that every subject-scoped route passes through the decision point is a hard requirement, not a nice-to-have.
- One extra database query per delegated request.
- Making credentials optional on the users table touches authentication and is the riskiest single migration in this work; it should ship on its own.
- Server-side reminders are a genuinely new subsystem and the largest piece of new work here. A defect in it is a patient-safety issue rather than a usability one.
- Caregiver reminders require connectivity, unlike the patient's own device alarms.
- The stored timezone becomes load-bearing once the server fires reminders; today the device owns the clock.
Operational¶
- Introduced behind a feature flag, following the existing pattern, and disabled by default.
- Sequencing: audit extension first, then the decision point in self-only mode (which must leave the existing test suite passing unchanged — this is the gate that proves the refactor is safe), then the subject-explicit endpoints, then adult-to-adult delegation, then families, then managed dependents, then reminders, then escalation. The first three steps deliver no visible feature and carry most of the safety value.
- Rollback is the feature flag. The schema is additive and harmless when unused. Only the managed-dependent step needs an agreed plan for orphaned records before it ships.
Follow-up records¶
Three decisions are deliberately out of scope here and should be recorded separately rather than expanding this one: hardening of the doctor PIN session (rate limiting on redemption, session revocation, scope enforcement, audit coverage), the design of the server-side reminder and escalation subsystem, and the unresolved product questions on delegation lifecycle (what happens to delegations when someone leaves a family, who may authorise access over a managed account, and whether a managed account can later become a full account).