Drug Quiz — USMLE Step 1 Pharmacology

A gamified, modular drug-learning app for medical students. Live at https://croblesmed.github.io/drugs-quiz/ Inspired by Amino Acid Quiz.

457 drugs across 11 subjects. Pick a subject, pick which attribute is the question and which is the answer, then match drugs against six choices.

npm install
npm run dev        # local dev server
npm run validate   # check every drug database
npm run build      # validates, then builds to dist/

See DRUG_DATA_GUIDE.md. Short version: every drug lives in src/data/topics/<subject>.json. Add a drug by appending an object to the drugs array. Add a subject by dropping in a new JSON file — it appears on the home screen automatically. Drug class colors, the class list, and the tag list are all derived from the data; you never configure them.

Run npm run validate after editing. It fails the build on missing fields, duplicate ids, or too few distinct values to build answer choices.

src/
  App.jsx                    screen routing: topics → setup → game → results
  components/
    TopicSelect.jsx          home screen, subject grid with per-topic best score
    StartScreen.jsx          drug-set filters (multi-select) and quiz mode
    GameBoard.jsx            question card, 6 answer cards, ✓/✗ tally
    AnswerCard.jsx           one answer choice
    ResultsScreen.jsx        score, drug tile grid, missed-only filter
    ScoreBar.jsx             fixed top bar with running tally
    TooltipModal.jsx         full drug detail sheet
  data/topics/
    index.js                 auto-discovers every .json in this folder
    *.json                   one file per subject — the entire content layer
  hooks/
    useGameSession.js        useReducer game state machine
    usePersonalBest.js       localStorage, keyed by topic + filter + mode
  utils/
    distractors.js           answer-choice construction and collision handling
    classColors.js           automatic per-topic class colors, class/tag lists
scripts/
  validate-data.mjs          data integrity checks, runs before every build

The Drug Quiz App is a matching-game flashcard system built around a single core loop: you are shown one attribute of a drug, and you must select the correct match from 6 answer choices. Every round covers the entire drug set you've selected, and your goal is to get a perfect score. The game is designed to be fast, visually clean, and deeply satisfying to complete — like Amino Acid Quiz, but for pharmacology.

Current scope: 457 drugs across 11 subjects covering the pharmacology tested on USMLE Step 1. Adding a subject requires only a new JSON file in src/data/topics/ — no code changes.

Target users: Medical students preparing for USMLE Step 1 and preclinical coursework.

Target platform: A static web app deployed to GitHub Pages — accessible via a shareable link that opens in any browser on iPhone or desktop. No app store, no install required. Optionally configured as a PWA (Progressive Web App) so the user can add it to their iPhone home screen and use it offline.

1. The user arrives at the Start Screen, reviews their past scores, selects a drug set and quiz mode, and taps Play.
2. The app shuffles the drug set and begins presenting drugs one at a time.
3. Each round: one attribute is shown as the question. Six answer choices are shown as tappable cards. The user taps one.
4. The answer is immediately revealed — correct flashes green, incorrect flashes red (and the correct answer also highlights green). The drug name then shows a tappable tooltip with its clinical summary.
5. Wrong answers are noted but not recycled within the same session. Every drug appears exactly once. The goal is to learn the correct answer and aim for a better score next game.
6. When all drugs have been shown, the Results Screen appears: a tile grid of all drugs, color-coded by drug class, showing a ✓ or ✗ on each tile. Score and personal best are prominently displayed.

All drug data lives in topic-specific JSON files under src/data/topics/. These files are human-readable and editable without touching any code. New subjects are added by dropping in a new JSON file — index.js discovers it automatically, and drug-class colors, class lists, and tag lists are all derived from the data. See DRUG_DATA_GUIDE.md.

Some attributes are shared across drugs (e.g., two drugs in the same class may share a mechanism). The app handles this in two ways:

• Prevention: The distractor-selection algorithm prefers distractors where the answer attribute value differs from the correct answer, minimizing collisions.
• Resolution: If two drugs genuinely share the exact same value for the answer attribute and both appear in the same question's answer bank, both are marked as correct. Selecting either counts as a correct answer for that round. This is explicitly surfaced to the user ("Multiple correct answers possible").

Every quiz mode pairs the drug Name on one side with one other attribute on the other. The user selects which side Name is on:

• Name → Attribute: The drug name (+ emoji) is the question. Six values of the chosen attribute are the answer choices.
• Attribute → Name: A drug attribute value is the question. Six drug names (+ emoji) are the answer choices.

No quiz mode pairs two non-name attributes against each other.

Even when the same game mode is selected again, the experience should feel varied:

• Drug order is shuffled each game.
• Distractor selection is randomized from the eligible pool each game (not fixed).
• The result: the same quiz mode played twice will have different ordering and different wrong answer choices.

• The score counter (e.g., 14 / 42) is always visible in the top bar during gameplay.
• Personal best per (drug set + quiz mode) configuration is stored locally and shown on the Start Screen and Results Screen.
• A perfect score triggers a distinct celebration animation.

Each drug has a unique 3-emoji combination displayed alongside its name throughout the app. Emojis are chosen to be thematically suggestive of the drug's effect or class. Every combination must be globally unique across all topic modules. Emojis are stored in the data file, assigned once, and never auto-generated.

All drug names in the database and UI use generic (INN) names exclusively. Brand names are never shown anywhere in the app.

For high-yield fields like side effects and contraindications, the stored value must include all clinically significant, exam-relevant entries — not a random subset. These fields are particularly important for USMLE Step 1 and should not be abbreviated.

Attribute values should be as brief as possible while remaining complete. Use comma-separated lists for multi-value fields. Mechanisms are 1–2 sentences maximum.

The Start Screen is the app's home. It shows:

1. App title and logo
2. Personal best scores — a compact table or card showing the user's top scores by quiz mode (e.g., "Name → Mechanism: 38/42 ✦")
3. Drug set selector — choose which drugs to include:
   • All cardiology drugs
   • Filter by drug class (e.g., Beta-blockers, ACE Inhibitors, Antiarrhythmics)
   • Filter by topic tag (e.g., Heart Failure, Hypertension, Arrhythmias)
   • In future versions: combine multiple topic modules (e.g., Cardiology + Psychiatry)
   • The total count of selected drugs is shown (e.g., "42 drugs")
4. Quiz mode selector — two dropdowns or segmented controls:
   • Question type: Name | Drug Class | Primary Effect | Treatment Usage | Mechanism of Action | Side Effects | Contraindications
   • Answer type: same list
   • Constraint enforced in UI: exactly one of the two must be "Name." Selecting non-Name for both is blocked with an inline message.
5. Play button — launches the game with the current configuration

Each round:

1. Display the question (drug name + emoji, or attribute value).
2. Display 6 answer cards — one correct, five distractors (or fewer if pool is small, minimum 3).
3. User taps a card.
4. Immediately:
   • Correct tap → that card turns green, score increments, brief animation.
   • Incorrect tap → that card turns red, correct card(s) pulse green.
5. A tooltip trigger appears on the drug name. Tapping it opens a modal with the drug's ≤50-word clinical summary, plus all attribute values for review.
6. A "Next →" button advances to the next drug. There is no retry; wrong answers are recorded and reviewed at the end.

• +1 for a correct first tap. 0 for an incorrect tap.
• Score visible throughout in top bar.
• No partial credit, no retries mid-game.
• At game end: score, personal best, and any improvement are shown.

For each round, the 6 answer choices are assembled as follows:

1. Insert the correct answer (the true attribute value for the drug being quizzed).
2. Scan for shared-value collisions. If any other drug in the active set shares the exact same value for the answer attribute, mark it also as correct. The shared value appears only once in the answer bank but both underlying drugs are flagged as acceptable.
3. Fill distractor slots (up to 5 wrong answers) using this priority:
   • First, prefer drugs from the same drug class as the correct drug — these are the most educationally meaningful distractors.
   • If insufficient same-class options exist, pull from the same topic tag.
   • Fill remaining slots from the broader active drug set.
