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	PASS — 50 new files generated (PA + NJ sets), 100% normalizer pass rate 2026-06-07
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