Availity Claim Submission

1. What does this feature do? (High-Level Overview)

This feature covers the end-to-end Availity claim workflow used by billing users to generate claim batches, review clearing house connections, and submit professional claims through the configured billing connection for a location.

The current backend flow is professional-only. Institutional claim submission is no longer active, so the frontend should treat Availity as a single-path submission flow.

2. Who is this for? (Roles & Permissions)

• Users with manage_claims (for example, Manager/Owner): Can generate claim batches, review pending batches, send batches, download EDI files, and manage rejected batches.
• Users with manage_clearing_houses: Can configure and maintain the clearing house connection used for claim submission at the location level.
• Users with location access: Can only see and use claim submission data that belongs to the active location context.

3. Business Rules & Enforcements

• Rule 1: Availity submission uses the professional claim flow only.
• Rule 2: Institutional Availity submission paths are no longer active and should not appear in the frontend.
• Rule 3: Claim batches are the unit of submission. The frontend should not expose a single-claim Availity send flow.
• Rule 4: A batch can be sent only when the batch location has at least one active clearing house connection.
• Rule 5: If a location has multiple active clearing house connections, the sender must choose one before submission.
• Rule 6: The frontend should respect location scope when showing batches, clearing house connections, and submission actions.
• Rule 7: Rejected batches remain visible for review and possible reprocessing, but they should not be presented as successfully submitted.
• Rule 8: Generated claim data is normalized before batch submission, and the frontend should align with the updated Swagger schema for that payload.
• Rule 9: Any location filtering that was removed from Audit Log should also be removed from the frontend if it is still exposed there.

4. UI Placement

1. Billing / Claims > Batches: Main place to review pending batches, send them, download EDI, and inspect batch state.
2. Billing / Claims > Logs Report: Source screen for generating claim batches from note rows.
3. Location Settings > Clearing House Connections: Screen to manage the active submission connection per location.
4. Claim batch detail / EDI viewer: Used to inspect the generated batch payload and response details.

5. Recommended Workflow

1. Configure at least one active clearing house connection for the location.
2. Generate a claim batch from the Logs Report or review an already created pending batch.
3. Open the Batches list and confirm the batch is in pending state.
4. Send the batch using the active clearing house connection.
5. Review the resulting batch state, submission feedback, and any rejection details.
6. If the batch is rejected, correct the underlying data and recreate or resubmit as needed.

6. Functional Flow Summary

Claim generation

• Notes selected in Logs Report are normalized into a claim batch.
• The batch stores claim rows, service references, and totals for later submission.
• The frontend should show clear feedback when generation succeeds or fails.

Clearing house connection selection

• The active location determines which connections are available.
• If there is one active connection, submission should proceed with that connection.
• If there are multiple active connections, the frontend should prompt the user to choose one.

Batch sending

• Submission happens at the batch level.
• The frontend should display loading, success, and failure states clearly.
• If the backend returns a rejection or tracking response, the UI should surface the relevant status text and identifiers.

Audit log visibility

• The current backend no longer supports location filtering in Audit Log.
• If the frontend still exposes those filters, they should be removed or hidden.

7. Frontend Questions

Navigation and naming

• Should the frontend keep the label Availity in the UI, or rename the user-facing area to Claims / Claim Submission?
• Should the Availity flow live only under Billing > Claims, or does the frontend need a separate navigation entry?
• Should the send action be available only from the Batches list, or also from a batch detail screen?

Claim generation

• Should the Generate Claim action continue to live in the Logs Report toolbar?
• Do you want the frontend to show a preview of the generated batch before submission, or only after the batch is created?
• Should the frontend display the professional claim type explicitly anywhere, or keep it hidden because it is fixed by backend behavior?
• Should the UI remove any leftover institutional claim options, filters, or copy from forms, modals, and empty states?

Batch submission

• What should the send button look like when a batch has no active clearing house connection?
• Should the send action be disabled in that case, or should it stay enabled and fail only after submission?
• When multiple active connections exist, should the UI use a modal, dropdown, or stepper to choose the connection?
• Should the selected connection be remembered for the session, the location, or not remembered at all?
• Should the frontend show the connection label, provider name, or only the masked API key summary?

Status and feedback

• Which batch states should be shown to the user: pending, sent, rejected, failed, or additional values?
• Should rejections appear as inline row badges, toast messages, a drawer, or a modal detail panel?
• Do you want the frontend to surface the Availity tracking identifier, claim identifier, or both?
• Should submission errors be shown immediately as alerts, or only in the batch status area after refresh?
• Should the UI poll for status updates, or rely on manual refresh after submission?

Clearing house management

• Should the Clearing House Connections screen remain in the same location settings area?
• Should the frontend allow editing an existing connection’s status and label without re-entering the API key?
• What masked-value format should the UI use for saved API keys?
• Should the frontend show a warning when a location has zero active connections?
• Should the frontend warn when a location has more than one active connection?

Audit Log

• Should the location filter controls be removed entirely from the Audit Log UI?
• If the filter controls are removed, should the frontend also remove any related copy, helper text, and test fixtures?

API and generated client

• Will the frontend regenerate its API client from the refreshed Swagger spec?
• Are there any typed response models that still assume the old institutional Availity shape?
• Should the frontend consume the normalized claim data directly, or only the batch-level response?
• Do you want the frontend to keep compatibility shims for older payload shapes, or remove them immediately?

Testing and UX

• Which frontend tests should be updated to cover the professional-only flow?
• Do you want explicit tests for the multiple-connection chooser and the no-active-connection state?
• Should the empty state for the Batches list mention that only professional claims are supported?
• Should the send flow include a confirmation modal before submission?

8. Acceptance Criteria

• No frontend screen exposes institutional Availity submission as an active path.
• Batch submission works only through the professional claim flow.
• The UI handles one or many active clearing house connections per location.
• The frontend matches the refreshed Swagger contract.
• Audit Log does not expose unsupported location filters.
• The user can clearly understand when a batch is pending, sent, rejected, or blocked by configuration.

9. Notes for the frontend team

• Keep the scope focused on compatibility with the current backend flow.
• Avoid adding new UI for deprecated institutional behavior.
• Align labels, modals, and tests with the updated batch-based submission model.