12 KiB
12 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.
Current State (embedded — always in context)
ACTIVE: Build Spec Phase 2 DESIGNED — session-brain auto-write + insight extraction spec ready for Claude Code. NEXT: Claude Code builds Phase 2 (modify navaigate-session-brain SKILL.md). Pi stands by for verification.
Open threads (at wrap-up):
- LabABLE Meeting Fri 2026-06-26 1:30 PM — /pilot-prep.
- Build Spec Phase 2: Claude Code building now. Pi verifies after.
- TRUST FIXES STAGED: docs/compliance/privacy-policy.md (7yr→6yr, false BAA claim). Waiting Kisa go-ahead.
- 3 validation product blockers: MA misclassification, duplicate patient_id, doc-status override.
- Primary domain sttilsolutions.com still "Pending" in Clerk (non-blocking for auth).
At session START: use this section for state. Then read context/current-state.md for the full shared state (decisions, stack details).
At WRAP-UP: update this section AND context/current-state.md (keep both in sync).
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-06-22)
- 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 — production key deployed. Frontend:
pk_liveon Vercel. JWKS:clerk.sttilsolutions.com/.well-known/jwks.jsonon Railway. - Frontend: Vite/React (signal-ui) — deployed at https://signal-ui-xi.vercel.app
- 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-16) — 100% pilot-ready (13/13)
| 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 | PASS — verified as Gaboro DME org 2026-06-10 |
| 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 | PASS — mapping review step built 2026-06-10; confidence display, override dropdown, unmapped column notice, required-missing notice all implemented in CSVImport.jsx |
| Report generation calculates from backend | PASS |
| Each status has reason + recommended action | PASS — visit date proxy bug fixed 2026-06-09; _resolve_visit_date() implements full priority chain (CSV column > Supabase confirmed > shipment-30d estimate) |
| Export CSV works and opens cleanly | PASS — verified end to end 2026-06-10 |
| Placeholder content removed | PASS — StatCard undefined variables fixed 2026-06-09; empty state heading "Drop your file here" + StatusLegend below; stoplight colors + ✓ for Clear to Ship; tab counts and percentages; legend bar removed from worklist header — all deployed 2026-06-16 |
| Browser smoke test passes | PASS — CSV import, all filter tabs, Confirm Visit, Export all verified 2026-06-10; sidebar count sync fixed |
| 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 | PASS — architecture confirmed; Supabase Pro plan verified 2026-06-11 |
| 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 | PASS — Pro plan confirmed 2026-06-10 ($25/mo). HIPAA available as paid add-on on Team ($599/mo) — deferred to post-funding per Real PHI gate. Pro is correct posture for pilot. |
| 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