Inspiration

Family history is the cheapest screening input in medicine. It needs no blood test and no scanner, only the right questions. Published guidelines already say which family patterns should lead to a referral: a mother with breast cancer before 40, three relatives with bowel cancer across two generations, a father with a heart attack before 60. Yet most people don't know which relatives matter, and a short appointment rarely leaves time to draw a family tree properly. We wanted anyone, anywhere, to walk into that appointment already knowing which criteria their family meets, and why.

What it does

KinTrace lets you draw your family tree, or describe it in a sentence, pick a published clinical guideline, and see which referral criteria your family history meets.

  • Three areas, five guidelines: breast and ovarian cancer (NICE CG164), Lynch syndrome (Amsterdam II), and early heart disease and familial hypercholesterolaemia (NICE CG71, the Dutch Lipid Clinic Network family-history item, NICE NG238).
  • Three possible findings: Meets criteria, Worth discussing or No criteria met. Each one shows the exact rule steps and highlights the relatives who triggered it on the tree.
  • No risk numbers: it never gives a risk percentage, a probability or a diagnosis.
  • Honest about gaps: a "What we don't know" panel shows missing ages and unknown relatives. Unknown is never treated as healthy. If a missing fact could meet a criterion, the finding says Worth discussing and names what would settle it.
  • Guidelines side by side: you can see why they disagree. A father's heart attack at 57 counts for the two NICE guidelines (limit 60) but not for the Dutch Lipid Clinic item (limit 55 for men).
  • A one-page report for your doctor, with an option to hide names.
  • Private by design: everything runs in your browser. There are no accounts, no database and no analytics.

KinTrace is not a medical device. It helps you start a conversation with a clinician; it doesn't replace one.

How we built it

  • Client-only core. Built with React, TypeScript in strict mode and Vite. The family tree is a plain TypeScript data structure: every change returns a new tree or a typed refusal. Every saved tree is checked against the same zod schema the loader uses. State lives in memory and localStorage (Zustand), with a "Clear everything" button.
  • Deterministic rules. Each guideline is a set of plain functions that narrow down candidate relatives step by step. Each check on a person returns passed, failed or unknown, which is how missing data becomes "Worth discussing" instead of a silent "no". A relationship engine works out degree, side of the family and line of descent, and counts only biological links.
  • AI in exactly one place. Quick add turns free text ("My mum had breast cancer at 38") into suggested tree entries. By default an offline English parser does this in the browser. If the user switches AI on, one serverless function on Vercel sends only the typed sentence to a hosted model (via NVIDIA's API). Every entry is checked against the shared schema, and any entry quoting words that aren't in the input is dropped. The user accepts each entry, and any failure falls back to the offline parser.
  • Verification as a feature. One command, npm run verify, runs everything: lint, strict types, unit, component, property and fuzz tests with coverage thresholds, and the build. It runs browser tests in Chromium, Firefox and WebKit under a guard that fails on console errors, failed requests, overflow, accessibility problems, layout shift and lost focus. It scans the source, the build and the git history for secrets, audits dependencies, and checks that every number in the README is true. Mutation testing (Stryker) proves the rule tests catch broken rules.
  • How the code was written. We built KinTrace with an AI coding assistant (Claude Code), working to a written build standard: tests with every feature, every claim backed by a command's output, and a log of decisions. No finding ever comes from a model; the assistant wrote code that is tested like any other code.

Challenges we ran into

  • Unknown is not "no". The natural way to write a rule is "if mother had breast cancer before 40". That quietly treats a missing age as healthy. We rebuilt the rule engine so every check has three answers (passed, failed, unknown), and the interface says what's missing.
  • Guidelines disagree. The same father counts under one guideline and not under another. Instead of hiding that, we made it a feature: the comparison view shows each guideline's threshold and who it counted.
  • Trusting a model's output. Models make things up. The parse function checks every quoted phrase against the user's own text and refuses an answer when most entries fail that check. Even then, the user confirms each entry.
  • Privacy you can test. "Nothing leaves your device" is easy to claim. We wrote a browser test that runs the whole flow and fails on any request to another site. We also self-hosted the fonts and shipped a strict Content-Security-Policy.
  • That strict policy bit us. Firefox failed 23 browser tests in CI because the policy blocked a check that the validation library (zod) runs with eval. We switched the library to its no-eval mode and taught our test guard to fail on any policy violation in every browser.
  • Deployment surprises. The parse function passed every local test but crashed on every request on Vercel, because Vercel runs it as unbundled ES modules that need .js import paths. We fixed it and added a test that loads the function exactly the way Vercel does.
  • Edge cases. Testing found 16 real bugs. They included two browser tabs silently overwriting each other's tree, blocked storage reported as saved, a double click adding two people, the report dated the wrong day in some time zones, and an adopted user being told to "add your parents".

Accomplishments that we're proud of

  • No risk numbers anywhere, and a test suite that checks for them.
  • 1002 unit, component, property and fuzz tests, 267 browser tests across three browser engines and five screen widths, and a 78.4% mutation score on the guideline rules and the relationship engine.
  • A full demo with zero keys: the sample family and the offline parser need nothing but a browser.
  • A one-page doctor report that always prints on one page.
  • Keyboard-only use, screen-reader labels, and English, Spanish and Hindi in the interface.

What we learned

  • The hard part of clinical software isn't the happy path. It's missing data, conflicting sources, and saying clearly what the software doesn't know.
  • Deterministic code and language models are good at different things. Letting the model only suggest, while code and the user decide, kept both the system and its tests simple.
  • Building the checks first (a guard on every browser test, a docs check on every README number) caught problems we would never have found by clicking around.

What's next for KinTrace

  • More conditions: familial colorectal cancer beyond Lynch syndrome, inherited cardiomyopathy, and sudden cardiac death in the young.
  • More guidelines, so users can choose the guidance their own health system uses.
  • More languages, each reviewed by fluent speakers, with an offline parser for each.
  • Clinical review of the rules and wording by clinical geneticists and cardiologists.

Built With

Share this project:

Updates

Submission history