Ground Truth

Type any US address. Read verified data from 6 federal agencies, where every sentence opens to cryptographic government proof.

Comment

1. Project Title & Description

Ground Truth — one US address, six federal environmental systems, one report where every sentence opens to the government record it came from.

You type an address. Ground Truth asks the US Census Geocoder for the point, then asks AirNow, EPA's Air Quality System, FEMA's National Flood Hazard Layer, EPA Superfund (SEMS), EPA ECHO and the EPA Facility Registry about that point, and streams back a single report organised around four questions: the air here, water and flooding, land once contaminated, industry next door.

Click any underlined phrase and a trace opens: the agency, the record ID, the raw field name, the raw value, the transform applied, the URL that was fetched, the timestamp, and the SHA-256 of the exact bytes that came back. Then a link to the agency's own page for that record.

2. Problem Statement

You find a place to live. The listing shows the kitchen, the light and the commute. It does not show the refinery 750 metres east, the cleanup site 700 metres away, the ozone monitor whose readings are public, or the flood zone the block sits in.

All of that is already public. It sits in six federal systems, each with its own search form and its own vocabulary, and none of them can be asked about one address across all six. So renters never look, and buyers pay an environmental consultant thousands of dollars and wait weeks for someone to do the cross-system search by hand.

The obvious fix is an AI assistant that reads all six and writes a summary. That is also the dangerous fix. A summary of someone's home that gets a distance, a status code or a flood zone wrong is worse than no summary, because the reader has no way to tell. The problem we set out to solve is not "fetch the data". It is "what is the software allowed to say about it, and how does the reader check".

3. Solution & Features

One address, six sources, one report. The report fills in as each agency answers. A slow agency never holds up the rest, and a source that cannot be reached says so on its card and offers a retry. It is never quietly replaced with a cached answer.

Every sentence is traceable. No sentence in the report is written freely by the software. Each one is a template filled from an agency's own fields, and a test enumerates every word the interface is allowed to write on its own. Delete the record and its sentence disappears. Change a field and the sentence changes.

The trace panel. Click a phrase: agency, record ID, raw field, raw value, transform, fetched URL, timestamp, SHA-256 of the response bytes, and a link to the agency page where the same ID and the same status are waiting.

Agencies explain their own terms. "Removal Only Site", "zone AE", "Area With Reduced Flood Risk Due To Levee" are shown in the agency's own definition with a link to where they wrote it. The report never paraphrases a status code.

Scales are the agencies' scales. AirNow's six air-quality bands appear with AirNow's names and edges. FEMA's three floodplain tiers are drawn as FEMA describes them, with a marker on the tier this point is in. Every band is one neutral colour, because a coloured band would read as a verdict.

A distance strip and a timeline. Where a source searched by radius, every record sits on a strip at its true distance. Distance only, because the record carries no direction. Every dated fact from every source sits on one axis of years across all four questions.

Privacy by construction. The address goes to the Census geocoder and nowhere else. Only the resulting point travels to the six agencies. The report lives in the browser and is gone when the tab closes. No accounts, no stored searches, no addresses or coordinates in any log.

What it deliberately does not do. It does not score the home and it does not say the home is safe. Six sources with six meanings do not add up to one number, and a number would be the first thing a reader trusted and the last thing anyone could defend. "No matching records" means the source returned nothing inside the boundary it was asked about, which is not the same as nothing being there, and the report says that too.

How AI is used

Ground Truth takes a position on where AI belongs in a product that makes factual claims about a person's home, and that position shaped every part of the build.

  • A verifiable evidence layer, not a generated summary. Every field in the report carries its own provenance (payload, raw key, transform, hash). That is exactly the grounding an AI assistant needs to answer "is this place near a Superfund site?" with a citation a person can click instead of a sentence they have to trust. The evidence kernel is the retrieval half of a RAG system, built so the generation half cannot drift from the record.
  • Agency text, not model text, for the facts. Where a plain-language explanation is needed, the report quotes the agency's own definition and links to it. That keeps the factual surface small enough to test exhaustively.
  • Built with an AI coding agent under a test suite that can fail. The codebase was written with Claude Code. The guardrail was 702 unit tests, 14 end-to-end browser paths, and a mutation check that breaks each of the eight core guarantees on purpose and confirms the suite catches all eight. Three committed tests that could not fail were found and replaced that way.

4. Technology Stack

  • Runtime and framework: Next.js 16, React 19, TypeScript, Bun (install, test and runtime).
  • Data contracts: Zod at every wire boundary. Each adapter returns records whose every field carries provenance; rendering is a pure read from that store.
  • Streaming: the report streams as NDJSON so each card resolves on its own.
  • Styling: Tailwind 4 with a token-based design system; components never name a colour.
  • Testing: Vitest (702 unit tests, 38 files), Playwright (14 browser paths), a mutation check over the eight core guarantees, and a test that proves production code cannot import the recorded fixtures.
  • Deployment: Docker (oven/bun image) on Google Cloud Run, us-central1.
  • Public data sources (six, all live, none cached on the report path): US Census Geocoder, AirNow, EPA Air Quality System (AQS), FEMA National Flood Hazard Layer (NFHL), EPA Superfund Enterprise Management System (SEMS), EPA Enforcement and Compliance History Online (ECHO), EPA Facility Registry Service (FRS).

Built With

Share this project:

Updates