Section 2: Promises a Test Can Check - Requirements (Functional & Non-Functional)

Executive Summary: This section turns Section 1's clarified scope into a contract: six functional requirements you could demo on a phone, and a table of non-functional targets where every entry is a number someone could be paged on. We split the search latency target into a 122 ms budget that later sections inherit, list what's out of scope along with the door each exclusion leaves open, and name the pull between relevance, latency and freshness that the rest of the design has to manage.

The clarifying questions are done. The interviewer asks: "Okay. What exactly are we committing to?"

They aren't asking for a feature list. They want to see whether you can write promises that can be measured. "Search should be fast and fresh" is decoration. "Search answers in 150 ms at p95, and an owner's edit reaches search within 5 minutes at p99" is something a load test can verify and an on-call engineer can be paged on.

The Functional Contract: What We Demo

Sam is in Bryant Park at 12:10 on a Tuesday, hungry. Every requirement below is something Sam, or a restaurant owner, would notice if it broke.

• FR1: Nearby search. The location comes as device coordinates or as text ("near Union Square") that we geocode. The area comes as a radius (up to 50 km) for the list or a viewport bounding box (diagonal up to 50 km) for the map.
• FR2: Text, filters and sort. An optional query matched against name, categories and tags. Hard filters for category, price level, minimum rating and open now. Sort by relevance (the default), distance or rating. An empty query ("what's near me") is a first-class case.
• FR3: Place details. One place by placeId: address, hours, open-now flag, phone, website, plus rating and review count. Reviews belong to another team's service. We only consume its aggregates.
• FR4: Stable pagination. Pages of 20, at most 10 pages (200 results) per query. Page 2 never repeats or skips a place, even while the index changes. A session older than 10 minutes restarts at page 1.
• FR5: Freshness pipeline. Owner edits, provider feeds and closures flow into search automatically. Nobody re-runs an indexing job by hand.
• FR6: Abuse controls. Rate limits of 60 searches/min per anonymous device and 120/min per signed-in user, plus API keys with contracted quotas for partners.

Interviewer: "FR4 sounds like a detail. Why is it top-level?"

You: "Because users see it. If a ramen shop from Sam's page 1 shows up again on page 2, the product looks broken. And how we paginate decides how much a scraper can take. I'll defend the mechanism in Section 4's cursor pushback. For now I'm committing to the behavior: no duplicates or gaps for 10 minutes, and a ceiling of 200."