London Neighbourhood Discovery

A neighbourhood decision engine for people moving to London. CommuteTimeMap shows where you can get to in N minutes — this app tells you which neighbourhoods inside that area you should consider living in.

Read STRATEGY.md first — it explains the product framing, architecture, and staged roadmap. This README only covers running the code.

What's in this repo

A working Next.js + TypeScript + MapLibre app with:

• A sampled public-transport isochrone overlay (the reachable-area shape, a la CommuteTimeMap)
• 95 London neighbourhoods with source-backed rent estimates, transport metadata, and static launch profiles
• A ranked sidebar that says "why this is in your shortlist" and "who this suits" for every area
• A detail drawer with affordability, transport route structure, lifestyle scores, strengths, tradeoffs, and commute estimate provenance

The default commute provider uses a reviewed static matrix plus clearly labelled distance estimates, so the public site stays fast and does not overwhelm TfL's Journey Planner. TfL routing remains an opt-in deployment setting. Rent values are static neighbourhood-level estimates reviewed for discovery use, with room values derived from listing-sample regional averages and the same base rent model.

Quick start

# 1. Install dependencies
npm install

# 2. (Optional) Get a MapTiler API key for nicer map tiles
#    Sign up free at https://www.maptiler.com/cloud/
#    Then:
cp .env.local.example .env.local
# Edit .env.local and paste your key into NEXT_PUBLIC_MAPTILER_KEY.
# You CAN skip this — the app falls back to a no-key demo style.

# 3. Run the dev server
npm run dev

# 4. Open http://localhost:3000

How the app works

• Pick a destination from the dropdown or search for a London place/postcode.
• Drag the commute slider. Neighbourhoods outside the threshold dim out.
• Set salary or rent budget. Affordability folds into the match score.
• Choose a rent type: lower-end house-share room, upper-end flat-share room, one-bed flat, or two-bed flat.
• Adjust lifestyle sliders. The ranked list and map colouring update live.
• Click any neighbourhood on the map or in the list for the detail drawer.

Architecture in one diagram

[User inputs] ─┐
               ▼
       lib/store.ts (Zustand)
               │
               ├──▶ ControlPanel (left)
               ├──▶ NeighbourhoodList (left)
               ├──▶ Map (right)
               └──▶ DetailDrawer (bottom)

       lib/data/neighbourhoods.ts ──┐
       lib/data/destinations.ts ────┤
                                     ▼
                            lib/scoring.ts
                            lib/commute.ts (RoutingProvider)
                            lib/affordability.ts

For the full architecture rationale, see STRATEGY.md §3.

Commute estimates

This app is public-transport-first. Driving estimates are intentionally not supported.

By default, /api/commute uses the reviewed static matrix and a distance-based estimate so every neighbourhood receives a fast result with a visible source. Set ROUTING_PROVIDER=tfl to opt into live Journey Planner calls; individual failures still fall back to the same estimate model. Route summaries distinguish access, public transport, interchange and final walk, and do not invent exact line-by-line instructions where the system lacks reliable route legs. The sampled isochrone combines neighbourhood results with a network-free grid, which keeps the visual shape aligned with the ranking without creating hundreds of public API requests per visit.

For an isolated local preview, npm run dev:static starts Next on port 3001 with the same network-free routing provider.

Map boundaries

The map renders official London borough boundaries from ONS Local Authority Districts May 2024 ultra-generalised clipped boundaries. Borough search highlights the selected borough boundary on the satellite map.

Neighbourhoods use launch footprints from lib/data/polygons.ts. If a neighbourhood later gets a hand-drawn or LSOA-derived Neighbourhood.polygon, the map will use that explicit geometry first.

Rent data maintenance

Rent assumptions are centralised in lib/data/rent-market.ts, with the review workflow in docs/rent-data-maintenance.md.

Analytics and shortlist experiment

The optional GA4 product funnel and the human-reviewed shortlist request flow are both disabled by default. Their environment variables, privacy constraints, event names, test procedure, launch gate, and weekly checks are documented in docs/measurement-and-shortlist-experiment.md.

The shortlist flow intentionally has no checkout or payment collection. Do not enable it until a private receiver is configured and the production hosting plan permits commercial use. Referral providers in lib/monetisation.ts also remain inactive until a provider and disclosure have been approved.

Adding accounts and saved shortlists

1. Install Convex: npm install convex
2. Run npx convex dev — it prints a deployment URL.
3. Paste the URL into NEXT_PUBLIC_CONVEX_URL in .env.local.
4. The schema is already drafted in convex/schema.ts. See convex/README.md for next steps.

Project structure

app/                  Next.js App Router pages and API routes
components/           React components (Map, ControlPanel, etc.)
lib/                  Domain logic — types, data, scoring, commute, affordability
lib/data/             Source-backed launch data (neighbourhoods, destinations)
convex/               Inactive until Stage 4
STRATEGY.md           Product spec, architecture, roadmap. READ FIRST.

Deploying

The cleanest path is Vercel:

1. Push this repo to GitHub.
2. Import into Vercel.
3. Set the same env vars in the Vercel dashboard.
4. Vercel auto-detects Next.js and deploys.

Before requesting an AdSense review

AdSense has rejected this site three times for "Low value content", each time because of pages generated from one template. Before ticking "I confirm I have fixed the issues":

1. Build and serve the site (npm run build, then npx next start -p 3210), and run npm run audit:content -- http://localhost:3210. It must exit cleanly: no sitemap cluster over 60% shared text, no page under 200 words of its own, no internal link that redirects or 404s.
2. Run the same audit against production once the deploy is live. It throttles itself there, but repeated runs from one IP can still trip Vercel's bot mitigation; if it aborts with a challenge message, wait and try later, and confirm Googlebot sees the pages with Search Console's URL Inspection → Test live URL.
3. Check that the sitemap count is what you expect. New city sections stay switched off in lib/published-city-sections.json until their pages carry writing of their own.
4. Wait until Search Console's Pages report shows retired URLs as "Page with redirect" or "Not found" before requesting review — usually two to four weeks.

Note for beginners

This project is structured to be readable end-to-end. If a file is confusing, search for it in STRATEGY.md — most architectural choices are explained there with their rationale. When in doubt, start at app/page.tsx and follow the imports.