# MediFlow Assistant: Healthcare Appointment Chatbot

## Overview

MediFlow Assistant is a Botpress-based chatbot design for hospital appointment support. The project focuses on reducing friction in common patient service tasks: booking doctor appointments, cancelling existing appointments, answering hospital FAQs, and collecting post-interaction feedback.

The work includes a working browser prototype, Hugging Face model inference demo, complete conversation architecture, Botpress variable strategy, workflow blueprint, multimodal response plan, testing matrix, and deployment approach for embedding the assistant on a hospital website through Botpress Webchat.

## Problem

Hospital front desks handle a high volume of repetitive appointment and information requests. Patients often need quick answers about departments, availability, required documents, insurance, parking, visiting hours, or appointment changes. A chatbot can reduce repetitive support load while giving patients a guided, consistent experience.

The design challenge was to create a chatbot that could:

- Understand whether the patient wants booking help, cancellation help, FAQ support, feedback, or staff handoff.
- Collect appointment details without repeatedly asking for information already provided.
- Route symptom-based requests to a likely department.
- Present confirmations clearly in both text and visual formats.
- Keep healthcare data collection limited to appointment-relevant information.

## Solution

I designed MediFlow Assistant as a modular Botpress workflow system with five main flows:

| Workflow | Purpose |
|---|---|
| Main / Greeting | Welcomes users, classifies intent, and routes the conversation |
| Appointment Booking | Collects patient, department, doctor, date, and time details |
| Appointment Cancellation | Identifies and confirms appointment cancellation requests |
| Hospital FAQs | Answers common hospital questions from a knowledge base |
| Feedback | Collects a rating and improvement comments after support |

The bot uses single-choice cards for structured actions and AI transition cards for free-text requests such as "I need to see a heart doctor" or "Can I cancel my appointment?"

The repository also includes a working JavaScript prototype that runs in the browser. It demonstrates the interaction model before the Botpress Studio build: users can book appointments, cancel prototype appointments, ask FAQs, leave feedback, and see local memory update in real time.

## ML Implementation

To make the project credible for an ML engineering profile, I added a model-backed routing demo with Hugging Face Transformers.js:

| Component | Implementation |
|---|---|
| Dataset | `data/intent_dataset.jsonl` with labeled intent and department examples |
| Model | `Xenova/all-MiniLM-L6-v2` sentence embeddings |
| Classifier | Nearest-centroid classifier over project examples |
| Outputs | Intent ranking, department ranking, confidence-style similarity scores |
| Evaluation | Leave-one-out evaluation written to `output/hf-demo-results.json` |

The verified run achieved `0.8571` leave-one-out accuracy across five intent classes: booking, cancellation, FAQ, feedback, and handoff. The first zero-shot MNLI attempt produced poor handoff-heavy predictions, so the implementation was changed to an embedding-based classifier that works better for the small project dataset.

## Conversation Memory Design

The memory model separates persistent user preferences from temporary appointment details:

| Scope | Example Variables | Why It Matters |
|---|---|---|
| User | `user.fullName`, `user.preferredDepartment`, `user.preferredDoctor` | Personalizes returning visits without restarting from zero |
| Conversation | `conversation.patientName`, `conversation.department`, `conversation.date`, `conversation.time` | Keeps the current appointment flow coherent |
| Workflow | `workflow.intent`, `workflow.feedbackRating`, `workflow.feedbackText` | Supports routing and short-lived workflow state |

This separation keeps the design practical for a healthcare context. The bot remembers useful preferences but avoids unnecessary long-term storage of sensitive medical details.

## AI and Multimodal Features

MediFlow Assistant includes AI-assisted and multimodal behaviors:

- Intent classification for booking, cancellation, FAQ, feedback, and handoff.
- Symptom-to-department mapping for requests like "knee pain" or "chest discomfort."
- Doctor profile cards with image captions.
- Appointment confirmation cards with doctor, department, date, time, and appointment ID.
- Text-only fallbacks when images are unavailable.
- Optional image captioning action for future support of uploaded documents or maps.

## Safety and Escalation

Because the use case is healthcare-adjacent, the bot design includes a clear emergency disclaimer and staff handoff path:

> If this is a medical emergency, please call emergency services or go to the nearest emergency department.

The assistant is designed for appointment support and general hospital information, not diagnosis or medical advice.

## Testing Plan

The test plan covers common and edge-case interactions:

| Test Area | Example |
|---|---|
| Intent routing | "I need an appointment" routes to booking |
| Symptom mapping | "I have knee pain" suggests Orthopedics |
| Memory behavior | Returning users can reuse saved name or department |
| Validation | Past dates trigger a request for a future date |
| Cancellation | Appointment ID requests route to cancellation confirmation |
| FAQ support | Visiting hours and document questions answer from the knowledge base |
| Multimodal fallback | Confirmation details remain available if images fail |

## Deployment Plan

The recommended deployment is Botpress Cloud Webchat embedded on a hospital website. This approach keeps the chatbot accessible from the existing patient-facing web experience and avoids requiring a separate frontend application.

Deployment steps include:

1. Build the workflows in Botpress Studio from the JSON blueprint.
2. Configure variables and knowledge base content.
3. Add doctor profile and confirmation card image responses.
4. Test booking, cancellation, FAQ, feedback, fallback, and emergency language.
5. Copy the Botpress Webchat embed script into the provided HTML template or hospital website.
6. Validate desktop and mobile behavior.

## Deliverables

- Working local chatbot prototype.
- Hugging Face embedding inference demo with generated evaluation output.
- Botpress workflow blueprint in JSON.
- Full implementation documentation.
- Webchat embed template.
- Portfolio case study.
- Resume-ready project descriptions and bullet points.

## Impact Statement

This project demonstrates the ability to design a practical AI assistant around a real service workflow, not just a generic chatbot. The architecture emphasizes clear routing, memory discipline, accessibility, fallback behavior, and deployment readiness.