# Bloodwork Tracker User Guide

Bloodwork Tracker is a private, invite-only app for recording blood test definitions, logging dated results, comparing those results against reference ranges, and exporting structured health data for review.

Production app:

```text
https://health-tracker.project4.net/
```

## Signing In

1. Open the production app.
2. Enter your approved email address.
3. Select **Send code**.
4. Check your email for a 6-digit one-time code.
5. Enter the code and select **Sign in**.

Codes expire after 10 minutes. If a code expires, request a fresh one.

## Main Navigation

The app has four primary areas:

- **Tracker**: latest marker cards grouped by test category.
- **Data**: the full blood-test table, visual range rows, and trend charts.
- **Admin**: test definitions, default result date, clinical notes, invitations, merging, and data reset.
- **API**: API key creation and access logs.

The top account area shows the signed-in user, theme toggle, and sign-out button.

## Finding Markers Quickly

Use the **Find marker** strip at the top of the signed-in app to avoid long scrolling.

Available controls:

- **Search**: search by marker name, group, unit, status, or latest value.
- **Group**: filter to one marker group.
- **Status**: filter to above range, below range, in range, or no result.
- **Jump to**: move directly to a marker visible under the current filter.
- **Clear**: remove active filters.

Filtering applies across:

- Tracker marker cards
- Data blood-test table
- Visual range rows
- Blood marker charts

There are also subtle **Back to top** links in marker groups and a floating back-to-top button after scrolling.

## Tracker Page

The Tracker page is for day-to-day review.

It shows:

- Summary cards for test count, result count, out-of-range count, and notes status.
- Marker cards grouped by category.
- Latest result, date, status, and result history for each marker.

Actions:

- **Add result**: opens the result modal for that marker.
- **Edit** in result history: edits an existing dated result.
- **Delete** in result history: removes that result.

Status colors:

- Green: in range
- Red: above range
- Purple: below range
- Warning/neutral: no result

## Adding Or Editing Results

1. Go to **Tracker**.
2. Select **Add result** on a marker, or **Edit** beside an existing history row.
3. Enter the value.
4. Enter or pick the test date in `YYYY-MM-DD` format.
5. Save.

If a result already exists for the same marker and date, the app asks before replacing it.

## Data Page

The Data page is for analysis and comparison.

### Blood Tests Table

The table shows:

- Test name
- Group
- Unit
- Reference range low/high
- Latest result and latest result date
- Edit, copy, and delete actions

Rows are visually flagged when the latest result is above or below range.

### Visual Range

The visual range section shows one marker per row. Each row places the latest value against the defined reference range.

Out-of-range rows are highlighted:

- Above range: red
- Below range: purple
- In range: quiet/neutral row with green range band

### Charts

Each marker with results gets a full-width trend chart.

Chart behavior:

- One marker per chart.
- X-axis uses dates.
- Y-axis centers around the normal range when possible.
- Low reference line is purple.
- High reference line is red.
- The chart expands if actual data exceeds normal bounds.

## Admin Page

The Admin page manages definitions and app-level data.

### Default Result Date

Set the default date used when adding new test results. This is useful when entering many results from the same lab visit.

Use the calendar picker or enter a valid `YYYY-MM-DD` date.

### Define Blood Test

Use this form to add or edit marker definitions.

Fields:

- **Blood test name**: marker name.
- **Unit of measure**: required.
- **Ref. range low**: optional lower bound.
- **Ref. range high**: optional upper bound.
- **Group**: choose an existing group or type a new one.

The group field normalizes case and spacing so duplicate groups are less likely.

### Clinical Notes

Clinical notes are stored with your data and included in AI export payloads.

Use this for context such as:

- diagnoses
- medication lists
- supplements
- treatment dates
- review goals
- recent lifestyle or health changes

### Manage Invitations

Admin users can invite additional email addresses. Invited users can request a login code.

### Merge Tests

Use merge when two test definitions should be combined.

The source test is merged into the destination test. Duplicate result dates in the destination are skipped.

### Danger Zone

**Clear all data** removes all blood tests and results for the signed-in user. Use with care.

## Import And Export

### Export

Use **Export** to download JSON containing:

- tests
- results
- clinical notes

### Import

Use **Import** to upload supported JSON data.

The backend accepts both:

- app export format: `tests` and `results`
- AI analysis format: `biomarkers`, `history`, and `clinical_notes`

Dates must be `YYYY-MM-DD`.

## AI Export

Use **AI export** to generate a structured JSON payload containing:

- clinical notes
- marker definitions
- latest results
- full result history
- reference ranges

This is intended for copying into an AI assistant or clinical review workflow.

## API Keys

The API page lets an admin create API keys for external tools.

Important:

- API keys are shown only once at creation.
- Store them somewhere safe.
- Existing keys can be revoked.
- Access logs show recent API use.

See `API-DOCS.md` for the complete API contract.

## Date Format Standard

Dates throughout the application use:

```text
YYYY-MM-DD
```

Example:

```text
2026-05-06
```

## Email Login Troubleshooting

If login codes do not arrive:

1. Check spam and Gmail search.
2. Confirm the email address is invited or is the admin email.
3. Check SocketLabs delivery logs.
4. Check the `mail_delivery_logs` table.
5. Confirm sender authentication DNS is still valid.

See `EMAIL-DELIVERABILITY.md` before changing SMTP or DNS.

## Recommended Workflow

1. Define markers on **Admin**.
2. Set the default result date.
3. Add results from **Tracker**.
4. Review out-of-range markers on **Tracker**.
5. Use **Data** for table review, visual ranges, and charts.
6. Keep clinical notes current.
7. Export or use AI export when preparing for review.