TerraVista

A free, neutral, citizen-facing tool for understanding a property's environment before you sign.

An address and a life profile go in; a sourced, weighted report comes out — natural hazards, market prices, air quality, safety, energy performance — produced by a team of agents that perceives, plans, collects, cross-references, and decides, with full traceability back to official French public data.

Quick start

Prerequisites: Node ≥ 24, pnpm 11 (packageManager in package.json — corepack enable handles this automatically).

pnpm install
cp .env.example .env      # optional — everything works without a key
pnpm fetch-data           # regenerates the local SSMSI index (committed, so skippable)
pnpm dev                  # http://localhost:3000

TerraVista runs one of two report paths behind a single streaming contract:

• Agentic path — active when DEEPSEEK_API_KEY is set. An Investigator LLM agent is handed the six data tools and decides for itself which sources to query, in what order, and when to dig deeper (sees flood exposure → calls the flood-zone tool; weighs a contaminated site against the energy rating). An Assessor LLM agent then forms its own verdicts, cross-domain red flags, and buyer actions from the gathered evidence. This is a real agentic loop — the agents do the research and the reasoning, not a fixed pipeline. (Native DeepSeek provider via Mastra's model router; see src/mastra/agents/investigator.ts and agentic-report.ts.)
• Deterministic path — the fallback when no key is set, or if the agentic path fails for any reason. A rule engine + templated composer (optionally polished by a narrator agent). It exists so a report is always produced, even fully offline.

Numbers stay grounded in both paths. The agents never invent a figure: every section is built from the real tool result, the map from real geometry, and the global score is computed deterministically from the verdicts the agent assigned. The LLM decides what to investigate and how to interpret it; the data itself always comes from the live official sources. No external service is required to run the app at all — the 6 sources are open APIs (except where noted below), and with no key the deterministic path produces a complete report.

Two pre-verified demo addresses are offered directly on the search screen (the "Or try a demo address" section):

• 8 Rue de la Paix, Paris 2e — urban apartment, documented flood zone, high clay shrink-swell risk.
• Venelle de l'Église, Huelgoat (29) — old rural house, underground cavities, elevated radon potential, repeated natural-disaster history. Triggers two cross-domain red flags (structural check + market/risk arbitration).

Architecture — the agentic loop

Address + profile
      │
      ▼  (agentic path — when DEEPSEEK_API_KEY is set)
┌──────────────┐   an LLM agent handed the 6 data tools. It DECIDES which
│ Investigator │   sources to query, in what order, and follows up on its own
│    (agent)   │   (flood exposure → flood-zone lookup; contaminated site →
└──────┬───────┘   weighs it against the energy rating and the buyer's plans).
       │           Tools return REAL data from the live official sources:
       │             risks ▸ Géorisques   prices ▸ Cerema/DVF   air ▸ Atmo
       │             safety ▸ SSMSI       energy ▸ ADEME DPE
       │           Grounded sections stream in as each tool returns.
       ▼
┌──────────────┐   a second LLM agent forms its OWN verdicts per domain,
│   Assessor   │   surfaces cross-domain red flags no single source reveals,
│    (agent)   │   and recommends concrete buyer actions — weighing the profile.
└──────┬───────┘   It cites only figures present in the gathered evidence.
       │
       ▼           Score = deterministic function of the agent's verdicts.
  Streamed report (NDJSON) → progressive report screen + PDF export
       ▲
       │  (deterministic fallback — no key, or agentic failure)
       │  Planner (weights) → Collectors (same tools, run in parallel) →
       │  Analyst (rule engine) → Advisor (templated composer) → narrator polish

Each stage runs inside a real Mastra workflow (src/mastra/workflows/report-workflow.ts), the agents are Mastra Agents with the sources attached as Mastra tools (src/mastra/tools/), and the workflow emits progress via writer.custom(...) which the /api/report/stream route turns into NDJSON. The same workflow runs in batch mode (run.start(...)) for PDF export — one logic, two execution modes.

The key design line: the reasoning and orchestration are genuinely agentic (the Investigator does the research and decides; the Assessor judges and adds its own findings), but the facts stay grounded — every number, source, and the score itself is derived from the real tool results, never generated by the model. And because the whole thing degrades to a deterministic rule engine with no key, a report is always produced. This split is documented in more detail on /methodology.

Sources

Six tools, each with caching, exponential-backoff retry, and a confidence score on the data returned. Per-source details (update frequency, known limitations) live on the app's Sources & methodology page (/methodology):

Domain	Source	Notes
Geocoding	IGN Géoplateforme — Base Adresse Nationale	Mandatory entry point
Risks	Géorisques (BRGM)	Flooding, clay shrink-swell, seismic, radon, cavities, contaminated sites, CatNat, AZI
Prices	Cerema — Données Foncières API (DVF open data)	Last 5 years; doesn't cover Mayotte / Alsace-Moselle
Air	Atmo Data (daily ATMO index)	Geod'air (fine-grained per-pollutant measurements) requires registration, not integrated
Safety	SSMSI (municipal crime data)	Pre-computed local index (pnpm fetch-data) — the source file (~40 MB) is too slow to query live
Energy	ADEME — DPE	Anonymized (CNIL); the most recent DPE for the exact address, or the immediate neighborhood otherwise

Tech stack

Next.js 16 (App Router, Turbopack) · React 19 · strict TypeScript · Mastra (agents, tools, workflows) · Zod · Tailwind CSS v4 · TanStack Query · MapLibre GL (IGN basemaps) · Framer Motion · @react-pdf/renderer · Vitest · Playwright.

Scripts

pnpm dev              # development server
pnpm build            # production build
pnpm test             # unit tests (Vitest)
pnpm test:e2e         # end-to-end tests (Playwright, network fully mocked)
pnpm lint             # ESLint
pnpm typecheck        # tsc --noEmit
pnpm format           # Prettier --write
pnpm fetch-data       # regenerates data/ssmsi/index.json.gz (committed — skippable in normal use)

Project structure

src/
  app/                 Next.js routes (screens + API routes)
  mastra/
    tools/             6 Mastra tools (1 per source, cache + retry + confidence)
    agents/            Investigator + Assessor (agentic path); Planner/Analyst/Advisor/Narrator (deterministic fallback)
    workflows/         the Mastra workflow that orchestrates everything
  components/screens/  search-screen and report-screen UI
  components/pdf/      PDF export template
  types/               shared Zod schemas (address, profile, domains, report, stream)
  lib/                 http (retry/backoff), cache (memory + disk), stats, geo
scripts/
  fetch-ssmsi.ts       pre-computes the SSMSI municipal index (see methodology)
tests/
  unit/                Vitest — tools, agents
  e2e/                 Playwright — critical path, mocked network

Known limitations

See the /methodology page for full detail. In short: price data (DVF) can include atypical sales that skew a local median; the Cerema (DVF) API sometimes takes several seconds to respond; fine-grained per-pollutant air quality (Geod'air) isn't integrated; detailed radon potential and clay shrink-swell hazard aren't systematically published by Géorisques for every municipality; automatic tracking of an address over time (a bonus item from the brief) isn't implemented.