SpanTrack — Requirements

Goals

• Let users record blood-test results from any lab service into a single, portable, browser-based record.
• Display each biomarker's trend over time against longevity-optimized reference ranges, visually distinct from standard lab normals.
• Require zero backend, zero auth, and zero configuration — open index.html and start tracking.
• Make the current health status of each marker immediately legible (optimal / borderline / out-of-range) at a glance.
• Provide a detail view for any marker that reveals the full trend and reference band.

Primary user

A 28–55-year-old health-optimizer who runs 2–4 comprehensive blood panels per year through services like Function Health, InsideTracker, OneTwenty, or their concierge physician. They know their markers by name, want to spot slow adverse trends before symptoms appear, and are frustrated that each service locks their historical data behind a different login. They read Peter Attia and Andrew Huberman; they track their Oura scores; they are not afraid of a spreadsheet, but they want something more visual and structured.

Functional requirements

• FR1: The app must load with sample data pre-populated so the demo is immediately interactive without any user setup.
• FR2: Each biomarker must display: current (most recent) value, unit, trend direction vs. prior test, and status badge (Optimal / Borderline / Out of Range).
• FR3: Biomarkers must be filterable by category (All, Metabolic, Cardiovascular, Inflammation, Hormones, Thyroid, Nutrients) using tab controls.
• FR4: Clicking a biomarker card must open a detail view showing a sparkline trend chart of all recorded readings.
• FR5: The detail view must display a shaded band representing the longevity-optimal range and a separate line for the standard lab normal boundary.
• FR6: An "Add Test Results" workflow must allow the user to specify a test date and enter values for any subset of the available markers via a modal form.
• FR7: Newly added entries must immediately appear in the dashboard and update trend indicators without a page reload.
• FR8: Status badges must use color coding: green = Optimal, amber = Borderline, red = Out of Range, grey = no target defined.
• FR9: Trend direction must be represented as an up arrow, down arrow, or dash, color-coded by whether the movement is favorable or unfavorable for that specific marker (e.g., falling LDL is favorable; falling HDL is unfavorable).
• FR10: All data must persist in localStorage so entries survive a page refresh within the same browser session.
• FR11: The app must be fully usable on a mobile viewport (≥ 375px wide) via responsive layout.
• FR12: Biomarker reference ranges must include both the longevity-optimal range and the standard lab normal range, clearly labeled, so users understand the distinction.
• FR13: The prototype must load sample-data.json via a fetch call (or inline JSON fallback for file:// access) and merge it with any localStorage entries.

User stories

• As a health optimizer, I want to log the results from my latest Function Health panel so that I have a single home for all my lab data regardless of which service drew the blood.
• As a user, I want to see at a glance whether each of my biomarkers is in the longevity-optimal range, not just the standard lab normal, so I can act on subtle trends before they become clinical problems.
• As a user, I want to see a trend chart for my ApoB over the past 12 months so I can confirm that my dietary changes are having the expected effect.
• As a user, I want to filter my dashboard to show only cardiovascular markers so I can focus my review during a cardio-health deep-dive.
• As a first-time visitor, I want to see realistic sample data already loaded so I can understand the product value before entering any of my own results.
• As a user, I want to add a new test date and enter just the markers that were included in that panel, without having to fill in every field.
• As a mobile user, I want the dashboard to work comfortably on my phone so I can check my results on the go.
• As a user, I want the app to remember my manually entered data between browser sessions so I don't lose my history on a refresh.

Non-functional requirements

• No server-side code, no API calls, no authentication — pure client-side HTML/CSS/JS.
• All data stays in the browser (localStorage); nothing is transmitted externally.
• Must open and function correctly from a local file:// path (for maximum portability) as well as served over HTTP.
• Third-party library usage limited to a single charting library (Chart.js from CDN) for the trend sparkline — no frameworks, no build toolchain.
• Page load must complete in under 2 seconds on a typical laptop browser.
• Color contrasts must meet WCAG AA standards for the status badge text and backgrounds.

Out of scope (for the prototype)

• CSV/PDF import from lab services.
• Account creation, cloud sync, or multi-device support.
• Real-time wearable integrations (CGM, Oura, Garmin).
• AI-generated narrative summaries.
• Physician share links.
• Push notifications or email reminders.
• Support for female-specific hormone ranges or pediatric ranges.

Open questions

• Should the user be able to customize the longevity-optimal ranges per marker, or are the defaults (based on published longevity medicine frameworks) fixed in v1?
• For markers where lower is not always better (e.g. testosterone can be too high), how should the "favorable direction" logic handle edge cases?
• Is localStorage sufficient for MVP or should an IndexedDB backend be considered for larger datasets (50+ test dates)?