108 lines
6.3 KiB
Markdown
108 lines
6.3 KiB
Markdown
# 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
|