USMLE Pomodoro

A focused study timer and Q-bank tracker built specifically for USMLE preparation. Glassmorphism UI, drift-free timer engine, per-subject accuracy tracking, and a floating mini player — everything a med student needs for long question-block days.

---

Features

• Pomodoro Timer — Focus / Short break / Long break with an arc progress ring and a drift-free, timestamp-based engine (accurate even when the window is throttled)
• Block Simulation — Timed exam-pacing mode (default 40 questions × 90 s = one 60-minute UWorld-style block); the ring counts down each question while the clock tracks the whole block, and the Q-bank logger pre-fills when you finish
• 14-Day Trend — Accuracy over time, overall or per subject, with a week-over-week delta so you know whether a weak subject is actually improving
• Backup & Restore — One-click JSON backup of all settings and history, restorable on any machine
• Q-Bank Tracker — Log questions done and correct per block, tagged by subject (Cardio, Neuro, Micro, Path, Pharm, Anatomy, Biochem, Physio)
• Performance Stats — Daily goal, day streak, focus minutes, overall and per-subject accuracy with automatic weak-subject detection, session history, CSV export
• Session Reflection — Rate each focus session 1–5 with an optional note
• Profile & Exam Countdown — Local profile (name, school/year, exam date) with a live days-until-exam chip on the timer
• Mini PiP Player — Always-on-top floating glass card with animated fidgets (Bouncing Dots, Infinity Wave, Ripple Waves, Hourglass — all self-contained SVG)
• Windows Notifications — Session complete, 30-second break warning, daily goal reached
• Full Customisation — Accent colour, background image (overlay + blur), custom clock font, custom alarm sound, looping ambient audio during focus
• Themes — Dark, Midnight, Light (frosted glass), System (follows Windows)
• Fully Offline — All fonts bundled locally; zero network requests
• Always-on-Top — Title-bar pin or system tray, kept in sync
• Single Instance — Relaunching focuses the running app

---

Installation

Requirements

• Node.js v18 or higher
• Windows 10 / 11 (macOS and Linux builds also supported)

Run from source

git clone https://github.com/mohamedhadyashry/usmle-pomodoro.git
cd usmle-pomodoro
npm install
npm start

Build the Windows installer (GitHub releases)

npm run build

Output: dist/USMLE Pomodoro Setup 2.1.0.exe

Build for the Microsoft Store

1. Create the app in Partner Center (Apps and Games → New product → MSIX or PWA app).
2. Open Product identity and copy the three values into the build.appx section of package.json:
   • identityName ← Package/Identity/Name
   • publisher ← Package/Identity/Publisher (the CN=…GUID string)
   • publisherDisplayName ← Package/Properties/PublisherDisplayName
3. Build the package:

npm run build:store

4. Upload dist/USMLE Pomodoro 2.1.0.appx in a new submission. Store packages are signed by Microsoft during ingestion — no local code-signing certificate is needed for Store distribution.

---

Project Structure

usmle-pomodoro/
├── assets/
│   ├── fonts/            # Bundled woff2 fonts (Space Mono, Syne, DM Sans) — offline
│   ├── icon.png          # App icon (256×256)
│   ├── icon.ico          # Windows installer icon (multi-size)
│   └── tray-icon.png     # System tray icon (32×32)
├── src/
│   ├── app.js            # All renderer logic (timer engine, Q-bank, stats, settings)
│   └── styles/
│       └── main.css      # Design system: tokens, themes, all components
├── index.html            # Main window
├── pip.html              # Mini PiP player window
├── main.js               # Electron main process (windows, tray, IPC)
├── preload.js            # Secure IPC bridge — main window (contextBridge)
├── preload-pip.js        # Secure IPC bridge — mini PiP window
├── LICENSE               # MIT
└── package.json

---

Customisation

All settings persist automatically via electron-store:

Setting	Details
Background image	Any JPG/PNG/WebP; overlay darkness and blur sliders
Clock font	Any TTF/OTF/WOFF/WOFF2, applied to the timer display
Alarm sound	Any MP3/WAV/OGG; volume slider and test button (built-in chime by default)
Ambient audio	Loops during focus sessions when enabled
Accent colour	Seven presets plus a full colour picker
Theme	Dark · Midnight · Light · System
Mini player fidget	Bouncing Dots · Infinity Wave · Ripple Waves · Hourglass

---

Keyboard Shortcuts

Key	Action
Space	Play / pause timer (also works in the mini player)
R	Reset timer
S	Skip to next session
1 / 2 / 3	Timer / Stats / Settings tab

---

Data & Privacy

Everything is stored locally on your machine (electron-store JSON in your user profile). No account, no telemetry, no network access.

---

License

MIT — free to use, modify and distribute.