# 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=<known overdue
  NPI from our 217,968 list>` 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.
