diff --git a/docs/plans/npi-healthcare-products-plan.md b/docs/plans/npi-healthcare-products-plan.md new file mode 100644 index 0000000..6d313f6 --- /dev/null +++ b/docs/plans/npi-healthcare-products-plan.md @@ -0,0 +1,113 @@ +# Plan — NPI / Healthcare Compliance Products + Site Pages + +## Goal +Build the full NPI/Healthcare compliance product line: ERPNext-backed ordering +(mirroring the FCC + trucking patterns), public service + order pages, and a free +NPI compliance-check lookup tool. **Exclude HIPAA** (separate specialty). All +ordering flows through the existing `compliance_orders` → ERPNext pipeline. + +## Scope / affected areas +The codebase defines a compliance service in ~5 coordinated places. We replicate +that for the new healthcare slugs: + +1. **API catalog** — `api/src/routes/compliance-orders.ts` + `COMPLIANCE_SERVICES` map (slug → name, price_cents, gov_fee, erpnext_item), + plus per-slug intake-required-fields and any slug-specific intake derivation. +2. **Intake manifest** — `site/src/lib/intake_manifest.ts` + `INTAKE_MANIFEST` (steps) + `SERVICE_META` (name/price) for each slug. +3. **ERPNext items** — `performancewest_erpnext/.../fixtures/item.json` + one Item per service (item_code must match the slug for worker dispatch via + `base_worker._resolve_service_slug`). +4. **Site pages (Astro)** — + - `site/src/pages/services/healthcare/*.astro` (marketing/service pages) + - `site/src/pages/order/*.astro` (order/intake wizard pages, copy cpni pattern) + - nav menu entry (add a "Healthcare" column to the Services dropdown). +5. **Worker handlers** — `scripts/workers/services/*.py` + registration in + `services/__init__.py` `SERVICE_HANDLERS` (keyed by slug). Start as + review-staged handlers (like FCC auto-filing-off default) since PECOS/NPPES + submission is manual initially. +6. **Free tool** — backend `api/src/routes/npi-lookup.ts` (mirror `dot-lookup.ts`) + + frontend `site/public/tools/npi-compliance-check/` (mirror dot tool) + an + `npi_*` data table (migration) loaded from the companion DBs we already pulled. +7. **Portal** — `performancewest_erpnext/.../www/orders.py` already renders a + generic compliance section; add the new slugs to `COMPLIANCE_SERVICE_LABELS` + and (optionally) a healthcare filing-field map for Filed/Overdue badges. + +## Product set (slugs, names, prices — from doc sec 6, HIPAA excluded) +| slug | name | price | +|---|---|---| +| `npi-revalidation` | Medicare PECOS Revalidation Filing | $399 | +| `npi-reactivation` | NPI Reactivation | $249 | +| `nppes-update` | NPPES Data Update / Attestation | $149 | +| `medicare-enrollment` | Medicare Enrollment (PECOS) | $499 | +| `medicare-reenrollment` / opt-out renewal | Opt-Out Renewal / Re-enrollment | $249 | +| `oig-sam-screening` | OIG/SAM Exclusion Screening (annual) | $99/yr | +| `caqh-attestation` | CAQH Profile Attestation/Maintenance | $249/yr | +| `provider-credentialing` | Payer Credentialing (per payer) | $199 | +| `provider-compliance-bundle` | Provider Compliance Bundle (annual) | $599–$899/yr | + +(Flagship = `npi-revalidation`; bundle = recurring revenue anchor.) + +## Approach (concrete ordered steps) +1. **Data layer for the free tool.** Add migration `npi_providers` (+ companion + tables: revalidation, exclusions, opt-out) loaded from the already-downloaded + free CMS/OIG files. Loader script under `scripts/workers/` mirroring the FMCSA + census downloader. Join key = NPI. +2. **Free lookup backend.** `api/src/routes/npi-lookup.ts`: + `GET /api/v1/npi/lookup?npi=` and `?name=`, returning checks + (revalidation overdue, NPI deactivated, exclusion flag, opt-out expiring, + stale NPPES) in the same `ComplianceCheck[]` shape as dot-lookup. +3. **Free lookup frontend.** `tools/npi-compliance-check/` cloned from the dot + tool (green/teal healthcare theme), pre-fillable `?npi=` for campaign links. +4. **Service catalog wiring.** Add all slugs to `COMPLIANCE_SERVICES` + (compliance-orders.ts) with prices + `erpnext_item` codes + intake-required + fields. Add matching `SERVICE_META` + `INTAKE_MANIFEST` entries. +5. **ERPNext items.** Add one Item per slug to `item.json` (item_code == slug). +6. **Order + service pages.** Generate `order/*.astro` (Wizard, copy cpni) and + `services/healthcare/*.astro` for each product; add Healthcare nav column. +7. **Worker handlers.** Add `scripts/workers/services/npi_*.py` handlers + (review-staged: generate packet + admin ToDo + email, like FCC auto-file-off), + register in `SERVICE_HANDLERS`. +8. **Portal labels.** Extend `COMPLIANCE_SERVICE_LABELS` (orders.py) so healthcare + orders render in the customer portal. +9. **Intake steps.** Reuse the generic `entity/review/payment` steps; add a small + NPI intake step component if NPI-specific fields are needed (NPI #, enrollment + ID). Most products can run on entity + review + payment. + +## Validation +- **Data/tool:** load companion data, hit `/api/v1/npi/lookup?npi=` and confirm it returns the overdue-revalidation + flag; confirm a deactivated NPI returns the reactivation check. Load the tool + page locally and run a lookup end-to-end. +- **Catalog:** unit-check that every new slug in `COMPLIANCE_SERVICES` has a + matching `SERVICE_META`, `INTAKE_MANIFEST`, ERPNext Item (item_code), and worker + handler in `SERVICE_HANDLERS` — write a small consistency check script that + fails if any slug is missing in any of the 5 places. +- **Order flow:** `POST /api/v1/compliance-orders` with a healthcare slug returns + an order_number; confirm row lands in `compliance_orders` with correct price. +- **Build:** `npm run build` in `site/` succeeds with the new Astro pages; nav + renders the Healthcare column; order pages load the Wizard. +- **Worker:** simulate a paid order and confirm the handler stages a review packet + + admin ToDo (no live PECOS submission). +- **Portal:** a seeded healthcare order shows in `/orders` with the right label. + +## Open questions / decisions +1. **Free tool data source.** NPPES is ~10M rows / ~1GB+. Load full NPI table, or + only the ~225k with revalidation due dates + ~491k with endpoints (smaller, + targeted)? Recommend: load the targeted subset first, expand later. +2. **NPI intake field.** Do we collect the provider's NPI at order time and + auto-pull their revalidation/exclusion status into the order? (Improves + fulfillment, small extra intake step.) +3. **Fulfillment reality.** PECOS revalidation/enrollment is done in CMS PECOS + (login). Confirm handlers stay review-staged (human files) initially — same + safety default as FCC auto-filing-off. Agreed? +4. **Bundle composition.** What exactly is in the $599–$899 Provider Compliance + Bundle (revalidation watch + OIG/SAM screening + NPPES upkeep)? Need final SKU. +5. **Recurring billing.** OIG/SAM screening + CAQH + bundle are annual + subscriptions — does the current order system handle recurring, or do we model + as annual one-time renewals (like CRTC maintenance)? Recommend annual one-time + to match existing patterns. +6. **Theme/brand.** Pick the healthcare accent color (telecom=blue, trucking= + orange, privacy=purple). Propose teal/green. +7. **Scope of first cut.** Ship flagship 3 (`npi-revalidation`, `npi-reactivation`, + `nppes-update`) + free tool first, then add the rest? Recommend yes.