On-Site Assessments

Overview

The Keyholding Company's assessors capture site assessments on-site in a parallel mobile app build; I led frontend delivery of the web page where enterprise clients view and manage them. The page covers three views: a searchable assessment list, a detail view, and client-side generation of the full report. The constraint: a hard four-week timeline, starting before the backend endpoints existed.

Decisions

Contract-first against an unbuilt backend

The backend engineer and I agreed shared TypeScript types and API contracts upfront, in writing, and I built against MSW mocks speaking that contract - frontend work was never blocked. I also verified contract claims empirically rather than assuming: before wiring a filter param, I sent a request with a value that should return zero rows - if rows came back, the endpoint was silently ignoring the param. [TODO: one-sentence example of a mismatch the zero-rows check caught] Before coding each ticket, I posted a short implementation plan (purpose, approach, dependencies, open questions), which caught architectural issues at the plan stage instead of in review.

URL as state

The list is searchable across property, address, account, and assessor, and search, filters, and pagination all live in the URL via nuqs - so any view can be shared as a link and survives a refresh. Search is debounced before committing to the URL. Vitest and React Testing Library cover this behaviour (fake timers for the debounce), MSW keeps tests on the real HTTP shape, and Playwright E2E is tracked separately.

The document problem

The page generates the assessment report client-side with jsPDF: a multi-section document running to around 30 pages, covering property details, access procedures, a categorized risk assessment, and embedded site photos. Assessments move through a lifecycle - in-progress, not assessed, complete - with reassessment available from a modal on either screen, and that state had to read the same in the list, the detail view, and the generated document.

[Visual: assessment lifecycle state-flow diagram]

[Visual: section-generic wireframe of the generated report - "structure recreated for illustration"]

[Visual: contract-first sequence - types agreed → MSW mocks → build → backend lands → swap]

Outcome

Enterprise clients get one place to search assessments, open the detail, and export the full report, with lifecycle state consistent across all three. Planned as four weeks, it was delivered in five - and it was live to enterprise clients when my involvement ended.