Skip to content

docs(mpf): fold the MPF pipeline into Deploy, correct drift from the implementation - #25

Open
Nesmeshnoy wants to merge 1 commit into
mainfrom
mpf-split-and-factfix
Open

docs(mpf): fold the MPF pipeline into Deploy, correct drift from the implementation#25
Nesmeshnoy wants to merge 1 commit into
mainfrom
mpf-split-and-factfix

Conversation

@Nesmeshnoy

Copy link
Copy Markdown
Contributor

Closes the Split MPF pipeline to 2 parts: deployment (deploy) and usage index file (Provider Directory) checkbox on HealthSamurai/smartbox#341.

Why

run-payerbox/provider-directory-pipeline.md sat outside the agreed IA (Run Payerbox = Architecture / Deploy / Maintain) and mixed three altitudes on one page: what the module publishes, how to deploy it, how to operate it. interop-apis/provider-directory.md never mentioned MPF, so a reader looking for the Medicare Plan Finder feed found nothing where they would look first.

What moved

Content New home
Buckets, sync client, access policy, env vars, export scope, first run, daily schedule run-payerbox/deploy.md## MPF provider-directory pipeline
Published artifacts, resource types, scope, crawl cadence, path choice interop-apis/provider-directory.md## MPF feed for Medicare Plan Finder
Endpoint contracts api-reference/operations/mpf-pipeline-api.md (stays, extended)

run-payerbox/mpf-pipeline.md is deleted. The old URL 301s to the new anchor.

The MPF section sits after Upgrade and uninstall so the mandatory runbook stays contiguous: with the section in the middle, Troubleshooting and helm upgrade payerbox read as if they belonged to the optional module.

Corrections, verified against backend/src/mpf in HealthSamurai/smartbox

These are factual fixes, not rewording:

  • Export scope is admin-editable. Settings → MPF, GET/PUT /admin/mpf/settings, persisted as a DocumentReference (routes/settings.ts, mounted at backend/src/index.ts:85). The page said scope ids were fixed in the image and changing them required a portal release.
  • The feed carries six resource types (pipeline.ts:37): InsurancePlan, Organization, Practitioner, PractitionerRole, Location, OrganizationAffiliation. HealthcareService and Endpoint stay REST-only. The composition was documented nowhere, while the Provider Directory page lists nine Plan-Net profiles.
  • MPF_STORAGE_ACCOUNT_ID is the id of an Aidbox account resource and is required on AWS and Azure (config.ts:81-84). The page called it the Azure storage account name and said it was unused on GCP.
  • MPF_PUBLIC_BASE_URL and MPF_FULL_URL_BASE are not required. Both fall back to built-in defaults, so an unset value publishes links to another deployment's base URL, which is worse than a failed start.
  • Missing variables added: MPF_EXPORT_STORAGE_PROVIDER / _BUCKET / _ACCOUNT_ID (needs Aidbox v2605+), MPF_DEFAULT_CONTRACT, MPF_DEFAULT_YEAR.
  • API reference gains the trigger error table (400/403/404/409/500), the settings endpoint, HEAD, Cache-Control, and the path-validation rules on the public endpoint.

Also added, from the module's own operational history: memory and ephemeral-storage headroom on the portal pod, the publish window where index.json briefly 404s, and the deliberate abort on an empty scope.

Deliberately not done

  • The MPF → compliance/cms-9115.md cross-link is dropped. CMS-9115-F covers the Plan-Net REST API; the Plan Finder feed is a different obligation and no regulatory anchor for it has been verified. The docs now make no regulatory claim about MPF. Worth settling separately.
  • The redirect target omits .md on purpose. normalizeRedirectUri in health-samurai-io-bun strips .md with an end-anchored regex, so deploy.md#anchor survives as .md and resolves to the raw-markdown endpoint (200, source dump). The same latent bug affects the five fhir-app-portal/smart-app.md#… entries already in redirects.yaml; they never fire only because their keys contain #.

Checks

bun lint clean. Rendered locally against the site: nav matches the IA, the anchor resolves, the old URL 301s to it.

…implementation

The MPF pipeline had its own page under Run Payerbox, outside the agreed IA
(Architecture / Deploy / Maintain), and mixed three altitudes: what the module
publishes, how to deploy it, and how to operate it. Provider Directory never
mentioned MPF at all, so a reader looking for the Medicare Plan Finder feed
found nothing there.

Split per the agreed IA, whose Deploy contract already covers "scope
configuration, env vars":

- Deploy gains a trailing "MPF provider-directory pipeline" section: buckets,
  sync client, access policy, env vars, export scope, first run, daily
  schedule. Placed after Upgrade and uninstall so the mandatory runbook stays
  contiguous and Troubleshooting keeps referring to the install.
- Provider Directory gains "MPF feed for Medicare Plan Finder": the published
  artifacts, the six resource types, scope, crawl cadence, path choice.
- run-payerbox/mpf-pipeline.md is gone; the old URL redirects to the anchor.

Corrections verified against backend/src/mpf in HealthSamurai/smartbox:

- Export scope is admin-editable (Settings -> MPF, GET/PUT /admin/mpf/settings,
  stored as a DocumentReference). The old text said scope ids were fixed in the
  image and changing them needed a release.
- The feed carries six resource types (pipeline.ts PHASE1_RESOURCE_TYPES);
  HealthcareService and Endpoint stay REST-only. The composition was documented
  nowhere.
- MPF_STORAGE_ACCOUNT_ID is the id of an Aidbox account resource, required on
  AWS and Azure (config.ts). The old text called it the Azure storage account
  name.
- MPF_PUBLIC_BASE_URL and MPF_FULL_URL_BASE are not required: both fall back to
  built-in defaults, which is the more dangerous failure.
- Added MPF_EXPORT_STORAGE_PROVIDER/_BUCKET/_ACCOUNT_ID (Aidbox v2605+),
  MPF_DEFAULT_CONTRACT, MPF_DEFAULT_YEAR.
- API reference gains the trigger error table (400/403/404/409/500), the
  settings endpoint, HEAD, Cache-Control, and path validation rules.

The MPF -> compliance/cms-9115 cross-link is dropped: CMS-9115-F covers the
Plan-Net REST API, not the Plan Finder feed, and no regulatory anchor for MPF
has been verified.

The redirect target omits the .md extension on purpose. normalizeRedirectUri in
the site repo strips .md with an end-anchored regex, so "page.md#anchor" would
resolve to the raw-markdown endpoint.

Refs #341

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@Nesmeshnoy
Nesmeshnoy requested review from Seryiza and glebmark August 3, 2026 10:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant