​

Ruby for Reception — Cockpit Design

​

1. Problem

​

2. Architecture

                      Receptionist UI
                            ▲
              ┌─────────────┴──────────────┐
              │  Reception Cockpit (React) │
              └─────────────┬──────────────┘
                            │
                            ▼
              ┌───────────────────────────┐
              │   Surface endpoints       │
              │  (Hono routes /reception) │
              └─────────┬─────────────────┘
                        │
        ┌───────────────┴────────────────┐
        ▼                                ▼
┌──────────────────┐          ┌──────────────────────┐
│ Deterministic    │          │ Ruby narrator        │
│ SQL aggregator   │ ───────▶ │ (deepseek-v4-flash   │
│ (Drizzle, indexes│          │  via Langfuse)       │
│ on clinic+date)  │          │                      │
└──────────────────┘          └──────────────────────┘
        │                                │
        ▼                                ▼
  facts, ids, scores            paragraphs, drafts,
  (cacheable per clinic)        classifications

• Deterministic SQL is fast, cheap, free, and fully predictable — perfect for “who needs follow-up” decisions.
• Ruby is good at narration, tone, classification, summarization — bad at deciding who to message.
• Ruby never reads PHI without a deterministic gate (consistent with existing decryptPatientPHI pattern in appointment-nudges.ts).

​

3. Model & Cost

• 1M context (was 128K) — full patient history + clinic config fits with room
• $0.14/M input cache miss, **$0.0028/M cache hit** (50× cheaper)
• $0.28/M output (was$0.40)
• Native JSON mode + tool calls
• response_format: { type: 'json_object' } supported as today

• Morning brief: 1 call/day, ~2K input + ~500 output = $0.0004
• Prep hints: 40 calls/day, mostly cache hits on system prompt (~3K stable + ~200 variable input) + ~80 output ≈ $0.001 total
• Patient snapshot: ~20 lookups/day, ~1K input + ~150 output = $0.003
• EOD reconciliation: 1 call/day, ~2.5K input + ~400 output = $0.0005
• Total: < $0.01/day per clinic at steady state. Pennies.

• System prompt stays byte-identical across calls of the same surface (managed by Langfuse, fetched once per worker isolate via 300s TTL cache)
• User message starts with a stable schema-reminder header, then the per-call JSON payload
• Track prompt_cache_hit_tokens / prompt_cache_miss_tokens in Langfuse metadata for cost monitoring

​

4. Prompt Management — Langfuse

• appointment-nudges — reused by Today’s Queue badge logic
• payment-reminder-msg — used when reception clicks “draft balance reminder”
• patient-recall-msg — used by EOD Reconciliation when a recall is overdue
• daily-clinic-brief — owner-facing daily brief; distinct from reception morning brief

1. Add new prompts to server/src/lib/ai/prompts.ts (PROMPTS + PROMPT_NAMES)
2. Run npx tsx server/src/scripts/sync-prompts-to-langfuse.ts (existing script)
3. Verify with --dry-run first, then push for real
4. Spot-check in Langfuse dashboard: each prompt should be on label production, version bumped

1. Three-tier structure: System role + JSON schema + Rules (matches existing house style)
2. The word “json” must appear in the system prompt (DeepSeek JSON-mode requirement)
3. Concrete JSON example baked in
4. Ruby brand, never “AI” or “Action Items”
5. PKR with commas
6. No emojis in patient-facing output
7. Empty array / empty string preferred over fabrication
8. Stable text — never embed per-call data in the prompt template; that comes via user message

​

5. Phase 1 surfaces (ship now)

​

5.1 Morning Brief

{
  "date": "2026-05-23",
  "dayName": "Saturday",
  "receptionistName": "Aisha",
  "appointments": {
    "totalToday": 38,
    "confirmed": 12,
    "unconfirmed": 26,
    "firstVisits": 4,
    "withBalance": 7,
    "highNoShowRisk": 3,
    "unassignedDoctor": 38,
    "topRiskPatients": [
      { "first": "Ahmed",  "time": "17:30", "reason": "missed last 2 visits"  },
      { "first": "Fatima", "time": "19:00", "reason": "4-week-out booking, no confirm"  }
    ]
  },
  "balances": { "expectedCollections": 42000, "patientsOwing": 7, "topOwed": [ { "first": "Sara", "balance": 18000 } ] },
  "recalls": { "dueToday": 2, "overdue": 5 },
  "operations": {
    "doctorsAvailable": 1,
    "doctorScheduleGaps": ["No schedule defined for Dr. Khan — assignment will fail"],
    "inventoryLow": 0
  }
}

{
  "greeting": "Good evening, Aisha — busy Saturday ahead.",
  "headline": "38 appointments today, 26 still unconfirmed. Priority: lock confirmations before 16:00.",
  "priorityList": [
    { "action": "Call 26 unconfirmed patients", "deepLink": "/dashboard?view=appointments&status=scheduled", "rationale": "26 unconfirmed booked for tonight" },
    { "action": "Watch for Ahmed (17:30)", "deepLink": "/dashboard/appointments/<id>", "rationale": "missed last 2 visits — confirm by SMS first" },
    { "action": "Collect PKR 18,000 from Sara at desk", "deepLink": "/dashboard?view=finance-invoices", "rationale": "balance from prior visit" }
  ],
  "operationalAlerts": ["38 appointments have no doctor assigned — pick a doctor when checking in or auto-assign to Dr. Khan"]
}

no_show_risk = clamp(
    0.40 * (per_patient_missed_90d / per_patient_appts_90d * 100)
  + 0.25 * (days_since_booked >= 14 ? 1 : 0) * 100
  + 0.15 * (first_visit ? 1 : 0) * 100
  + 0.10 * (outstanding_balance > 0 ? 1 : 0) * 100
  + 0.10 * (late_arrivals_last_3 * 33)
, 0, 100)

​

5.2 Today’s Queue prep hints

{
  "appointments": [
    { "id": "appt_xx", "first": "Ahmed", "time": "17:30", "type": "Root Canal",
      "isFirstVisit": false, "hasConsent": true, "balanceOwed": 0, "doctorAssigned": false,
      "roomAssigned": false, "noShowRisk": 78, "lastVisit": "2026-04-19", "lastProcedure": "Filling 16M" }
  ]
}

{
  "hints": [
    {
      "appointmentId": "appt_xx",
      "tone": "warn",
      "hint": "Likely no-show — confirm by SMS now. Continuing RCT on #16; assign a doctor before chair time.",
      "flags": ["no-doctor", "no-room", "high-risk"]
    }
  ]
}

​

5.3 Patient Snapshot

​

5.4 EOD Reconciliation

{
  "date": "2026-05-23",
  "unclosedConfirmed": [
    { "id": "appt_a", "first": "Hira",  "time": "15:00", "type": "Check-up" }
  ],
  "completedNoInvoice": [
    { "id": "appt_b", "first": "Bilal", "type": "Crown",  "estimatedFee": 25000 }
  ],
  "missedToday": [
    { "id": "appt_c", "first": "Zara",  "time": "16:30", "phoneOnFile": true }
  ],
  "balancesCollectedToday": 12000,
  "balancesExpectedToday": 42000
}

{
  "summary": "3 visits still in confirmed — looks like Hira's check-up never got closed. 1 completed visit (Bilal, Crown) hasn't been invoiced. 1 patient missed and is reachable by WA.",
  "batchActions": [
    { "label": "Mark 3 visits as completed",     "endpoint": "POST /reception/eod/close-confirmed", "ids": ["appt_a", "..."], "tone": "info" },
    { "label": "Generate invoice for Bilal (Crown)", "deepLink": "/dashboard/appointments/appt_b#invoice", "tone": "warn" },
    { "label": "Send recovery message to Zara",  "deepLink": "/dashboard/appointments/appt_c#recover",   "tone": "info", "disabledReason": "WhatsApp send not yet configured" }
  ],
  "tomorrowSetup": "26 appointments tomorrow already unconfirmed — schedule a 09:00 call block."
}

​

6. Phase 2 surfaces (when WA send lands)

