feat(patients): patient data export (right of access) as a complete, machine-readable bundle

[zainabwahab-eth]

Closes #40

What changed

Endpoints (patient-only, self-only. Doctors and admins get 403; another patient's export id returns 404, the same as an id that doesn't exist):

• POST /patients/me/export returns 202 with a status object and a Location header. If the patient already has an export pending or processing, it returns that one instead of queuing a second (the PatientProfile row is locked FOR UPDATE, so a double-click can't create two jobs).
• GET /patients/me/export/:id returns status, expiresAt, a machine-readable failure, and downloadUrl once ready.
• GET /patients/me/export/:id/download streams the JSON bundle. It returns 409 EXPORT_NOT_READY until the export is ready, and 410 EXPORT_EXPIRED at or after expiresAt, even if cleanup hasn't run yet.

The download is a third route rather than a different response shape on GET /:id, so the status endpoint always returns JSON.

Exporter registry (ARCHITECTURE.md §3.1). Each module contributes its own section through its own services/. patients never queries another module's tables:

Section	Owner	Contents
account	auth	email, phone, role, emailVerifiedAt (never the password hash)
profile	patients	full name, DOB
appointments	appointments	status/origin, slot times via availabilityService.getSlotTimesByIds, doctor name via doctorsService.getDoctorSummariesByIds
payments	payments	order ref, status, amount (string), facility, escrow id, stellarTxHash, contract id

Sections are listed explicitly in src/export-sections.ts and registered by createApp(). To add a module later (referrals, prescriptions, ...), export a PatientExportSection from its service and add one line there. Every section uses an explicit field allowlist, so a column added later doesn't leak into exports by default.

Bundle: { format: "docforum.patient-export", schemaVersion: 1, exportId, generatedAt, sections: { <name>: { version, items } } }.

Bounded memory. Sections page with keyset pagination (PATIENT_EXPORT_PAGE_SIZE, default 200). The writer flushes about 256 KiB chunks into PatientExportChunk as it goes, and the download reads one chunk at a time with backpressure. Memory is about one page plus one chunk, however long the history is.

Lifecycle and integrity. pending → processing → ready → expired, or → failed. Every transition is a conditional UPDATE. Each claim bumps an attempt fencing token: chunks are keyed by it, and ready is conditional on it, so two racing workers generate a job exactly once and a stale or crashed claim can't publish a partial bundle. If any section throws, the whole export fails (SECTION_FAILED plus the section name, never the error message), and its partial chunks are deleted. Claims older than 15 minutes are requeued, up to 3 attempts.

Jobs (src/jobs/patient-exports.ts, started from server.ts only). Plain intervals, per ARCHITECTURE_ESSENTIALS. The worker is also woken immediately by a new request. Cleanup expires ready exports past their TTL (PATIENT_EXPORT_TTL_HOURS, default 24), deletes their chunks, and sweeps any chunk that can't be served. It touches only this module's export rows.

Schema changes (proposed per AGENTS.md)

• New PatientExport + PatientExportChunk and enum PatientExportStatus. Migration 20261017062203_add_patient_export adds tables only; no existing table is altered.
• Storage decision: bundles are kept in Postgres rather than object storage. No object-storage provider exists yet, and a filesystem store would break on Render's ephemeral disk and on any second instance. Recorded as ARCHITECTURE.md §6.3.4. Only patients/repositories touches the chunks, so moving to S3 later swaps that seam, not the design.

Docs

ARCHITECTURE.md §3.1 (registry, and how to register), §4.10 (models), §6.3.4 (storage trade-off); ARCHITECTURE_ESSENTIALS.md (model map, jobs); docs/api/README.md (endpoints, status object, bundle schema, env knobs); backend/src/jobs/README.md; backend/.env.example; ROADMAP.md (Phase 8 item and changelog).

Tests

• tests/unit/patient-export.test.ts (12): bundle format and version, chunk-size bound, paging before later pages are fetched, section failure keeps only the section name, multi-byte byte accounting, registry duplicate and name rules, keyset pagination.
• tests/integration/patient-export.test.mts (11, own embedded Postgres on port 5438):
  • in-flight dedupe under concurrent POSTs
  • doctor, admin and anonymous callers refused on all three routes; a patientProfileId in the body is ignored
  • cross-patient 404
  • full bundle contents, including tx hash and BigInt strings, with no password hash, no sentinel platform secrets, and none of another patient's rows
  • multi-chunk streaming and size accounting
  • two workers racing for one job
  • failing section: job failed, no artifact, no error text stored
  • stale-claim requeue, fencing, and the max-attempts failure
  • expiry refusal before and after cleanup; cleanup leaves unexpired exports alone
  • real job wiring wakes on a request
  • booking rows unchanged

Mutation check: dropping the owner scope from findExportForPatient makes the cross-patient test fail.

npm run typecheck        → tsc --noEmit (clean)
npm test                 → Test Files 7 passed (7) · Tests 42 passed (42)
npm run test:integration → Test Files 5 passed (5) · Tests 33 passed (33)
npm run build            → clean

These were run in Ubuntu (WSL) on Node 20 to match CI, with --hookTimeout raised locally. The existing suites' beforeAll takes more than 10s on this machine; the new suite sets its own 180s hook timeout.

Notes for reviewers

• A verified guardian exporting a dependent's data (mentioned in the issue) depends on [Phase 8] Guardian and dependent accounts: booking on behalf of a minor #42's model and is not built here. ExportSubject carries patientProfileId explicitly so it can be added without changing the registry.
• Open PR feat(audit): PHI read-access logging: record who viewed which clinical record (#45) #149 also creates backend/src/modules/audit/. There's no overlap with this PR.

🤖 Generated with Claude Code

[drips-wave]

@zainabwahab-eth Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[afeezorobsco-cyber]

fix conflicts

[afeezorobsco-cyber]

CI is failing on this PR. main itself is green, so the cause is in this branch:

Typecheck fails: src/app.ts(18,3): Cannot find name 'registerPatientExportSections'. app.ts calls it, but the import from ./export-sections is missing, probably dropped when you merged main in. Add the import.

Please push a fix and CI will re-run. Before pushing, run npm run prisma:generate && npm run typecheck && npm test && npm run test:integration in backend/.

[afeezorobsco-cyber]

Reviewed: export is patient-only and self-only, foreign ids 404, every section is an explicit field allowlist (no password hash / throttle state), generation is paged + chunked with conditional claims, and the download streams with backpressure. CI green. LGTM.