Patient Service

Canvas-first slim rewrite. Two tables. Zero clinical data. Canvas owns medical records; this service owns only identifiers and the HIPAA-grade verbatim intake archive.

Overview

Patient-service is the identifier map. Given one of {MRN, Canvas Patient ID, Stripe customer ID, Clerk user ID, legacy Bask MRN, lowercase email}, it returns the patient-directory row that ties them together. It also holds intake_snapshots — the verbatim intake payloads we keep for HIPAA / clinical compliance.

It owns no clinical data. Name, DOB, address, conditions, allergies, medications — all in Canvas. If a sidecar needs those, it fetches live via @yourera/canvas-client.

Canonical spec: /docs/schema/patient-domain.md in the platform monorepo.

Why slim?

Pre-Canvas, patient-service stored clinical fields that were also in Canvas — causing drift, doubled PHI surface area, and reconciliation headaches. The Canvas-first rewrite deletes all of that. Two tables, clear ownership. Clinical truth lives in Canvas; this service is the join key.

Status

Database Schema

patient_directory

intake_snapshots

INSERT-only. Never updated, never deleted. Append every completed intake (new patient or re-intake) as a verbatim payload.

Also present: outbox (transactional outbox) and audit_events (admin-action log), shared-pattern tables.

MRN Generation

Our MRN is 10 characters of Crockford base32 — 0-9A-Z minus I, L, O, U. CSPRNG-backed (crypto.randomBytes). Case-insensitive unique at the DB level (CITEXT or lowercased functional index).

On collision, we retry up to a small bound (typically 5) before surfacing a 503. The 10-char space is large enough that collisions at our volume are theoretical, but the retry is a defense against birthday effects and future scale. The MRN is mirrored to Canvas as Patient.identifier[].value with system https://yourera.com/mrn.

HTTP Endpoints

Atomic Create Semantics

POST /patients is the most delicate endpoint. It touches two systems (Canvas + Postgres) and must either complete fully or cleanly fail. The shape:

1. Generate a candidate MRN (retry on DB collision).
2. Call canvas-client.patient.create(…) with the MRN as Patient.identifier. Capture the returned Canvas Patient.id.
3. Open Postgres transaction. INSERT into patient_directory with canvas_patient_id already set. INSERT into intake_snapshots. INSERT into outbox with patient.created. Commit.
4. Return the new patient.

Email Lookup Privacy

POST /patients/email-lookup is called by intake-gateway at step 1 to tell the patient "we already have you on file, resume?". The privacy contract:

• Caller must include { email, organizationId }.
• Caller must be a member of organizationId (enforced via requireOrgAccess).
• Response is the same shape regardless of which orgs the email matches in.

{
  "exists": true,
  "in_your_org": true,
  "status": "active"
}

The patient-facing UI branches: resume (if in_your_org and active), sign-in (if in_your_org and has clerk_id), contact support (if exists elsewhere or archived).

Identifier Backfill Rules

PATCH /patients/:id is deliberately narrow. It exists only to fill in identifiers that get minted asynchronously after create:

Archive Flow

1. Operator calls POST /patients/:id/archive (or patient requests deletion).
2. Service sets archived_at = now(), INSERTs outbox with patient.archived.
3. Outbox worker ships to EventBridge.
4. webhook-receiver's CanvasSyncWorker (SQS consumer) receives the event and calls canvas-client.patient.update(id, { active: false }).
5. Canvas reflects inactive; the intake-snapshots remain for compliance.

We do not hard-delete. Snapshots are an INSERT-only compliance log and must be retained for the HIPAA retention window; the directory row is retained as the join key.

Intake Snapshots

intake_snapshots is the append-only store of verbatim intake payloads. Every completed intake — initial and re-intake — writes one row. The payload is exactly what the intake client submitted: no normalization, no stripping, no re-serialization beyond the JSON round-trip. If a field was collected, it's in the snapshot.

This is the archive the compliance team reads during audits. Canvas holds the clinically normalized view (Observations, Conditions, Consent, etc.); this table holds the raw payload the patient actually submitted at that moment in time. Both are needed: Canvas answers what is clinically current?, snapshots answer what did the patient tell us in 2026?.

Emitted Events

Testing

908 tests total:

• 573 unit — pure logic (MRN generator, identifier backfill validator, email-lookup response shaping).
• 322 integration — request-level tests with canvas-client stubbed and outbox verified.
• 3 real-Postgres-skipped — run locally against a real DB for the atomic-create transaction path and collision retry. Skipped in CI to keep the tree hermetic.

Key coverage: the atomic-create orphan path (simulated Postgres commit failure), MRN collision retry bounds, every 409 on immutable identifiers, the email-lookup privacy matrix (in-org / cross-org / not found for each caller role), archive flow end-to-end.

TODOs & Future Waves

• Patient merge. When a patient creates two accounts by mistake (different emails, same human), we need a merge operation. Deferred — operationally rare and needs Canvas-side Patient.link support.
• Snapshot pruning policy. We're INSERT-only indefinitely. An eventual archive after N years policy will need legal sign-off.
• Bulk export. No export endpoint today. Compliance gets snapshots via direct DB query; a first-class API with signed-URL delivery is planned.
• Change-of-organization. organization_id is single-org-for-life. If we ever support rehoming (e.g. an org acquisition), this service will need an explicit migration endpoint with Canvas-side managingOrganization updates.
• Legacy Bask reconciliation. legacy_bask_mrn exists for the Bask→Canvas migration window. Once that window closes, we'll plan a column drop.