aibilly_backend_code/docs/context/state_machine_and_badging.md

IamBilly Backend: State Machine & AI Confidence Logic

Claim State Machine

Claims must transition through the following 7 states:

1. RECORDED: Audio captured on mobile, upload confirmed.
2. TRANSCRIBING: AI engine (Whisper) is converting audio to text.
3. CODING: NLP engine is extracting entities and mapping ICD/CPT codes.
4. READY FOR REVIEW: AI processing complete; sitting in Biller's inbox.
5. APPROVED: Human biller/supervisor has verified the claim data.
6. REJECTED: Human biller rejected the claim (requires reason code).
7. EXPORTED: Claim successfully pushed to EMR or PDF generated. Final state.

AI Confidence Logic (Color Coding)

The processing layer must assign a confidence score to each extracted item:

• 🟢 Green (>90%): High confidence. Visual indicator for "Fast-Track" approval.
• 🟠 Orange (70-90%): Moderate confidence. Triggers a mandatory review highlight for the biller.
• 🔴 Red (<70%): Low confidence. System must provide the top 3 alternative mapping suggestions if confidence is between 70-80%, otherwise requires manual entry from scratch.