1. 📌 Overview & Purpose
Goal: Klinik kurangkan staf admin atau tingkatkan kapasiti tanpa hire. AI handle queue priority (triage colour-aware), appointment booking, WAHA reminder, billing automation, panel claim submit. Per Doc Zam mock: Registration Counter UI dgn Today's Queue · 12 patients · Insurance & Consent.
Standalone value: Klinik solo boleh subscribe untuk operasi automation walaupun belum guna AI clinical features.
2. 👤 User Stories
US-7.1 (Receptionist · Smart queue)
Pesakit walk-in: register cepat (auto-fill from M1 atau MyKad scan) · queue priority by triage colour from M1 · receptionist tap "Check-in" terus.
US-7.2 (Receptionist · Insurance verify)
Insurance card scan (AIA / MySalam) · auto-verify panel coverage · consent capture · sign on tablet.
US-7.3 (Admin · No-show)
AI predict pesakit risiko no-show (history · weather · distance) · WAHA T-7 + T-2 + T-1 reminder cascade · proactive call high-risk.
US-7.4 (Admin · Billing)
Encounter sign-off → auto-generate invoice · ICD-10 codes from M4 SOAP · panel claim submit (MySalam · Socso) · e-Invoice LHDN auto.
US-7.5 (Klinik owner · KPI)
Daily dashboard: pesakit hari ni · revenue · follow-up due · NPS · panel claim status · inventory low-stock.
US-7.6 (Pesakit · Reminder)
Saya forget appointment esok · WAHA reminder pagi-pagi · "Klik Confirm" untuk reschedule kalau perlu.
3. ✅ Functional Requirements
MUSTFR-7.1: Smart queue dgn priority by triage colour (M1 input · MERAH > KUNING > HIJAU)
MUSTFR-7.2: Appointment booking · slot finder · doctor availability · room conflict check
MUSTFR-7.3: WAHA WhatsApp reminder cascade (T-7 · T-2 · T-1 · day-of) · idempotent · opt-out respect
MUSTFR-7.4: No-show prediction (ML classifier · features: prior history · day · weather · distance · age · payment method)
MUSTFR-7.5: No-show intervention (proactive call list · book replacement standby slot · waitlist offer)
MUSTFR-7.6: Patient registration form (Doc Zam 11-section canonical · auto-fill from M1 atau MyKad scan)
MUSTFR-7.7: Insurance capture (AIA · MySalam · Allianz · panel) · OCR card scan · digital consent (e-sign on tablet)
MUSTFR-7.8: Auto ICD-10 coding (from M4 SOAP) → claim line · doctor confirm
MUSTFR-7.9: Panel claim submit (MySalam · Socso · private · API integration)
MUSTFR-7.10: e-Invoice LHDN auto-submit per encounter · UBL XML format · digital signature
MUSTFR-7.11: Daily KPI dashboard (pesakit · revenue · follow-up due · NPS · low-stock alert · panel claim aging)
MUSTFR-7.12: Resource scheduling (room · equipment · staff)
MUSTFR-7.13: Receipt generation (printed + WAHA digital copy)
SHOULDFR-7.14: Aging report panel claim (30/60/90+ days outstanding)
SHOULDFR-7.15: Patient self-service rebook via WAHA
SHOULDFR-7.16: Multi-cawangan view (group klinik aggregate KPIs)
4. ⚙️ Non-Functional Requirements
| Aspect | Target | Notes |
|---|---|---|
| Queue update latency | <500ms | Real-time WebSocket |
| WAHA delivery success rate | ≥95% | SMS fallback <5% failure |
| No-show prediction accuracy | ≥75% precision | Pilot baseline |
| e-Invoice submit latency | <10s post sign-off | Async OK if delayed |
| Panel claim submit success | ≥90% first-pass | Manual review <10% |
| OCR card scan accuracy | ≥95% | AIA/MySalam standard cards |
| Daily KPI refresh | <1min | Cached · materialized views |
5. 🗄️ Data Model
| Table | Key fields | Purpose |
|---|---|---|
appointments | id, patient_id, clinic_id, doctor_id?, start_at, end_at, status (booked · confirmed · checked-in · in-progress · completed · noshow · cancelled), source (M1 patient_pa · walk-in · web · waha) | Master |
queue_entries | appointment_id, queue_position, triage_color (from M1), checked_in_at, started_at, completed_at | Live queue |
waha_reminders | appointment_id, schedule_at, type (T-7/T-2/T-1/day-of), status, sent_at, replied, reply_action | Cascade |
noshow_predictions | appointment_id, prob_noshow, features_json, predicted_at, actual_outcome | ML model audit |
invoices | id, encounter_id, total_myr, items_json, payer (self/MySalam/AIA/...), status (draft/sent/paid/overdue), generated_at, paid_at | Billing |
panel_claims | id, invoice_id, panel_provider, claim_ref_no, status (submitted/approved/rejected/paid), submitted_at, approved_at, payout_amount | Insurance |
einvoice_submissions | id, invoice_id, lhdn_uuid, ubl_xml_url, status, submitted_at, validated_at | LHDN compliance |
resources | id, clinic_id, type (room/equipment/staff), name, available_hours_json | Resource scheduling |
6. 🔌 API + Integrations
POST /api/v1/admin/queue/checkin # patient walk-in or scheduled
PATCH /api/v1/admin/queue/{id}/reorder # admin re-prioritise
POST /api/v1/admin/appointments # create
PATCH /api/v1/admin/appointments/{id} # reschedule
DELETE /api/v1/admin/appointments/{id} # cancel
POST /api/v1/admin/waha/send # internal · cascade trigger
POST /api/v1/admin/waha/reply-webhook # patient reply handler
GET /api/v1/admin/noshow/predictions # today's high-risk list
POST /api/v1/admin/noshow/intervention # call · book replacement
POST /api/v1/admin/billing/{enc_id}/invoice # generate
POST /api/v1/admin/billing/claim-submit # panel
POST /api/v1/admin/billing/einvoice-submit # LHDN
GET /api/v1/admin/dashboard/kpi # daily metrics
GET /api/v1/admin/dashboard/aging-report
# Integrations
WAHA: HTTP API · WhatsApp Business
LHDN e-Invoice: UBL 2.1 XML · OAuth 2.0 token
MySalam claim: REST API · digital signature
Socso: SOAP/REST hybrid · CSV batch fallback
AIA / Allianz: per-insurer API
MyKad scan: OCR + AS400 NRIC validate (offline OK)
7. 🔁 State Machine
Appointment lifecycle:
BOOKED ──► WAHA_CASCADE_T-7 ──► T-2 ──► T-1 ──► CONFIRMED?
│
┌─────────────────────┤
▼ ▼
CHECKED_IN NO-SHOW
│ │
▼ ▼
QUEUE_ASSIGNED INTERVENTION_TRIGGERED
│ │
▼ ▼
IN_PROGRESS REBOOK_OR_CLOSED
│
▼
COMPLETED ──► INVOICE ──► PANEL_CLAIM ──► EINVOICE ──► PAID
Queue:
ARRIVE ──► PRIORITY_SORT (triage colour) ──► WAITING ──► CALLED ──► IN_ROOM ──► DONE
8. 🤖 Agent Specification
M7 mostly orchestration + ML model + integrations. LLM untuk: (a) WAHA reminder template generation BM/EN, (b) panel claim narrative auto-fill, (c) KPI insight summary.
- Models: Llama 8B untuk reminders + summaries · custom no-show ML classifier (XGBoost atau lightGBM)
- Memory: appointment history per patient · panel claim format library · LHDN UBL templates
- Guardrails: e-Invoice must validate before submit · panel claim doctor sign-off · WAHA opt-out respect
9. 🎨 UI/UX
Per Doc Zam mock slide 5 (Registration Counter): Queue list left · Patient Registration form right · Insurance & Consent below.
- Filament 3 Admin panel · 3-column dashboard layout
- Queue Board page (drag-to-reorder · color-coded triage badge)
- Registration form (Doc Zam canonical 11-section auto-fill)
- Insurance scan + e-sign tablet support
- Appointment calendar (FullCalendar 6 · doctor swimlanes)
- No-show predictions widget (today's high-risk · intervention button)
- Billing workspace (encounter list · claim status · aging)
- Daily KPI dashboard (revenue · pesakit · NPS · widgets ApexCharts)
10. ✔️ Acceptance Criteria
- AC-7.1: Queue priority correctly orders MERAH > KUNING > HIJAU walk-in scenarios
- AC-7.2: WAHA cascade delivery rate ≥95% · opt-out 100% respected
- AC-7.3: No-show prediction precision ≥75% on pilot 4-week baseline
- AC-7.4: Insurance OCR scan AIA/MySalam ≥95% accuracy
- AC-7.5: e-Invoice LHDN submit ≥98% first-pass · async retry on transient fail
- AC-7.6: Panel claim submit ≥90% first-pass approval (MySalam initial)
- AC-7.7: Daily KPI dashboard refresh <1 min
- AC-7.8: Receptionist time-to-checkin ≤45 saat for returning patient
- AC-7.9: Resource scheduling no double-booking detected
11. 🧪 Test Plan
| Tier | Cases | Coverage |
|---|---|---|
| Unit | Queue priority algo · WAHA cascade scheduler · ICD-10 mapper · UBL XML composer | ≥80% |
| Integration | End-to-end appointment → encounter → invoice → panel → e-Invoice | 100% paths |
| External integration | WAHA · LHDN · MySalam · Socso (sandbox) | 4 integrations · contract tested |
| ML model | No-show classifier · 4-week baseline data · precision/recall | P ≥75%, R ≥60% |
| OCR | 30 sample insurance cards · 5 brands | ≥95% accuracy |
| UAT | Receptionist 2 weeks · NPS | NPS ≥7 |
12. 🔗 Dependencies
- Hard: M9 (audit + RBAC) · 11-section Patient model · WAHA running
- Soft: M1 (intake source · triage input) · M4 (encounter trigger · ICD-10 source)
- External: e-Invoice LHDN API · MySalam API · Socso API · WAHA WhatsApp Business · Twilio SMS · OCR service (Google Vision atau local OCR)
13. 🏃 Sprint Allocation
Sprint 2.2 · 19 Jul - 1 Aug 2026 (2 minggu)
- Day 1-2: Filament Admin panel scaffold · Queue Board UI · drag-reorder
- Day 3-4: Appointment + WAHA cascade · reminder scheduler · opt-out workflow
- Day 5-6: No-show ML model · feature engineering · serve API
- Day 7-8: Insurance OCR + e-sign tablet · panel claim API integration (MySalam first)
- Day 9-10: e-Invoice LHDN · UBL XML · OAuth · digital signature
- Day 11-12: Billing workspace · aging report · daily KPI dashboard
- Day 13: Resource scheduling · multi-cawangan aggregator
- Day 14: E2E + UAT prep · sprint review
Capacity: 3 backend (1 LHDN/panel integration heavy) · 1 frontend · ML support · clinical SME consult
14. ⚠️ Module-Specific Risks
| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| WAHA WhatsApp ban or rate-limit | Med | 🟠 Reminder cascade fail | SMS Twilio fallback · multi-WAHA instance · in-app push notification fallback |
| e-Invoice LHDN API change | Med | 🟠 Compliance gap | Spec version monitor · monthly LHDN bulletin watch · adapter pattern · retry queue |
| Panel claim API friction (insurer) | Med | 🟢 Cash flow | Manual claim fallback · MySalam first then expand · API contract tested · monthly recon |
| No-show prediction false positive (annoy patient) | Med | 🟢 UX | Threshold tuned per-clinic · patient feedback loop · respect opt-out |
| OCR insurance card scan fail | Med | 🟢 Receptionist friction | Manual entry fallback · cards trained on 5 popular brands · admin train new brand |
| Queue gaming (skip line) | Low | 🟢 Trust | Triage colour from M1 (verifiable) · audit re-order · per-tenant policy |
| Multi-cawangan permission leak | Low | 🔴 PDPA | Tenant scope strict · per-cawangan RBAC · M9 cross-tenant audit |