# 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