b52b258b8f
- Add supabase/ to .gitignore (local CLI config should not be committed) - Create and apply migration 20260607000001_audit_log_worm.sql via CLI: creates audit_log table with RLS enabled + INSERT/SELECT policies + WORM policies that block UPDATE and DELETE on all rows - Update CLAUDE.md compliance checklist: audit_log WORM marked PASS Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
10 KiB
10 KiB
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 --detachfrom 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
Payer matching— FIXED 2026-05-29._normalize_payer()added tocoverage_calculator.py. Handles: "Medicare Part B" → medicare, "Tricare for Life" / "TFL" → medicare, "Medicaid - GA" → medicaid, commercial insurer names → commercial.- 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