4. Randomize the selection within each priority tier every game (so distractors differ between sessions).
5. Shuffle the final 6 cards before display.

After each round, the drug name is shown with a small info indicator. Tapping opens a modal with:

• Drug name + emoji (large)
• ≤50-word clinical summary (the tooltip field)
• All attribute values listed for that drug (class, mechanism, treatments, side effects, contraindications)
• Dismisses on tap outside or a close button

If the user answers incorrectly, they see the correct answer, then move on. The app is designed for repeated play — the incentive to improve is the score and personal best system, not in-session correction. This preserves the integrity of the completion score.

The Results Screen appears after all drugs have been answered. It contains:

• Large Score / Total display (e.g., 38 / 42)
• Personal best for this configuration
• Delta from personal best (e.g., "+3 from your best")
• Perfect score triggers a full-screen celebration (confetti or similar)

Every drug in the active set is shown as a tile in a responsive grid (similar to the Amino Acid Quiz end screen). Each tile shows:

• Drug name + emoji
• ✓ (if answered correctly) or ✗ (if answered incorrectly)
• Color-coded by drug class — each drug class gets a consistent color throughout the app (the tile background or border uses that class color)
• Tapping a tile opens the tooltip modal for that drug

The tile grid gives the user an at-a-glance view of exactly which drugs they know and which they missed, and the color coding reinforces class groupings visually.

• Play Again — same configuration, reshuffled
• Change Settings — return to Start Screen
• Review Missed — filter tile view to show only incorrect drugs and their correct answers

Each drug class is assigned one consistent color used across tiles, filter chips, and card accents. Colors should be visually distinct, aesthetically clean, and work in both light and dark mode. Suggested mapping (exact hex values to be finalized in implementation):

All drug data is stored in /src/data/topics/cardiology.json as a JSON array. Each entry:

{
  "id": "metoprolol",
  "name": "Metoprolol",
  "emoji": "❤️🛡️🐢",
  "drugClass": "Beta-blocker (cardioselective, β1)",
  "primaryEffect": "Reduces heart rate and myocardial contractility",
  "treatmentUsage": "Hypertension, angina, heart failure (HFrEF), post-MI, atrial fibrillation rate control, SVT prevention",
  "mechanismOfAction": "Selectively antagonizes β1-adrenergic receptors in the heart, reducing sympathetic stimulation of heart rate, contractility, and renin release.",
  "sideEffects": "Bradycardia, fatigue, cold extremities, depression, sexual dysfunction, masks hypoglycemia symptoms, bronchospasm (less than non-selective beta-blockers), rebound hypertension on abrupt discontinuation",
  "contraindications": "Cardiogenic shock, decompensated heart failure, significant bradycardia or heart block (without pacemaker), severe reactive airway disease",
  "topicTags": ["hypertension", "heart failure", "arrhythmias", "angina", "post-MI"],
  "tooltip": "Cardioselective β1-blocker reducing heart rate, contractility, and renin release. High-yield for hypertension, angina, HFrEF, and rate control. Classic USMLE associations: masks hypoglycemia, causes bronchospasm, rebound hypertension if stopped abruptly."
}

/src/data/
├── topics/
│   ├── cardiology.json       ← V1 drug database (edit here to add drugs)
│   ├── psychiatry.json       ← future module
│   ├── neurology.json        ← future module
│   └── ...
├── topicRegistry.json        ← list of available topic modules + metadata
├── drugClasses.json          ← valid drug class strings + assigned colors
└── topicTags.json            ← valid topic tag strings

topicRegistry.json format:

[
  {
    "id": "cardiology",
    "label": "Cardiology",
    "file": "topics/cardiology.json",
    "icon": "🫀",
    "description": "M1 cardiology and USMLE Step 1 pharmacology"
  }
]

