Lab Reports Example

A clinician dashboard on the Lab Reports API: upload a lab report PDF, get standardized biomarkers, and read them against the patient's wearable history.

Terra Panel is a clinician-facing dashboard that joins lab results to wearable data. Upload a lab report PDF and the Lab Reports API returns standardized biomarkers with ranges, flags, and provenance, which the app charts against the same patient's sleep, resting heart rate, and training history.

Without credentials it runs in demo mode on bundled synthetic data: four patients, three years of lab history for one of them, and 18 months of wearable data.

terra examples clone lab-reports-web-app my-app
cd my-app && npm install && npm run dev

What it demonstrates

• Upload and standardization: PDF to canonical biomarkers with ranges, flags, and provenance

• Cross-report trends matched by biomarker.key, so a marker charts across labs, languages, and formats

• Joining labs to wearable data by reference_id, the only key they share

• A timeline plotting lab draws over resting heart rate, HRV, sleep, and training lanes

• Pre-draw context: recent exertion and short sleep sit next to each report, since both skew results

• Deterministic domain scoring with an explainable breakdown, kept separate from the AI layer

• Chronicity assessed against each patient's own baseline

• AI insights with schema-validated structured output, cached by input hash

Run it yourself

Prerequisites: Terra CLI, Node.js v20+. Demo mode needs nothing else. For live data you need a Terra Dev ID and API key with Lab Reports enabled, plus the wearable data types you want.

1

Start in demo mode

terra examples clone lab-reports-web-app my-app
cd my-app
npm install
npm run dev

Open http://localhost:5173. Mutating actions are disabled behind a banner. This is the same read path as live mode, served from a local cache.

2

Go live

Copy .env.example to .env, fill in TERRA_DEV_ID and TERRA_API_KEY, then run npm run seed to create four patients and print their reference_ids.

3

Upload reports

Upload the PDFs in sample-reports/, oldest first so trends build up, or your own. Results appear grouped by panel with range bars, flags, and deltas against the previous report.

4

Add wearable data

Use the in-app Connect wearable button, or seed synthetic data with npm run seed:wearables -- <referenceId>. Lab draws then appear as markers over daily metrics.

Add an ANTHROPIC_API_KEY for the Intelligence Brief, chat, and wearable-signal insights on flagged values. Without it the rest of the app still works.

How the integration works

Lab sessions are immutable once terminal, so the app caches terminal payloads write-through and refetches anything still in flight.

src/server/lib/lab-reports.ts

export async function getSession(sessionId: string): Promise<LabReportSession> {
  const [hit] = await db
    .select()
    .from(schema.labSessionCache)
    .where(eq(schema.labSessionCache.sessionId, sessionId));

  // Terminal sessions never change, so a cached payload can't go stale
  if (hit && TERMINAL_LAB_STATUSES.has(hit.status)) {
    return withComputedFlags(JSON.parse(hit.payload) as LabReportSession);
  }

  const session = await client.get(`/lab-reports/${sessionId}`);
  await cacheIfTerminal(session);
  return withComputedFlags(session);
}

Some standardizations return normal for in-range rows but null for out-of-range ones. withComputedFlags fills that gap on the read path when the value and its applied range are both present, marking what it derived as source: "computed". The cache keeps Terra's payload verbatim.

Explore the code

View the source

AGENTS.md maps the integration code worth lifting.

Path	What it holds
src/server/lib/lab-reports.ts	Session access, cache, computed flags; start here
src/server/lib/terra/	API client, typed responses, error handling
src/server/lib/wearables.ts	Per-user, per-resource, per-day caching
src/server/lib/analysis/	Declarative registry of domains, weights, guideline bands
src/server/lib/ai.ts	Structured-output insights, cached by input hash
scripts/	Sample report generation and wearable seeding