/medplum-rules

name: medplum-rules
description: "Medplum (FHIR healthcare) coding rules: style, patterns, security, testing. Triggers: medplum.config.mts, medplum.config.ts, FHIR, Medplum, Bot, Subscription, Questionnaire."
effort: medium
user-invocable: false
allowed-tools: Read

Medplum (FHIR healthcare) Rules

These rules come from `app/rules/medplum/` in ai-toolkit. They cover the project's standards for coding style, frameworks, patterns, security, and testing in Medplum (FHIR healthcare). Apply them when writing or reviewing Medplum (FHIR healthcare) code.

Medplum / FHIR Coding Style

Resource Structure

• Every FHIR object must include `resourceType` as first field.
• Use PascalCase for resource types (`Patient`, `ServiceRequest`), camelCase for fields (`birthDate`, `valueQuantity`).
• Never hardcode resource IDs. Let the server assign them on create.
• Include `meta.profile` when creating resources that must conform to a StructureDefinition.

References

• Use `createReference(resource)` from `@medplum/core` to build Reference objects.
• Always include `display` on references for human readability.
• Use `getReferenceString(resource)` for comparisons and logging — returns `ResourceType/id`.
• Use `parseReference(ref)` to extract resourceType and id from a reference string.
• Never concatenate strings to build references manually.

CodeableConcepts & Coding

• Always include `system`, `code`, and `display` in every Coding element.
• Use standard terminology URIs: `http://loinc.org`, `http://snomed.info/sct`, `http://hl7.org/fhir/sid/icd-10-cm`.
• Use `getCodeBySystem(cc, system)` to find codes; `setCodeBySystem(cc, system, code)` to set them.
• Prefer `CodeableConcept` over plain `Coding` when the FHIR spec allows both — it supports multiple codings and free text.

Identifiers

• Use `identifier` arrays with `system` + `value` for external IDs (MRN, NPI, SSN).
• Use `getIdentifier(resource, system)` and `setIdentifier(resource, system, value)` helpers.
• Identifier systems must be absolute URIs (e.g., `http://hl7.org/fhir/sid/us-npi`).
• Use `createResourceIfNoneExist(resource, 'identifier=system|value')` for idempotent creates.

Extensions

• Use the `extension` array with `url` and typed `value[x]` fields.
• Prefer official HL7/US Core extensions over custom ones where they exist.
• Use `getExtension(resource, url)` and `getExtensionValue(resource, url)` helpers.

Bundles

• Use `urn:uuid:<uuid>` for internal references between entries in a transaction Bundle.
• Every Bundle entry must have `request.method` (`POST`, `PUT`, `DELETE`) and `request.url`.
• Include `fullUrl` on entries that are referenced by other entries.
• Use conditional references (`Practitioner?identifier=npi|123`) for existing resources.

HIPAA-Aware Coding

• Identifiers like SSN, MRN, and insurance IDs are PHI — never log raw values to console or external services.
• Use a safe logging utility (e.g., `safeLog()`) for any output that might contain patient data. Never `console.log` raw FHIR resources.
• Reference `display` strings may contain patient names — treat as PHI in logs and error messages.
• Every new data access path or admin operation must include corresponding `AuditEvent` creation. No exceptions.
• When audit logging fails (Medplum unreachable), write to a fallback store — audit events must never be silently dropped.
• See `security.md` rules for full HIPAA, access policy, and PHI handling requirements.

Formatting

• Use `formatHumanName()`, `formatAddress()`, `formatDate()`, `formatQuantity()` for display strings.
• Use `getDisplayString(resource)` as a universal fallback for any resource's display name.
• Never manually concatenate name parts — FHIR names have `given[]`, `family`, `prefix[]`, `suffix[]`.

Medplum Frameworks

@medplum/core — SDK Client

• Use `MedplumClient` for all FHIR operations. Never use raw `fetch` against Medplum endpoints.
• Use `medplum.createResource()`, `readResource()`, `updateResource()`, `deleteResource()` for CRUD.
• Use `medplum.searchResources()` for typed arrays. Use `medplum.searchOne()` when expecting a single result.
• Use `medplum.executeBatch()` for transaction Bundles — groups multiple operations atomically.
• Use `medplum.upsertResource(resource, query)` for atomic create-or-update.
• Use `medplum.createResourceIfNoneExist(resource, query)` for idempotent creation.
• Configure `autoBatchTime` on MedplumClient to auto-batch concurrent GET requests. Use `Promise.all()` instead of sequential `await` to benefit from batching.

@medplum/fhirtypes — Type Safety

• Import FHIR types directly: `import { Patient, Observation } from '@medplum/fhirtypes'`.
• Use TypeScript types for all FHIR resources — never use `any` for resource data.
• Cast `event.input` in bot handlers: `const patient = event.input as Patient`.
• Use optional chaining for nested FHIR fields: `patient.name?.[0]?.given?.[0]`.

@medplum/react — UI Components

• Wrap app with `<MedplumProvider client={medplum}>` at the root.
• Use `useMedplum()` hook to access the MedplumClient instance in components.
• Use `useMedplumContext()` for client + profile + loading state together.
• Use `<ResourceForm>` for auto-generated CRUD forms, `<ResourceTable>` for display.
• Use `<SearchControl>` for searchable/filterable resource lists.
• Use `<QuestionnaireForm>` to render FHIR Questionnaires and capture responses.
• Use `useSubscription(criteria)` for real-time WebSocket data in React components.
• Requires Mantine 7+ and PostCSS with Mantine preset. Import `@mantine/core/styles.css`.

Bot Development

• Export a single `handler` function: `export async function handler(medplum: MedplumClient, event: BotEvent)`.
• Access trigger resource via `event.input`. Access secrets via `event.secrets`.
• Use `event.contentType` to determine input format (`application/fhir+json`, `text/plain`, `x-application/hl7-v2+er7`).
• Deploy bots via CLI for CI/CD: `medplum bot deploy <bot-name>`.
• Apply Ac