• Follow-Up Drafter (reception-followup-drafter): given a list of patients flagged by deterministic SQL (missed today, unconfirmed tomorrow, recall due, outstanding balance), Ruby drafts per-patient WA message with reschedule slot suggestions. Deterministic layer provides the slots.
• Triage Inbox (reception-triage-classifier): inbound WA messages classified (booking-request / question / complaint / no-action) with suggested 1-click replies. Confidence threshold below 0.7 → human review.
• D from prior brainstorm = subset of Follow-Up Drafter (the “missed today” cohort).

​

7. Data model changes

• appointments (clinic_id + appointment_date indexed)
• invoices (balance + status)
• patients (last_visit derived)
• tenant_daily_briefs (already exists for daily brief caching)
• clinic_operating_hours / clinics.operating_hours

​

8. API surface (Phase 1)

• Require receptionist, admin, or doctor role
• Clinic scope enforced via getClinicIdFromContext
• PHI decrypted server-side, never sent raw to Ruby (deterministic aggregator already handles this in appointment-nudges.ts — copy the pattern)

​

9. UI surface (Phase 1)

1. MorningBriefCard — new component at top, above existing KPI cards. Collapsible. Shows greeting + headline + priority list with deep links.
2. Today’s appointments table — add a new Prep column rendering the badge + hover tooltip with the hint. Existing rows untouched.
3. EOD Reconciliation button — new “Wrap up day” CTA in the header. Opens a modal with the Ruby summary + batch action buttons.
4. Patient drawer — keep using existing patient brief endpoint (no change in Phase 1).

​

10. Eval & observability

• All Ruby calls already traced via client.ts — extend metadata to include surface (“morning-brief” | “prep-hint” | “eod”) and cacheHitRatio (computed from prompt_cache_hit_tokens)
• Per-surface dashboards in Langfuse for cost, latency, p99 token count
• Eval dataset: collect 50 Dental Square brief renders over 1 week, human-rate on a 1-5 scale, set up Langfuse experiments to compare prompt versions

• DeepSeek returns empty content (documented failure) → retry once; if still empty, show deterministic-only fallback (“38 appointments today, 26 unconfirmed” — no narration)
• Langfuse getPrompt throws → fall through to hardcoded prompt in prompts.ts (existing pattern)
• Ruby JSON parse error → log to worker_logs, render deterministic fallback

​

11. Migration plan

1. Push 3 new prompts to Langfuse (reception-morning-brief, reception-prep-hint, reception-eod-reconcile)
2. Switch model default in client.ts to deepseek-v4-flash
3. Re-push existing prompts to ensure they’re current on the new model context (no edits, just version bump): daily-clinic-brief, patient-brief-summary, appointment-nudges, payment-reminder-msg, patient-recall-msg, churn-reengagement-msg, treatment-followup-msg, revenue-forecast-insight, monthly-performance-summary, clinical-notes-soap, note-rewrite, note-grammar-check, note-shorten, note-expand, treatment-plan-presentation, superadmin-tenant-daily-brief. Skip DICOM — uses GPT, not DeepSeek.
4. Smoke test on Dental Square: trigger morning brief, render today’s queue, run EOD reconciliation. Confirm Langfuse traces show prompt_cache_hit_tokens > 0 after second call.
5. Build endpoints + UI per Section 8–9.
6. Ship behind feature flag reception_cockpit_v1 on clinic_modules. Roll out to Dental Square first; observe 1 week; then enable for other reception-using clinics.

​

12. Scope this spec covers

• 3 new Langfuse prompts (authored + pushed)
• 16 existing prompts re-pushed (untouched content, version bump)
• Model default flip to deepseek-v4-flash
• Spec for Phase 1 surfaces (Morning Brief, Prep Hints, EOD Reconciliation; Patient Snapshot reuses existing)

​

13. Scope this spec does NOT cover

• DICOM prompt or model (GPT-based, untouched)
• WhatsApp send integration
• Follow-Up Drafter and Triage Inbox prompts (Phase 2)
• Reception cockpit UI build-out (separate plan via writing-plans)
• API route implementation (separate plan via writing-plans)
• Smart booking (C from prior brainstorm — explicitly out of scope per user)

​

14. Risks

​

15. Open questions