Documentation Index
Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
Use this file to discover all available pages before exploring further.
Version: 1.0.0
Last Updated: 2026-04-09
Spec: PM-15 Phase 2 Expansion
Overview
Phase 2 adds live clearinghouse connectivity via Waystar REST API, replacing Phase 1 stubs with operational transport for claims submission (837P), remittance retrieval (835), eligibility verification (270/271), and acknowledgment processing (999, 277CA).
Architecture Decision: REST-only transport. SFTP is deferred due to Deno Deploy incompatibility with native SSH modules.
1. Credential Configuration
Edge Function Secrets
Clearinghouse credentials are stored as Edge Function Secrets (environment variables), not in the database.
| Secret Name | Purpose |
|---|
WAYSTAR_CLIENT_ID | OAuth2 client ID for Waystar REST API |
WAYSTAR_CLIENT_SECRET | OAuth2 client secret |
WAYSTAR_API_ENDPOINT | Base URL for Waystar API (e.g., https://api.waystar.com) |
Vault Reference Resolution
The pm_clearinghouse_config.credentials_vault_ref column stores a logical reference (e.g., vault://waystar/api-key). At runtime, the edge function resolves this to the corresponding Edge Function Secret.
2. Health Monitoring
Health Check Endpoint
clearinghouse-health-check runs every 30 minutes (cron) and updates pm_clearinghouse_config:
| Column | Description |
|---|
health_status | healthy, degraded, unhealthy, unknown |
last_health_check_at | Timestamp of last check |
Health Badge UI
The configuration list page displays a ClearinghouseHealthBadge next to each configuration. Colors use semantic tokens (text-success, text-warning, text-destructive).
3. Batch Submission Flow
Edge Function: clearinghouse-submit
- Reads batch from
pm_transaction_batches
- Generates X12 837P envelope using
envelope.ts + generate-837p.ts
- Acquires OAuth2 token via
rest-transport.ts
- Submits to Waystar REST endpoint
- Updates batch with trace number and status
- Logs transaction to
pm_transaction_log
Retry Logic
Failed submissions use exponential backoff:
- Max retries: 3
- Base delay: 1 second (doubles each retry)
- Dead letter: After max retries, batch marked as
error with transport_error
4. ERA Retrieval Flow
Edge Function: clearinghouse-retrieve
- Fetches pending 835 files from Waystar API
- Parses using
parse-835.ts
- Creates inbound
pm_transaction_batches record
- Logs each remittance to
pm_transaction_log
5. X12 Transaction Types
| Type | Direction | Generator/Parser | Edge Function |
|---|
| 837P | Outbound | generate-837p.ts | clearinghouse-submit |
| 835 | Inbound | parse-835.ts | clearinghouse-retrieve |
| 270 | Outbound | generate-270.ts | (Future) |
| 271 | Inbound | parse-271.ts | (Future) |
| 999 | Inbound | parse-999.ts | clearinghouse-retrieve |
| 277CA | Inbound | parse-277ca.ts | clearinghouse-retrieve |
6. Permissions
| Permission Key | Description |
|---|
pm.clearinghouse.view | View configurations, batches, transactions |
pm.clearinghouse.admin | Create/edit configurations, trigger submissions |
7. Troubleshooting
| Issue | Solution |
|---|
| Health badge shows “Unknown” | Health check hasn’t run yet or config is new |
| Batch stuck in “submitted” | Check transport_error column; verify secrets |
| OAuth2 token failure | Verify WAYSTAR_CLIENT_ID and WAYSTAR_CLIENT_SECRET secrets |
| 999 rejection | Check pm_transaction_log for error codes; correct and resubmit |
Edge Function Logs
- Submit: Supabase Dashboard → Edge Functions →
clearinghouse-submit → Logs
- Retrieve: Supabase Dashboard → Edge Functions →
clearinghouse-retrieve → Logs
- Health: Supabase Dashboard → Edge Functions →
clearinghouse-health-check → Logs
References
