One declarative descriptor per FHIR resource type lets ResourceFacade<R>
route create/read/update/delete/search across HAPI FHIR, two Prisma databases,
and MinIO — including a Tier-0 bridge row in fhir_resource_link that pins
every FHIR resource to a tenant-scoped Prisma key.
Authoritative deep-dive: see
ddx-documentation/97-fhir-resource-facade.md
for the full pattern reference (StoreKind values, descriptor anatomy, recipes,
patterns-to-follow / patterns-to-AVOID, file:line catalog). This KB page is the
audience-facing summary; the canonical doc must NOT be paraphrased into the body.
Business Purpose
A typical FHIR resource in HMS is NOT just a row in HAPI — it's split across
HAPI (canonical), Prisma (link rows, sequences, AR records, demographics
mirror), MinIO (binary attachments), and sometimes external systems. Before
ResourceFacade<R>, every feature module hand-wrote that orchestration —
inconsistent error handling, inconsistent partition routing, inconsistent
tenant scoping. ResourceFacade collapses all of that into one declarative
descriptor per resource type:
One pattern, many resources — adding a NEW FHIR-backed resource is now
~50 lines of descriptor + a useFactory provider, not a new service +
module + Prisma model.
Hard tenant guarantee at write time — every FHIR create runs the Tier-0
makeBaseLinkHooks afterCreate that upserts a fhir_resource_link row keyed
on (resourceType, fhirId, clinicId). Cross-tenant joins on FHIR data become
cheap and safe.
Migration path off legacy FhirService — FhirService was retired
2026-05-17; FhirResourceService + FhirSearchService remain in-tree as
@deprecated for the 47 non-financial consumers tracked under CR-031.
Audiences
Investor: This is the platform's "FHIR adapter for the rest of the
business." It is what lets one engineer ship Invoice, Account, ChargeItem,
PaymentNotice, Claim, Practitioner, and PractitionerRole on the same pattern
in a quarter. Future resources cost descriptor-time, not service-time.
Clinical buyer: Invisible to clinical users — but it is why "the bill,
the appointment, and the prescription are all consistent across tenants" is
a guarantee we can actually make.
Developer/partner: New FHIR resources go through ResourceFacade<R> +
a ResourceDescriptor<R>. Direct FHIR_CLIENT injection is allowed for
transitional code, but new FhirService() is forbidden — FhirService no
longer exists, and FhirResourceService / FhirSearchService are
@deprecated (CR-031 tracks deletion).
Internal (ops/support): All FHIR writes that go through the facade get a
fhir_resource_link row in ddx_api_main.fhir_resource_link — that table is
the cross-clinic index used by audit, partition routing, and (eventually)
cross-system queries.
Five StoreKind values today (core/resource-descriptor.ts:43-51): fhir,
prisma:main, prisma:acc, minio, external.
Tech Stack & Choices
TypeScript + NestJS 11, per-feature useFactory provider (the facade is
generic on R, so it cannot be a global provider — see
data-context.module.ts:26).
Tier-0 / Tier-1 hooks — descriptor hooks (Tier-0) run first
(makeBaseLinkHooks upserts the bridge row), then adapter.hooks (Tier-1)
for resource-specific side effects (invoice-number allocation, presigned-PUT
URLs, …). Hook errors are SWALLOWED — observability is the caller's job;
rollback belongs in the orchestrating service.
Boot-time Zod validation of the descriptor — typos in StoreKind,
missing repositories, or malformed bindings crash the module on start, not
on the first request.
MinIO port is RBAC-agnostic — MinioPort receives a fully-qualified
bucket + key; clinic-bucket resolution lives upstream in
getClinicBucket(slug, type). This is intentional — coupling RBAC into the
port would force every port consumer to fabricate Attachment context.
fhir_resource_link bridge table (prisma-main/models/clinical.prisma)
with UNIQUE (resourceType, fhirId, clinicId) — Prisma can join FHIR data
by tenant without round-tripping HAPI.
Rejected — per-resource service (legacy FhirService model): forced
every new resource to be a fresh class with hand-rolled error handling, no
shared lifecycle, drift across modules. Retired 2026-05-17.
Rejected — global ResourceFacade<R> provider: facade is generic on
R; one global instance cannot serve N resource types. Per-feature
useFactory is the right grain.
Data Flow
Creating an Invoice (canonical financial example):
Service injects INVOICE_RESOURCE_FACADE token → a
ResourceFacade<InvoiceResource> configured with
storageBindings: [{store: 'fhir'}, {store: 'prisma:main', field: 'identifier', repository: invoiceSequenceRepo}].
Tier-1 adapter hook runs (e.g. invoiceNumberAllocatorHook bumps the
gap-less sequence in prisma:main).
Facade returns a FacadeResult<InvoiceResource> discriminated union — the
service narrows with if (!result.ok) return … and reads result.value
without casts.
Implicated Code
MANDATORY: ≥3 file:line citations.
Core engine
ddx-api/src/platform/fhir-resources/core/resource-facade.ts:206 —
class ResourceFacade<R extends FhirResource> declaration.
ddx-api/src/platform/fhir-resources/core/resource-facade.ts:213 —
boot-time Zod descriptor validation (fails fast on misconfigured bindings).
ddx-api/src/platform/fhir-resources/core/resource-facade.ts:249 —
hook execution order (Tier-0 descriptor hooks → Tier-1 adapter hooks; errors
swallowed and logged).
ddx-api/src/platform/fhir-resources/core/minio-port.ts:36 — MINIO_CLIENT
DI symbol.
DI wiring
ddx-api/src/platform/infrastructure/data/data-context.module.ts:11 —
MINIO_CLIENT global registration (the only globally-scoped port the facade
needs at module-instantiation time).
ddx-api/src/platform/infrastructure/data/data-context.module.ts:26 —
comment "NOT exported as a global provider — it is generic" (rationale for
per-feature useFactory).
ddx-api/src/platform/infrastructure/fhir/fhir-client.service.ts:33 —
FhirClientService — the FHIR_CLIENT port the facade consumes for
store: 'fhir' bindings.
Active consumers (post-migration as of 2026-05-16)
ddx-api/src/financial/billing/billing.module.ts:91 — new ResourceFacade<InvoiceResource>(...).
ddx-api/src/financial/billing/billing.module.ts:109 — new ResourceFacade<AccountResource>(...).
ddx-api/src/financial/billing/billing.module.ts:125 — new ResourceFacade<ChargeItemResource>(...).
ddx-api/src/financial/billing/billing.module.ts:141 — new ResourceFacade<ChargeItemDefinitionResource>(...).
ddx-api/src/financial/insurance/insurance.module.ts:75 — new ResourceFacade<ClaimResource>(...).
ddx-api/src/financial/accounting/accounting.module.ts:129 — new ResourceFacade<PaymentNoticeResource>(...).
ddx-api/src/user-mgmt/user-management/user-management.module.ts:74 — new ResourceFacade<PractitionerResource>(...).
ddx-api/src/user-mgmt/user-management/user-management.module.ts:87 — new ResourceFacade<PractitionerRoleResource>(...).
Legacy / deprecated FHIR access
ddx-api/src/platform/fhir/services/fhir-resource.service.ts:22 —
@deprecated Use FhirClientService (via FHIR_CLIENT token from DataContextModule) for all new code.
CR-031 tracks the 47 non-financial consumers still on this class.
ddx-api/src/platform/fhir/services/fhir-resource.service.ts:35 —
export class FhirResourceService body — kept in FhirInfrastructureModule
for transitional code only; do not introduce new callers.
ddx-api/src/platform/fhir/services/fhir-search.service.ts:20 —
export class FhirSearchService — also @deprecated per CR-031 and the
ddx-api/CLAUDE.md "FHIR Service Layers" table; new code uses
FhirClientService.search() via FHIR_CLIENT or ResourceFacade.search().
ddx-api/src/platform/fhir/fhir.module.ts:14 — NF4.6 docstring confirming
the legacy umbrella FhirService class + FHIR_SERVICE token were retired
2026-05-17; all consumers now depend on FHIR_CLIENT.
Operational Notes
Migration status (2026-05-18): 7 financial resources have descriptors
and run through ResourceFacade<R> — Invoice, Account, ChargeItem,
ChargeItemDefinition, Claim, PaymentNotice, Practitioner/PractitionerRole
(the last two via user-management). 47 non-financial consumers remain on
the legacy deprecated FhirResourceService / FhirSearchService — tracked
under CR-031 (see context/REMINDERS.md Permanent Reminders).
new FhirService() is forbidden (ddx-api/CLAUDE.md Forbidden Patterns).
The umbrella FhirService class was deleted; importing it will fail at
type-check. Transitional code that cannot yet adopt the facade should
inject FHIR_CLIENT directly — never recreate FhirService.
Hook errors are SWALLOWED (resource-facade.ts:257). A failed
fhir_resource_link upsert does NOT roll back the FHIR write. If you need
a compensating action, write it in the service that called facade.create
— not in a hook.
afterDelete is a no-op stub by design in makeBaseLinkHooks — the
synthetic delete context lacks enough info for targeted removal. Adapters
that need real cleanup override it.
MinIO bucket map: 7 canonical bucket types
(documents | dicom | lab-results | attachments | recordings | exports | scratch).
Bucket name resolution lives at platform/storage/storage/utils.ts:126
(getBucketTypeForAttachment) — NOT in the port.
Dual-arg call signature: every facade write takes
(resource, clinicSlug, organizationId). Missing organizationId was the
S2.1 follow-up bug in the smoke test — both args flow into
ResourceMutationContext AND into the bridge-row upsert.
Boot-time validation gotcha: type-only descriptor fields (hooks,
adapter, repository) are NOT Zod-validated — they're verified by NestJS
DI. A typo in binding.store crashes at startup; a missing repository
crashes at first request.
Validation command — full pattern reference for adding a new resource:
bash
# Read the canonical recipe
cat ddx-documentation/97-fhir-resource-facade.md
Related Topics
FHIR Partitions and Multi-Tenancy — every
facade write is tenant-scoped via X-Clinic-ID; the Tier-0 hook reuses the
same clinicId to key the bridge row.
Prisma 7 Schemas — the
fhir_resource_link bridge model lives in prisma-main/models/clinical.prisma,
and prisma:main / prisma:acc are the two Prisma StoreKinds the facade
dispatches to.