Signal/CLAUDE.md

# STTIL Solutions — Signal | Active Build Context

## What This Tool Does
Signal is a B2B DMEPOS documentation readiness tracker for CGM suppliers.
It ingests order data from any DME order management CSV export (e.g., Brightree),
evaluates each patient against documentation requirements (6-month qualifying
visit, PECOS enrollment, SWO, resupply eligibility), and produces an actionable
worklist for supplier staff to prioritize outreach and capture revenue before it leaks.
NOTE: Signal identifies gaps. It does not conduct outreach. Never write copy
implying Signal contacts prescribers or patients directly.

## Core Value Proposition
Shifts supplier staff time from reactive (appeals after denial)
to proactive (preventing denial conditions).
The workload curve: appeals volume drops over time as proactive
coverage management replaces it. Outreach volume starts manageable
and stays predictable.

## PHI Architecture — Non-Negotiable
- STTIL never stores patient names, SSNs, DOBs, or contact info
- Sole crosswalk key: patient_id (DME's internal MRN or account #)
- DME staff maintain the patient_id ↔ real identity mapping locally
- AI/calculation layer sees: patient_id, device_type, shipment_date,
  quantity, payer — NOTHING else
- All logs use hashed patient_id, never raw

## Current Stack (Updated 2026-05-29)
- Backend: Railway (Python/FastAPI) — live at https://signal-api-production-91c2.up.railway.app
- Database: Supabase (PostgreSQL + RLS policies + Third Party Auth with Clerk)
- Auth: Clerk — app name: eternal-goblin-1, domain: eternal-goblin-1.clerk.accounts.dev
- Frontend: Vite/React (signal-ui) — local dev only at localhost:5173, NOT YET deployed publicly
- Orgs in Clerk: STTIL Solutions (default), Gaboro DME (org_3EPAEcAw06V2yGMSkxE3UjqIA3c)

## Run Commands
- Frontend (local): `cd signal-ui && pnpm dev` → localhost:5173
- Backend deploy (code change): `railway up --detach` from project root — forces fresh build
- Backend redeploy (no code change): `railway redeploy` — reuses existing image

## Active Files
- signal-ui/src/App.jsx — Clerk auth gate, OrganizationSwitcher
- signal-ui/src/components/WorklistTable.jsx — main worklist display
- signal-ui/src/components/CSVImport.jsx — CSV upload
- signal-ui/src/components/CSVExport.jsx — CSV export
- python-backend/core/coverage_calculator.py — gap detection logic (see Known Bugs)
- python-backend/core/audit_logger.py
- python-backend/core/persistence.py
- python-backend/core/supabase_client.py
- python-backend/api/main.py
- python-backend/api/normalizer.py
- python-backend/config/payer_rules.json

## Known Bugs — Fix Before Pilot
1. ~~**Payer matching**~~ — FIXED 2026-05-29. `_normalize_payer()` added to `coverage_calculator.py`. Handles: "Medicare Part B" → medicare, "Tricare for Life" / "TFL" → medicare, "Medicaid - GA" → medicaid, commercial insurer names → commercial.
2. **Visit date**: coverage_calculator.py uses shipment_date as proxy for qualifying visit, not an actual visit date. Fix: use stored confirmed visit date when available; fall back to shipment_date - 30 days labeled as estimated.

## Features Not Yet Built — Pilot Priority
- **Confirm Visit workflow**: staff button on each worklist row to record a confirmed visit date. Signal stores it against patient_id in Supabase. This is Signal's core persistent value — without it, visit dates never improve beyond estimates.
- **Frontend public URL**: DEPLOYED 2026-05-29 — https://signal-ui-xi.vercel.app
- **25 CSV variant test suite**: whitepaper requirement. Generate and test 25 mock CSVs with different column orders, headers, date formats, and payer name variants.
- **Mapping review interface**: confidence score display, user override dropdown per column (per whitepaper spec).

## Pilot Readiness — Authoritative Gauge
**Progress is measured against the whitepaper checklist only. Do not estimate % from feel.**

Whitepaper: `/Users/sttil-solutions/Documents/Obsidian_Vault/STTIL-Vault/Projects/2026-05-18-pilot-readiness-whitepaper.md`

### Checklist Status (as of 2026-06-07) — 45-50% pilot-ready

| Checklist Item | Status |
|---|---|
| App hosted behind stable URL | PASS — https://signal-ui-xi.vercel.app (deployed 2026-05-29) |
| Demo login / controlled access working | PASS |
| Synthetic sample data loads end to end | NOT VERIFIED as Gaboro org |
| 25 CSV variants pass ingestion tests | NOT DONE |
| Import flow: mapping, validation, warnings | PARTIAL — CSVImport exists, full mapping review unconfirmed |
| Report generation calculates from backend | PASS |
| Each status has reason + recommended action | PARTIAL — payer bug fixed; visit date still uses shipment proxy |
| Export CSV works and opens cleanly | NOT VERIFIED end to end |
| Placeholder content removed | NOT VERIFIED |
| Browser smoke test passes | NOT RUN |
| Data handling rules documented | PASS — privacy-policy.md + data-handling.md written 2026-06-07; minimum necessary fields, CSV disposition policy, retention, and payer_rules.json cadence all documented |
| Real PHI blocked | PARTIAL — architecture confirmed; Supabase plan tier (Pro vs Team) not yet verified |
| Pilot success metrics written down | PASS |

Update this table every build session. Re-count PASS items before quoting a % to anyone.

---

## Compliance Readiness Checklist

Source: `/Users/sttil-solutions/Documents/Obsidian_Vault/STTIL-Vault/Projects/2026-06-04-signal-compliance-whitepaper.md`

This checklist tracks compliance gates separately from build readiness. Update it alongside the pilot readiness table above.

### Gate: Pilot (before any supplier sees the product)

| Compliance Item | Status |
|---|---|
| HTTPS enforced across all surfaces | PASS |
| CORS locked to Vercel domain (ALLOWED_ORIGINS env var) | PASS |
| API key auth on upload and export endpoints | PASS |
| Clerk JWT validation active | PASS |
| Supabase RLS enabled | PASS |
| PHI fields (name, DOB, SSN) blocked at normalizer | PASS |
| patient_id as sole crosswalk key | PASS |
| SHA-256 hashed identifiers in all audit log entries | PASS |
| Service role keys absent from frontend env vars (VITE_) | PASS — verified 2026-06-05 |
| Railway-to-Supabase TLS | PASS — Supabase SDK manages SSL at infrastructure level |
| CSV file disposition post-normalization confirmed | PASS — raw bytes discarded; only hash + normalized records persist |
| Audit log WORM enforcement (RLS blocks UPDATE/DELETE on audit_log) | PASS — migration 20260607000001_audit_log_worm.sql applied via CLI 2026-06-07; audit_log table created with RLS + WORM policies live in Supabase |
| PostgreSQL as primary audit log retention sink documented (6-year) | NOT DONE |
| MFA confirmed on all admin accounts (AWS, Supabase, Railway, Vercel, Clerk) | NOT VERIFIED |
| payer_rules.json quarterly update cadence documented | PASS — documented in docs/compliance/data-handling.md 2026-06-07 |

### Gate: First Supplier (before Robert Robinson or any pilot partner uploads data)

| Compliance Item | Status |
|---|---|
| Privacy Policy published at stable public URL | PASS — privacy-policy.md written 2026-06-07; Privacy.jsx deployed to https://signal-ui-xi.vercel.app/privacy |
| FDA CDS exemption memo written and attorney-reviewed | NOT DONE |
| Supabase plan tier confirmed (Pro vs Team) and PHI posture documented | NOT VERIFIED |
| Pilot LOI reviewed by attorney | PARTIAL — template ready; Bittinger/Nixon review pending |
| NDA template reviewed by attorney | PARTIAL — template ready; Bittinger/Nixon review pending |
| Pilot LOI executed with supplier | NOT DONE |
| NDA executed with supplier | NOT DONE |
| Minimum necessary field documentation written (why each of 5 fields is required) | PASS — documented in docs/compliance/data-handling.md 2026-06-07 |
| Incident response procedure written (includes breach notification timeline) | PASS — docs/compliance/incident-response.md written 2026-06-07 |
| Data retention and deletion procedure written | PASS — retention and deletion policy documented in docs/compliance/data-handling.md 2026-06-07 |
| Deletion procedure tested against Gaboro test batch | NOT DONE |
| Internal tabletop incident exercise completed | NOT DONE |
| Production access scope documented (who has access and why) | NOT DONE |
| CMS AI governance quarterly monitoring cadence set (WISeR reminder) | NOT DONE |
| labABLE kit-in-kit arrangement reviewed for Anti-Kickback Statute exposure | NOT DONE — required before any labABLE agreement is executed |

### Gate: Real PHI (post-funding, before any direct patient identifiers enter the system)

| Compliance Item | Status |
|---|---|
| AWS RDS encryption at rest confirmed when activated | NOT DONE |
| Supabase upgraded to Team plan or replaced with AWS RDS | NOT DONE |
| Railway replaced with BAA-capable host (AWS ECS Fargate or equivalent) | NOT DONE |
| Full HIPAA Security Rule administrative safeguards review with attorney | NOT DONE |

### Gate: Token Layer (before Med Tracker starts)

| Compliance Item | Status |
|---|---|
| Token generation service built | NOT DONE |
| Crosswalk handoff protocol defined for clinic onboarding | NOT DONE |
| Signal updated to accept tokens instead of raw patient_ids | NOT DONE |

## What Is Tabled — Do Not Build Yet

| Item | Phase | Reason |
|---|---|---|
| AWS infrastructure | Post-pilot | Railway is sufficient until live PHI contracts signed |
| Dexcom OAuth API | Phase 2 | Requires vendor agreement + PHI scope expansion |
| Billing system API (Brightree, etc.) | Phase 2 | Build after pilot reveals which systems suppliers use |
| CMS / Salesforce integration | Phase 2 | Pilot feedback needed first |
| Prescriber fax automation | Phase 2 | Manual outreach sufficient for pilot |
| Patient-facing SMS | Phase 3 | PHI transmission requires BAA + consent layer |
| Doc upload + AI validation | Phase 2 | Explicitly deferred |
| Consortium strategy | 18-24 months | Need 15+ paying Level 1 suppliers first |

## Instructions for Claude Code Sessions
- Work only on pilot-scope items from the checklist above
- Never suggest adding PHI fields beyond patient_id
- Flag any vendor integration that would require a new BAA
- When building calculations, reference payer_rules.json for wear days
- When building audit logs, always hash patient_id before storing
- Use "resupply" not "refill" — CGM supply allowances are exempt from Medicare refill rules
- Always calculate progress against the whitepaper checklist table above — not subjective feel
- Before quoting any % complete to Kisa, count the PASS items in the checklist