The following drugs constitute the complete V1 dataset. All must be entered in cardiology.json with every field populated. Drugs are organized here by class for authoring convenience only — in the JSON file they are a flat array.

See Beta-blockers section. Key agents for arrhythmia: Metoprolol, Esmolol, Propranolol.

See Calcium Channel Blockers section. Key agents: Diltiazem, Verapamil.

The following mode combinations are valid (one side must always be Name):

/
├── public/
│   └── manifest.json               ← PWA manifest
├── src/
│   ├── data/
│   │   ├── topics/
│   │   │   ├── cardiology.json     ← V1 drug database
│   │   │   └── [future modules]
│   │   ├── topicRegistry.json      ← which topic files exist + metadata
│   │   ├── drugClasses.json        ← class names + assigned colors
│   │   └── topicTags.json          ← valid topic tag strings
│   ├── components/
│   │   ├── StartScreen.jsx         ← stats, drug set + mode selection, Play button
│   │   ├── GameBoard.jsx           ← main quiz UI
│   │   ├── AnswerCard.jsx          ← individual answer option card
│   │   ├── ScoreBar.jsx            ← top bar with live score
│   │   ├── TooltipModal.jsx        ← post-round drug info overlay
│   │   └── ResultsScreen.jsx       ← tile grid + score summary
│   ├── hooks/
│   │   ├── useGameSession.js       ← game state machine (shuffle, scoring, advance)
│   │   └── usePersonalBest.js      ← localStorage persistence
│   ├── utils/
│   │   └── distractors.js          ← distractor selection + collision detection
│   ├── App.jsx
│   └── main.jsx
├── vite.config.js
└── README.md

• Hosted on GitHub Pages via the gh-pages npm package or GitHub Actions.
• The app is accessible at a URL like https://[username].github.io/drug-quiz/.
• That URL can be opened on iPhone in Safari and added to the home screen as a standalone app icon (via the PWA manifest).
• No server, no database, no login required.

Saved to localStorage under key drugQuizBests. Key format: {topicId}_{filterKey}__{questionAttr}__to__{answerAttr}.

{
  "cardiology_all__name__to__drugClass": {
    "bestScore": 38,
    "totalDrugs": 42,
    "date": "2026-05-10"
  },
  "cardiology_beta-blockers__mechanismOfAction__to__name": {
    "bestScore": 7,
    "totalDrugs": 7,
    "date": "2026-05-11"
  }
}

The Start Screen reads these keys and displays a summary of the user's best scores by configuration.

The data architecture supports new modules with zero code changes. To add a new topic:

1. Create /src/data/topics/[topic].json with drug entries following the schema in Section 8.
2. Register it in topicRegistry.json.
3. Assign any new drug classes to drugClasses.json with a color.

Planned future modules:

• Psychiatry — antidepressants, antipsychotics, mood stabilizers, anxiolytics
• Neurology — anticonvulsants, Parkinson's drugs, migraine treatments, MS drugs
• Hematology / Oncology — chemotherapy agents, growth factors
• Infectious Disease — antibiotics, antivirals, antifungals
• Combined sessions — the Start Screen will allow selecting multiple topic modules simultaneously once they exist

Open src/data/topics/cardiology.json and append a new object following the schema in Section 8.2. Checklist:

• id is unique across all topic files, lowercase, no spaces
• emoji is exactly 3 emoji, not already used by any other drug
• tooltip is ≤50 words
• sideEffects includes all exam-relevant adverse effects
• contraindications includes all major absolute and relative contraindications
• At least one topicTag is assigned
• Generic name only — no brand names

No code changes required.

• User accounts or cloud sync (localStorage only)
• Spaced repetition / Anki-style scheduling
• Audio pronunciation
• Multiplayer or competitive modes
• In-session retry of wrong answers (intentional — see Section 5.5)
• Brand name recognition mode
• Non-cardiology topic modules (architecture supports them; content deferred)

Spec version 2.0 — May 2026
Author: Carlos Robles | Icahn School of Medicine at Mount Sinai, M1