supermarket-catchment-intelligence

bySaikiran Kiran

Build a full-stack, map-first web application called "Supermarket Catchment Intelligence" — a site-selection decision-support tool for a supermarket chain expanding across Telangana and Andhra Pradesh, India. A site-selection analyst drops a pin (or enters coordinates/a Google Maps link/an address), sets a radius, and the app pulls in everything relevant within that catchment — competitors, residential density, institutions, footfall generators — then produces a sales estimate and a downloadable dossier to support a go/no-go decision. Tech Stack Frontend: React + TypeScript, Tailwind CSS Map engine: Mapbox GL JS (preferred for isochrones + custom layers) or Google Maps JavaScript API — pick one as primary, but Google Places/Maps must be integrated regardless for POI + link/coordinate parsing Backend: Node.js (Express) or Python (FastAPI) Database: PostgreSQL with PostGIS extension (for radius/geo queries) — Replit's built-in Postgres is fine Auth: Simple single-team login (email + password, session-based). No multi-tenant complexity. File generation: docx library (e.g., docx npm package or python-docx) for the catchment dossier export Voice: Web Speech API (browser-native STT/TTS) for MVP, with a fallback structure to swap in a hosted STT/TTS API later Geographic Scope Restrict search/autocomplete and default map bounds to Telangana and Andhra Pradesh (map should initially center on Hyderabad, with easy panning to Vijayawada, Visakhapatnam, Guntur, Warangal, Tirupati, etc.) Store a state field (Telangana / Andhra Pradesh) on every saved site and POI so results can be filtered/grouped by state later Core User Flow Analyst logs in. Analyst finds a candidate location by one of four methods: Search bar with address/place autocomplete Click-to-drop-pin on the map Paste a Google Maps share link (app parses lat/long from the URL) Manually enter latitude/longitude coordinates directly Analyst sets a catchment radius (1–10 km slider, default 3 km) or switches to a drive-time isochrone (5/10/15 min) once a routing API key is connected. App queries all POI categories within the catchment and renders them as toggleable map layers. Summary drawer populates with counts, scores, and an auto-generated narrative. Analyst reviews/edits the sales estimator inputs and sees a low/mid/high sales range. Analyst saves the site as a "candidate," optionally compares it against other saved candidates. Analyst downloads the Complete Catchment Dossier as a Word document, or exports/shares a link. Optionally, analyst asks the app questions by voice ("How many hospitals are within 2 km?") and hears/reads a spoken answer. Feature Specifications 1. Location Input Address/place autocomplete (Google Places Autocomplete, scoped to Telangana/AP) Click-to-drop-pin Google Maps link parser: accepts a pasted Google Maps URL (short or long form) and extracts coordinates; if the link only contains a place ID, resolve it via Places API Manual coordinate entry: a lat/long input field with validation and a "go to location" button Radius slider (1–10 km, default 3 km) Isochrone toggle (5/10/15 min drive time) — gate this behind a routing API key; show a clear "connect API key to enable" state if not configured 2. Catchment Data Layers (toggleable) Each layer pulls from Google Places API (or OSM/Mapbox fallback) plus supports manual CSV upload/override where API coverage is sparse. For every category, use Google's rating and review count fields where available. Layer Fields to capture Competitors (supermarkets, grocery, kirana stores) name, rating, review count, category/format Residential (apartment complexes, gated communities) name, unit count (existing), status (existing/under construction/upcoming), developer if known Schools & colleges name, type (school / junior college / degree college), estimated footfall driver Hostels/PGs & budget lodging name, capacity if known — proxy for transient/migrant population Hospitals & clinics name, size/speciality, rating Offices, IT parks, industrial/manufacturing employers name, estimated employee footfall if known Malls name, existing vs. upcoming, estimated footfall, rating Gated communities (existing & upcoming) name, unit count, existing vs. upcoming, developer Resorts name, rating, review count, category Each POI should be clickable on the map, showing a card with its details. Layers should be independently toggleable via a legend panel. 3. Catchment Summary Panel (collapsible side drawer) Total POI count per category within the selected radius Competitor density score (Low/Medium/High) — derive from competitor count weighted by their average rating and total review volume Auto-generated plain-language summary, e.g.: "This catchment has 4 grocery competitors, 5 hospitals, 3 schools, 2 malls (1 upcoming), and 6 gated communities (1,200+ existing units, 400 upcoming) within 3 km." 4. Monthly Sales Estimator (key decision-support feature) Editable formula, all inputs overridable by the analyst: Estimated households = (catchment population OR residential unit count × avg household size) Monthly grocery spend/household = editable, default ₹6,000–10,000 Capture rate = editable, default 8–15% (auto-suggest lower end when competitor density is High) Estimated monthly sales = households × spend/household × capture rate Display as a range: Low / Mid / High case, never a single number Inputs the analyst can override: household count, spend per household, capture rate, planned store size (sq ft) If store size is entered, show sales per sq ft/month, benchmarked against a typical Indian supermarket range of ₹800–1,500/sq ft/month, with a visual indicator (below/within/above benchmark) Persistent, visible disclaimer: "This is an estimate based on user-adjustable assumptions, not a guarantee of actual sales performance." 5. Site Comparison Save multiple pinned locations as "candidate sites" Side-by-side comparison table: catchment population, competitor count, estimated monthly sales range, top hospital, top school, top residential project, top mall Ability to remove/re-order candidates in the comparison view 6. Complete Catchment Dossier (Word export) Generate a downloadable .docx report per site containing: Site header: address, coordinates, state, radius/isochrone used, date generated Map screenshot/static image of the catchment with pins Full breakdown of every POI category above (including malls, gated communities with unit counts, resorts) with name/rating/review count tables Competitor density score and narrative summary Sales estimate section with the low/mid/high range, all assumptions used, and the sales/sq ft benchmark comparison Disclaimer footer Also support "Export as shareable link" (a read-only web view of the same dossier) as an alternative to the Word download 7. Voice Conversations Add a microphone icon in the summary drawer that lets the analyst ask natural-language questions about the current catchment ("What's the competitor density here?", "How many upcoming gated communities are within 2 km?") Use Web Speech API for speech-to-text in the browser; send the transcribed question + current catchment data to the backend/LLM for an answer; read the answer back via text-to-speech Show a live transcript of the conversation in a small chat panel alongside the map 8. Google Search Grounding For POI categories where Places API data is thin (e.g., upcoming malls, upcoming gated communities, footfall estimates), supplement with a Google Search-grounded lookup to pull recent news/announcements, and clearly label this data as "web-sourced, verify before use" versus "Places API verified" Data Sources & APIs to Integrate Google Places API — POI search within radius, ratings, reviews Google Maps JavaScript API — map rendering, link/coordinate parsing Google Distance Matrix or Mapbox Isochrone API — drive-time polygons (optional, key-gated) Google Search (grounding) — supplemental data for upcoming projects/footfall Manual CSV upload — fallback for population/household/unit-count data not available via API UI/UX Requirements Map dominates the screen; summary panel is a collapsible side drawer Mobile-responsive — site-selection teams will use this in the field Clear visual legend for all toggleable layers Loading and empty states for every data layer Auth Single team login (email + password), no multi-tenant complexity for v1 Out of Scope for v1 Real-time POS/sales integration Fully automated demographic API integration (population data stays manual/CSV upload where APIs don't cover it) Suggested Build Order for Replit Agent Scaffold React + Tailwind frontend and Express/FastAPI backend, set up Postgres/PostGIS schema for sites, POIs, and candidates Map + location input (search, pin drop, coordinate entry, Maps link parser) Places API integration for all nine POI layers + toggleable legend Summary panel with counts, density score, auto-summary Sales estimator with editable formula and low/mid/high display Site save + side-by-side comparison table Word dossier generation + shareable link export Voice Q&A panel Google Search grounding for sparse categories Mobile responsiveness pass + auth