Medplum Rules

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 AccessPolicies to bots — restrict to minimum required resource types.
• Use Subscriptions with channel.type: 'rest-hook' and channel.endpoint: 'Bot/<ID>' for event-driven execution.

GraphQL

• Append List to resource type for searches: PatientList(name: "Eve").
• Use snake_case for search parameters in GraphQL (not kebab-case): address_city, not address-city.
• Use inline fragments for reference resolution: ... on Observation { valueQuantity { value } }.
• Use _reference for reverse lookups: EncounterList(_reference: patient).

CLI (@medplum/cli)

• Use medplum login for auth, medplum get/medplum post for FHIR operations.
• Use medplum bot deploy for bot deployment in CI/CD pipelines.
• Use medplum bulk export for bulk data operations.

Medplum / FHIR Patterns

Bundle Transactions

• Use type: 'transaction' for atomic multi-resource operations — all-or-nothing.
• Use type: 'batch' when operations are independent and partial failure is acceptable.
• Use urn:uuid:<uuid> in fullUrl for forward references between entries.
• Reference other entries via { reference: 'urn:uuid:<uuid>' }.
• Use ifNoneExist on POST entries for conditional creation (idempotent).
• Use ifMatch: 'W/"versionId"' on PUT entries for optimistic concurrency.
• Use conditional references for existing resources: Practitioner?identifier=http://hl7.org/fhir/sid/us-npi|123.
• For large bundles (>50MB), use Prefer: respond-async header.

Search Patterns

• Use _include=ResourceType:searchParam to fetch referenced resources in one call.
• Use _revinclude=ResourceType:searchParam to fetch resources referencing your results.
• Use :iterate modifier for multi-hop traversal: _include:iterate=Patient:general-practitioner.
• Use _count + _offset for pagination; use searchResourcePages() for async iteration.
• Use :contains modifier for substring search on string params: name:contains=eve.
• Use :not modifier to exclude: status:not=completed.
• Use comma-separated values for OR: status=active,on-hold.
• Use multiple parameters for AND: name=Simpson&birthdate=1940-03-29.
• Prefer searchResources() over search() — returns typed array, not raw Bundle.

Subscription & Bot Workflows

• Create a Subscription resource with criteria (FHIR search query) and channel.type: 'rest-hook'.
• Point channel.endpoint to Bot/<BOT_ID> for automated processing.
• Use subscribeToCriteria() client-side for WebSocket real-time updates.
• Never subscribe to AuditEvent changes — prevents notification spirals.
• Use cron-based bots for scheduled tasks (e.g., daily reports, batch processing).

Access Policies

• Define AccessPolicy.resource[] with resourceType and optional criteria, readonly, hiddenFields, readonlyFields.
• Use %profile variable to scope data to the current user: Observation?performer=%profile.
• Use %patient variable for patient-portal access: Observation?subject=%patient.
• Use compartment-based access for patient-scoped isolation.
• Use writeConstraint with FHIRPath for state machine enforcement (e.g., prevent status rollback).
• Apply least privilege: start with no access, add specific resource types.

Conditional Operations

• Use createResourceIfNoneExist(resource, query) for idempotent creates keyed on identifier.
• Use upsertResource(resource, query) for atomic create-or-update in a single request.
• Use If-None-Exist header on POST for server-side conditional creation.

Patient Deduplication

• Match on identifier systems (MRN, SSN, insurance ID) for deterministic matching.
• Use probabilistic matching on name + birthdate + address for fuzzy matches.
• Use Patient link field with type: 'replaced-by' for merge workflows.
• Prefer createResourceIfNoneExist() at ingestion to prevent duplicates.

Questionnaire Workflows

• Create Questionnaire resources for form definitions. Use linkId for question identification.
• Use QuestionnaireResponse for captured answers. Link to Questionnaire via questionnaire field.
• Use getQuestionnaireAnswers(response) to extract answers as a map keyed by linkId.
• Automate post-submission processing with a Bot subscribed to QuestionnaireResponse creation.
• Use SDC (Structured Data Capture) extensions for advanced rendering and extraction.

Medplum / FHIR Security