EVV & 21^st Century Cures Act Compliance¶

Golden Age Hub provides a comprehensive Electronic Visit Verification (EVV) engine fully compliant with the Medicaid 21^st Century Cures Act mandate (Section 12006). The platform combines edge-authenticated clock-in/out data, multi-channel verification, cryptographic proof-of-care hashing, and direct integration with major state aggregator open models.

🏛️ Regulatory Mandate Overview¶

Under Section 12006 of the 21^st Century Cures Act, states require personal care services (PCS) and home health care services (HHCS) funded under Medicaid to utilize Electronic Visit Verification. Golden Age Hub captures and cryptographically seals all 6 required data elements at the point of care:

+-------------------------------------------------------------------------------+
|                      6 MANDATED CURES ACT DATA ELEMENTS                       |
+-----------------------------------+-------------------------------------------+
| Mandated Element                  | Golden Age Hub Capture Mechanism          |
+-----------------------------------+-------------------------------------------+
| 1. Type of Service Performed      | HCPCS / CPT Code validation per visit     |
| 2. Individual Receiving Service   | Patient Medicaid ID & Encrypted Profile  |
| 3. Date of Service                | UTC ISO-8601 Timestamp from Verified Clock|
| 4. Location of Service Delivery   | GPS Haversine Radius & Fixed Geofencing   |
| 5. Individual Providing Service   | Caregiver NPI / State Identification ID   |
| 6. Service Begin & End Time       | Signed Device Clock-In & Clock-Out Events |
+-----------------------------------+-------------------------------------------+

📡 Multi-Channel Verification Methods¶

To handle non-tech-savvy caregivers, remote environments, and offline scenarios, Golden Age Hub supports three verification channels:

1. Mobile GPS Geofencing (Primary)¶

• Mechanism: Captures smartphone coordinates at clock-in and clock-out.
• Validation: Calculates the Haversine distance between caregiver coordinates and the patient's registered home address.
• Geofence Threshold: Configurable per agency (default: 200 meters). Visits outside the threshold are flagged into exception_pending status for supervisor review.

2. Fixed Object Token / TOTP FOB (Offline Fallback)¶

• Mechanism: For home visits with zero cellular connectivity, a physical TOTP hardware FOB (or on-device HMAC-SHA1 generator) displays a rolling 6-digit passcode.
• Validation: Caregiver records the code at clock-in/out. The backend verifies the passcode against the patient's shared secret key allowing up to 1-window clock drift.

3. Landline Interactive Voice Response / IVR (Telephony Fallback)¶

• Mechanism: Caregiver dials a toll-free IVR number from the patient's home landline.
• Validation: Matches the incoming Caller-ID against the patient's verified telephone number registered in the database.

🔄 State Aggregator Open Model Connectors¶

Golden Age Hub integrates directly with state-mandated Medicaid aggregators. Aggregator connectors format, validate, and transmit visit payloads via REST APIs or secure batch CSV/SFTP feeds:

                              +--------------------------+
                              |   Golden Age Hub Engine  |
                              +------------+-------------+
                                           |
                    +----------------------+----------------------+
                    |                      |                      |
            +-------v-------+      +-------v-------+      +-------v-------+
            |    Sandata    |      |  HHAeXchange  |      |    Tellus     |
            |  Open API     |      |   Aggregator  |      |   Connector   |
            +---------------+      +---------------+      +---------------+

Supported Aggregators¶

1. Sandata Open EVV: Supports real-time JSON REST transmission, account-level authentication, and Sandata-specific reason code mapping.
2. HHAeXchange: Supports batch CSV and JSON payloads formatted to HHAeXchange specifications.
3. Tellus / Netsmart: Supports Tellus visit import schemas and provider key authentication.
4. CareBridge & Generic REST: Configurable REST JSON endpoint exporter with custom date formatting (YYYY-MM-DDTHH:MM:SSZ vs compact YYYYMMDDHHMMSS).

⚠️ Exception Resolution & Compliance Engine¶

Auto-Verification Ratio (AVR) Monitoring¶

State Medicaid agencies require providers to maintain an Auto-Verification Ratio (AVR) of at least 85% (unmodified, real-time verified visits). Golden Age Hub provides real-time compliance widgets tracking: $\(\text{AVR} = \frac{\text{Auto-Verified Visits}}{\text{Total Completed Visits}} \times 100\%\)$

Exception Workflow & Reason Codes¶

When a visit fails automated geofencing or clock-in validation, it is placed in exception_pending status. Supervisors resolve exceptions via the /exceptions console:

1. State-Standardized Reason Codes:
2. 210: Device/Network Failure
3. 220: Caregiver Forgot Clock-Out / Clock-In
4. 230: Offsite / Emergency Care
5. 240: Patient Request / Location Exemption
6. 250: System Technical Issue
7. 260: Manual Administrative Entry Verified
8. Mandatory Audit Notes: Every manual resolution requires a descriptive audit note (minimum 10 characters), which is permanently hashed and attached to the visit's cryptographic ledger chain.

🧪 Test Verification & Implementation Links¶

All EVV Cures Act verification channels, aggregator export formats, and exception workflows are backed by explicit unit and integration test suites:

• EVV Cures Act Workflow Suite: backend/tests/test_evv_cures_act.py (Tests GPS Haversine calculation, TOTP FOB verification, landline IVR authentication, state aggregator formatting, and exception resolution).
• Visits API Endpoint Suite: backend/tests/test_visits_api.py (Tests CRUD operations, clock-in/out transitions, and exception resolution logic).
• Verification Status: Passed (All EVV & Visit test cases passing in standard test suite).

🔌 API Summary¶