# KwDose

> Evidence-based clinical decision support for Kuwait MOH primary care professionals.

KwDose is a web-based clinical toolkit designed for doctors, pharmacists, and medical students working in Kuwait's Ministry of Health primary care sector. All medication dosing content is verified against the British National Formulary (BNF) and BNF for Children (BNFC).

## Core Features

### Dose Calculator
Weight-, age-, and indication-based medication dosing references. Includes insulin pen/vial quantity estimations, renal and hepatic impairment considerations, pregnancy and breastfeeding safety information, minimum/maximum reference dose ranges, and Kuwaiti-only medication availability alerts (Qarar system).
- Route: `/?tab=calculator`

### Drug Interactions
AI-powered pairwise drug–drug interaction analysis. Checks each medication pair with severity ratings (Major, Moderate, Minor, None), mechanism explanations, and management recommendations. Sources include BNF, SmPC, and Lexicomp.
- Route: `/?tab=drug-interactions`

### Schedule Builder
Create printable, bilingual (English/Arabic) medication schedules with visual time indicators. Schedules can be shared via QR code or printed as professional patient handouts. Supports Ramadan-aware medication timing adjustments.
- Route: `/?tab=schedule`

### Smart Guidelines
Evidence-based clinical guideline references for common scenarios including Diabetes (ADA standards) and Dyslipidemia (ESC guidelines). Features streaming AI-generated summaries with drug-specific dosing recommendations, patient-parameter-driven lookups, and scenario-specific references.
- Route: `/?tab=guidelines-guides`

### Patient Assessment Guides (Chief Complaint Guides)
Clinical assessment frameworks based on "CSA Symptom Solver" for structured history-taking. Includes an AI Multi-Complaint Synthesizer that analyses combined differentials across multiple presenting complaints, identifies overlapping diagnoses, and highlights cross-complaint red flags. Also includes validated screening tools and clinical reference tools.

**Screening Tools:**
- GAD-7 (Anxiety): `/?tab=guidelines-guides&subtab=history-guides&guide=gad7`
- PHQ-9 (Depression): `/?tab=guidelines-guides&subtab=history-guides&guide=phq9`
- ACT (Asthma Control Test): `/?tab=guidelines-guides&subtab=history-guides&guide=act`

**Clinical Reference Tools:**
- **Insulin Comparison Tool** — Side-by-side insulin PK/PD comparison with smart insights
  - Route: `/?tab=guidelines-guides&subtab=history-guides&guide=insulin-comparison`
- **Antibiotic Spectrum Tool** — Visual antibiotic spectrum coverage maps with ecological impact ratings
  - Route: `/?tab=guidelines-guides&subtab=history-guides&guide=antibiotic-spectrum`
- **Antidepressant Switching Guide** — Cross-taper and switching technique references with half-life data
  - Route: `/?tab=guidelines-guides&subtab=history-guides&guide=antidepressant-switching`

- Route: `/?tab=guidelines-guides&subtab=history-guides`
- AI Analyzer: `/?tab=guidelines-guides&subtab=history-guides&analyzer=open`

### Lab Values
Laboratory result interpreter with reference ranges for common tests, critical value alerts, and AI-generated clinical significance insights.
- Route: `/?tab=lab-interpreter`

### Clinical Calculators
Essential clinical calculation tools:
- **GFR Calculator** — Estimate glomerular filtration rate (CKD-EPI)
- **BMI Calculator** — Body Mass Index with interpretation
- **CVD Risk Calculator** — 10-year fatal cardiovascular disease risk (ESC SCORE)
- **Creatinine Clearance** — Cockcroft-Gault equation
- **Body Surface Area (BSA)** — Multiple formula support
- **Cholesterol Ratios** — Lipid ratios for cardiac risk assessment
- **Insulin Conversion Calculator** — Dose calculation when switching insulin types
- Route: `/?tab=clinical-calculators`

## Additional Features

