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-05-29) — 40-45% 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
Real PHI blocked	PASS
Pilot success metrics written down	PASS

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

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