ClarityMD

Inspiration

Orthopedic surgeons face a paradox of choice. Arthrex alone offers hundreds of specialized implants, fixation systems, and soft-tissue repair products — each with specific indications, patient profile requirements, and contraindications. In a busy clinical environment, no surgeon has time to search a catalog mid-consultation. We asked: what if the right procedure surfaced itself, ranked by how well it matches the patient in front of you?

ClarityMD was built to answer that question.

What It Does

A surgeon enters a patient profile — age, sex, diagnosis, activity level, and prior treatments — and selects the affected joint on an interactive anatomical body diagram. ClarityMD then:

Runs a TF-IDF machine learning ranking across 74 Arthrex procedures to find the best matches
Generates a clinical brief for the surgeon (structured Markdown, AI-authored)
Generates a plain-language summary for the patient
Renders an SVG anatomical diagram of the affected joint with key structures labeled

How We Built It

The architecture is a clean client-server split:

Frontend — React with a custom CSS design system. The body selector is a hand-coded SVG figure with clickable joint regions. Each joint also has a detailed zoomed SVG diagram (knee, shoulder, hip, ankle, elbow, wrist, spine, neck, hand) drawn entirely in code — no image assets.

Backend — Flask API with two distinct responsibilities:

ML Ranking: scikit-learn's TfidfVectorizer converts the patient's free-text diagnosis into a vector, then computes cosine similarity against every procedure in the catalog. The relevance score is:

$$\text{similarity}(A, B) = \frac{A \cdot B}{|A| \cdot |B|}$$

Procedures are ranked by this score and bucketed into confidence labels (Strong / Good / Possible Match) based on score thresholds.

AI Summaries: Groq's llama-3.3-70b-versatile receives the top-ranked procedures and patient profile, then generates two independent summaries — one clinical, one conversational. If Groq is unavailable, the ML rankings still render. The system degrades gracefully by design.

Data A custom JSON catalog of 74 Arthrex procedures, each with product name, category, technique notes, recovery timeline in weeks, and contraindications. The SQLite database auto-seeds from this file on first startup.

Challenges We Faced

The API disappeared mid-hackathon. We originally built around the Anthropic Claude API. Midway through, it became unavailable. We had to rearchitect the AI layer to use Groq.

A silent encoding bug cost us debugging time. VS Code saved our .env file with a UTF-8 BOM (byte order mark — three invisible bytes: 0xEF 0xBB 0xBF). The python-dotenv library read the key name as \ufeffGROQ_API_KEY instead of GROQ_API_KEY, so the key silently resolved to None. Every API call returned 401. The fix was writing the .env without BOM using PowerShell: