BiomarkersList

Open-source, local-first Electron desktop app for tracking blood-test biomarkers over time.

Product name: BiomarkersList · GitHub repo: biomarkerstracker

Upload lab reports (PDF or images), extract values with your own OpenAI API key, review, and browse your history — all on your machine.

Not medical advice. This software shows and stores your data only. No interpretation, recommendations, or in/out-of-range flags. AI extraction can make mistakes — always verify values against your original report. Contact your doctor for any health decisions. See DISCLAIMER.md.

Architecture

• Electron + SQLite — no server, no Docker; database lives in your app data folder
• Bring your own OpenAI API key — stored locally (macOS safeStorage when available; otherwise base64 in the local settings table)
• No auth, no cloud — single-user desktop app
• No original files stored — only parsed values and report metadata

Requirements

• macOS (v1 target)
• Node.js 20+
• OpenAI API key

Development

git clone https://github.com/veryayskiy/biomarkerstracker.git
cd biomarkerstracker
npm install
npm run dev

If you see a better-sqlite3 architecture error on Apple Silicon:

npm run rebuild:native

Build

npm run build
npm run package:mac

Output: release/BiomarkersList-<version>.dmg

For unsigned local builds, signing is disabled by default (identity: null). To sign for distribution, configure your Apple Developer certificate in electron-builder.

Data location

Data persists across app restarts in your Electron user data folder:

• Database: ~/Library/Application Support/biomarkerslist/biomarkers.db
• Avatar: ~/Library/Application Support/biomarkerslist/avatars/

The app checkpoints SQLite on save and closes the database cleanly on quit.

Marker catalog

The marker catalog lives in SQLite (markers table), not in a static runtime file. On first launch, common markers are seeded from electron/data/seed-catalog.json.

When a parsed marker is not in the catalog, the app makes one small gpt-4o-mini request (batched per report) to fetch metadata (id, display name, unit, description, aliases), validates it with Zod, and saves it to SQLite for future reports.

Tests

npm test
npm run typecheck

Reset local data

Removes the database, OpenAI API key, profile, and avatars. Quit the app first.

npm run reset

Core flow

1. First launch → enter OpenAI API key
2. Profile screen → avatar + name on the left, metric grid on the right
3. Upload report → AI extracts markers → review wizard → save locally
4. Click a metric → history chart, entries, delete options

Privacy

Stays on your device: parsed marker values, report metadata, profile name, avatar, marker catalog, and your OpenAI API key (in the app data folder).

Sent to OpenAI (only when you parse a report): PDF text or report images, plus marker names for catalog enrichment. This uses your API key and your OpenAI account. The project authors do not receive this data. See OpenAI's policies for how they handle API data.

Original uploaded files are not kept after parsing.

Legal

Free open-source software (MIT). Not a medical device or health service. The authors do not operate a cloud service or collect your health data. Use at your own risk.

See DISCLAIMER.md, CONTRIBUTING.md, and SECURITY.md.