### KWiz
Interactive clinical quiz game with multiplayer support. Features category-based questions, real-time scoring, streaks, and leaderboards. Supports both solo and multiplayer game modes. Includes auto-generated daily quiz questions.
- Route: `/quiz`

### Patient Management
- Favorite medications for quick access
- Medication search with fuzzy matching and formulation browsing
- Saved patient schedules with medication lists
- Saved clinical guideline bookmarks
- Saved assessment guide bookmarks

### Feedback & Missing Medication Reporting
Users can submit general feedback and report missing medications to help expand the database.
- Route: `/feedback`

### Push Notifications
Push notification support via OneSignal for admin-sent alerts and updates.

### Calculation History
Track and review past dosage calculations for reference.

## Technology Stack

- **Frontend**: React 18, TypeScript, Tailwind CSS, Vite
- **UI Components**: shadcn/ui (Radix primitives)
- **Backend**: Supabase (PostgreSQL, Auth, Edge Functions, Realtime)
- **PWA**: Installable progressive web app with offline support
- **Native iOS**: Available via Despia wrapper for App Store distribution
- **Search**: Fuse.js fuzzy matching for medication lookup
- **PDF**: pdfjs-dist for PDF handling
- **Onboarding**: react-joyride for guided onboarding tours

## Routes

| Route | Description |
|-------|-------------|
| `/` | Main dashboard with feature grid |
| `/?tab=calculator` | Dose Calculator |
| `/?tab=drug-interactions` | Drug Interaction Checker |
| `/?tab=schedule` | Schedule Builder |
| `/?tab=guidelines-guides` | Smart Guidelines |
| `/?tab=guidelines-guides&subtab=history-guides` | Patient Assessment Guides |
| `/?tab=lab-interpreter` | Lab Value Interpreter |
| `/?tab=clinical-calculators` | Clinical Calculators |
| `/quiz` | KWiz clinical quiz game |
| `/auth` | Authentication |
| `/s/:shortId` | Shared schedule short links |
| `/feedback` | User feedback & missing medication reports |
| `/settings` | User settings & preferences |
| `/saved-guidelines` | Saved clinical guideline bookmarks |
| `/saved-history-guides` | Saved assessment guide bookmarks |
| `/favorites` | Saved patient schedules |
| `/delete-account` | Account deletion |
| `/privacy-policy` | Privacy policy |

## Data Sources

- **BNF** (British National Formulary) — adult medication dosing and safety
- **BNFC** (BNF for Children) — paediatric dosing
- **ADA** (American Diabetes Association) — diabetes management guidelines
- **ESC** (European Society of Cardiology) — dyslipidemia and CVD risk guidelines
- **Validated screening tools** — GAD-7 (Spitzer et al.), PHQ-9 (Kroenke et al.), ACT (Schatz et al.)

## API / Edge Functions

KwDose uses Supabase Edge Functions for server-side AI processing:

- **drug-interaction-checker** — Analyses pairwise drug interactions using OpenAI, returns severity-rated clinical recommendations
- **lab-insights** — Generates clinical interpretation of lab results including common causes and recommended actions
- **ada-diabetes-guidelines-streaming** — Streams ADA diabetes guideline responses with patient-specific context
- **dyslipidemia-guidelines-streaming** — Streams ESC dyslipidemia guideline responses with risk stratification
- **ai-multi-complaint-synthesizer** — AI multi-complaint synthesis for patient assessment guides
- **parse-medication-text** — Parses free-text medication lists into structured data for schedule building
- **send-push-notification** — Push notification delivery via OneSignal
- **generate-daily-quiz** — Auto-generates daily KWiz questions
- **send-welcome-email** — New user welcome emails
- **send-weekly-digest** — Weekly usage digest emails
- **create-short-url** / **redirect-short-url** — Schedule sharing short link creation and redirection
- **send-feedback** — User feedback submission
- **ramadan-timing** — Ramadan-aware medication timing adjustments

## Contact

KwDose is a clinical decision-support tool and does not replace professional medical judgement. All outputs should be verified by qualified healthcare professionals.