8080.AI
DesignReqsTasksUser FlowArchitecture
Log inSign up for free

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

LandingLoginCatchment Map
Landing

Comments (0)

No comments yet. Be the first!

System Requirements

System Requirement Document
Page 1 of 11

System Requirements Document for supermarket-catchment-intelligence

1. Introduction

The "Supermarket Catchment Intelligence" is a full-stack, map-first web application designed as a site-selection decision-support tool for a supermarket chain expanding across Telangana and Andhra Pradesh, India. The application enables site-selection analysts to evaluate potential locations by analyzing catchment areas for competitors, residential density, institutions, and footfall generators, ultimately producing a sales estimate and a downloadable dossier to support go/no-go decisions.

2. System Overview

The application is a decision-support tool that integrates mapping, data analysis, and document generation to assist supermarket chains in site selection. It is designed for use by site-selection analysts and team members within a single team environment. The application provides a map-first interface with tools for location input, catchment analysis, sales estimation, and dossier generation. It supports voice interaction for natural language queries and integrates various data sources, including Google Places API and manual CSV uploads.

Page 2 of 11

2a. Product Interpretation and Delivery Boundary

The application is delivered as a web-based tool with a single-team login system. It is designed to operate within the geographic boundaries of Telangana and Andhra Pradesh, with map functionalities centered on Hyderabad. The application does not support multi-tenant environments or real-time POS/sales integration in its initial version. It relies on external APIs for data retrieval and document generation, with manual data input options where necessary.

2b. Source Content Inventory

Not applicable as no explicit content_source directive was provided.

2c. Page Content and Component Coverage

Landing

  • Purpose: Introduce the application and its purpose to anonymous visitors.
  • Components:
    • Overview of the application and its functionalities.
    • Explanation of the target audience (site-selection analysts).
    • Description of the decision-support purpose.

Login

  • Purpose: Provide access to authenticated users.
  • Components:
    • Email and password input fields.
    • Session-based authentication process.
Page 3 of 11

Dashboard

  • Purpose: Central hub for accessing analyses, saved candidates, and dossier work.
  • Components:
    • Links to active analyses and saved candidates.
    • Access to comparison and dossier generation tools.

Catchment Map

  • Purpose: Map-first workspace for location input and catchment analysis.
  • Components:
    • Location input methods (search, pin drop, link parser, coordinate entry).
    • Radius and isochrone settings.
    • Toggleable POI layers with detailed cards.

Catchment Summary

  • Purpose: Display summary of catchment analysis.
  • Components:
    • Total POI counts and competitor density score.
    • Auto-generated narrative summary.

Sales Estimator

  • Purpose: Provide sales estimation based on catchment data.
  • Components:
    • Editable inputs for households, spend, capture rate, and store size.
    • Low/mid/high sales range display.
    • Disclaimer on sales estimates.
Page 4 of 11

Candidates

  • Purpose: Manage saved candidate sites.
  • Components:
    • List of saved sites with options to remove or reorder.
    • Comparison table access.

Comparison

  • Purpose: Compare candidate sites side-by-side.
  • Components:
    • Comparison table with key metrics (population, competitor count, sales range).

Dossiers

  • Purpose: Generate and export catchment dossiers.
  • Components:
    • Dossier generation and download as Word document.
    • Shareable link export option.

Voice Q&A

  • Purpose: Enable voice interaction for catchment queries.
  • Components:
    • Microphone icon for voice input.
    • Live transcript and chat panel.
    • Text-to-speech responses.
Page 5 of 11

Data Import

  • Purpose: Import manual data for catchment analysis.
  • Components:
    • CSV upload for population, household, and unit-count data.
Page 6 of 11

3. Functional Requirements

  • As a Site-Selection Analyst, I should be able to log in using email and password to access the application.

    • Provenance: Explicit
    • Lifecycle: Initiates session-based access.
    • Observable Acceptance: Successful login redirects to the Dashboard.

  • As a Site-Selection Analyst, I should be able to input a candidate location using various methods (search, pin drop, link parser, coordinate entry).

    • Provenance: Explicit
    • Lifecycle: Location input initiates catchment analysis.
    • Observable Acceptance: Map updates to show the selected location.

  • As a Site-Selection Analyst, I should be able to set a catchment radius or drive-time isochrone for analysis.

    • Provenance: Explicit
    • Lifecycle: Radius/isochrone setting defines the catchment area.
    • Observable Acceptance: Map displays the defined catchment boundary.

  • As a Site-Selection Analyst, I should be able to toggle POI layers and view detailed information for each POI.

    • Provenance: Explicit
    • Lifecycle: POI toggling and inspection provide detailed catchment insights.
    • Observable Acceptance: POI details are displayed on the map.

  • As a Site-Selection Analyst, I should be able to view a summary of the catchment analysis in a collapsible side drawer.

    • Provenance: Explicit
    • Lifecycle: Summary drawer provides an overview of catchment data.
    • Observable Acceptance: Drawer displays POI counts and narrative summary.

  • As a Site-Selection Analyst, I should be able to use the sales estimator to calculate a sales range based on catchment data.

    • Provenance: Explicit
    • Lifecycle: Sales estimation supports decision-making.
    • Observable Acceptance: Sales range is displayed with a disclaimer.

  • As a Site-Selection Analyst, I should be able to save candidate sites and compare them side-by-side.

    • Provenance: Explicit
    • Lifecycle: Saving and comparing sites aid in decision-making.
    • Observable Acceptance: Comparison table displays selected metrics.

  • As a Site-Selection Analyst, I should be able to generate and download a Complete Catchment Dossier.

    • Provenance: Explicit
    • Lifecycle: Dossier generation provides comprehensive site analysis.
    • Observable Acceptance: Dossier is available for download as a Word document.

  • As a Site-Selection Analyst, I should be able to interact with the application using voice commands for catchment queries.

    • Provenance: Explicit
    • Lifecycle: Voice interaction enhances user experience.
    • Observable Acceptance: Voice queries are transcribed and answered.

  • As a Site-Selection Analyst, I should be able to import manual data for catchment analysis via CSV upload.

    • Provenance: Explicit
    • Lifecycle: Data import supplements API data.
    • Observable Acceptance: Uploaded data is integrated into analysis.
Page 7 of 11

4. User Personas

Site-Selection Analyst

  • Product Context: Uses the application to evaluate potential supermarket sites in Telangana and Andhra Pradesh.
  • Primary Goal: Identify viable locations for new supermarkets based on catchment analysis.
  • Responsibilities: Input locations, analyze catchment data, estimate sales, save and compare candidate sites, generate dossiers, and interact via voice commands.
  • Interactions: Engages with the map interface, summary panel, sales estimator, and dossier generation tools.
  • Observable Success: Successfully identifies and evaluates potential sites, generating actionable insights for decision-making.

Team Member

  • Product Context: Collaborates with the analyst to review and compare candidate sites.
  • Primary Goal: Support the site-selection process by reviewing analyses and using dossier outputs.
  • Responsibilities: Access shared candidate and catchment workflows, review saved analyses, and participate in decision-making.
  • Interactions: Uses the dashboard, comparison, and dossier tools to support the analyst.
  • Observable Success: Effectively contributes to the site-selection process by providing insights and feedback.

5. Core User Flows

Page 8 of 11

5.1 Site-Selection Analyst: Location Input and Catchment Analysis

  1. Login: Analyst logs in using email and password on the Login page.
  2. Access Dashboard: Redirected to the Dashboard, where active analyses and saved candidates are accessible.
  3. Input Location: On the Catchment Map page, the analyst inputs a location using search, pin drop, link parser, or coordinate entry.
  4. Define Catchment: Sets a catchment radius or drive-time isochrone.
  5. Toggle POI Layers: Selects and toggles POI layers to view detailed information.
  6. Review Summary: Opens the Catchment Summary drawer to review POI counts and narrative.
  7. Estimate Sales: Navigates to the Sales Estimator page to calculate sales range.
  8. Save Candidate: Saves the location as a candidate site for future comparison.

5.2 Site-Selection Analyst: Dossier Generation and Voice Interaction

  1. Generate Dossier: On the Dossiers page, generates a Complete Catchment Dossier for a candidate site.
  2. Download/Share: Downloads the dossier as a Word document or exports a shareable link.
  3. Voice Interaction: On the Voice Q&A page, uses the microphone icon to ask catchment-related questions.
  4. Receive Response: Receives text-to-speech responses and views live transcript in the chat panel.

5.3 Team Member: Review and Comparison

  1. Login: Team member logs in using email and password on the Login page.
  2. Access Dashboard: Redirected to the Dashboard to access shared analyses and candidates.
  3. Review Candidates: On the Candidates page, reviews saved candidate sites.
  4. Compare Sites: Uses the Comparison page to view side-by-side metrics for decision-making.
Page 9 of 11

6. Visuals Colors and Theme

  • Muse: Erik Spiekermann
  • Palette:
    • Background: #F6F3EE
    • Surface: #FFFFFF
    • Text: #141517
    • Primary: #FF6F00
    • Accent: #4CAF50
    • Muted: #BDBDBD
  • Typography:
    • Headings: Fira Sans
    • Body: Source Sans Pro
    • Scale: 1.25 modular (48/32/24/18/16)
  • Shape Language: Clear columns and structured grids with generous margins
  • Layout: Functional, clear columns with numbered systems and table-like rows for data
  • Motion: Functional and purposeful transitions; short animations that enhance understanding

7. Signature Design Concept

The public entry (Landing page) will feature a full-width interactive map as the hero element, engaging users through interaction rather than static imagery. The map will include toggleable data layers with icon-based legends, providing a clear and intuitive interface for site-selection analysts.

Page 10 of 11

8. Interaction Model & Motion Direction

  • Interaction Model: Static
  • Motion Tempo: Restrained
  • Hero Dimensionality: Flat
  • Landing Hero Motion Brief: The focal subject is a full-width interactive map with POI overlays. The transformation involves toggling data layers to reveal insights, with outcomes displayed in a side-drawer summary. Motion vocabulary includes short, purposeful transitions to enhance understanding. The first frame is composed with a clear map view, and a reduced-motion state is available for accessibility.

9. Non-Functional Requirements

  • Performance: The application should load quickly and handle large datasets efficiently.
  • Scalability: Designed to support future expansion and additional features.
  • Security: Ensure secure authentication and data handling practices.
  • Accessibility: Comply with accessibility standards to ensure usability for all users.

10. Tech Stack

  • Frontend: React + TypeScript, Tailwind CSS
  • Map Engine: Mapbox GL JS (primary) with Google Places/Maps integration
  • Backend: Node.js (Express) or Python (FastAPI)
  • Database: PostgreSQL with PostGIS extension
  • Auth: Simple single-team login (email + password, session-based)
  • File Generation: docx library for dossier export
  • Voice: Web Speech API for speech-to-text and text-to-speech
Page 11 of 11

11. Assumptions and Constraints

  • Geographic Scope: Restricted to Telangana and Andhra Pradesh.
  • Authentication: Single-team login with no multi-tenant complexity.
  • Data Sources: Reliance on Google Places API and manual CSV uploads for data.
  • Out of Scope: Real-time POS/sales integration and fully automated demographic API integration.

12. Glossary

  • Catchment Area: The geographic area from which a location draws its customers.
  • POI (Point of Interest): Specific locations within the catchment area that are relevant to site selection.
  • Isochrone: A line on a map connecting points at which a vehicle can arrive in the same amount of time.
  • Dossier: A comprehensive report generated for a candidate site, including all relevant data and analysis.
Preview dataChanges stay in this preview.
Landing design preview
Landing: View app overview
Login: Log in with credentials
Dashboard: Open active analyses
Catchment Map: Search address location
Catchment Map: Drop pin on map
Catchment Map: Paste Google Maps link
Catchment Map: Enter coordinates manually
Catchment Map: Set catchment radius
Catchment Map: Toggle POI layers
Catchment Map: Inspect POI details
Data Import: Upload CSV overrides
Catchment Summary: Review POI counts
Catchment Summary: Read narrative summary
Sales Estimator: Edit estimator assumptions
Sales Estimator: Review sales range
Candidates: Save candidate site
Comparison: Compare candidate sites
Dossiers: Generate catchment dossier
Dossiers: Download Word document
Dossiers: Export shareable link
Voice Q&A: Ask catchment question
Voice Q&A: Hear spoken answer
Preview dataChanges stay in this preview.
Landing design preview
Landing: View app overview
Login: Log in with credentials
Dashboard: Open active analyses
Catchment Map: Search address location
Catchment Map: Drop pin on map
Catchment Map: Paste Google Maps link
Catchment Map: Enter coordinates manually
Catchment Map: Set catchment radius
Catchment Map: Toggle POI layers
Catchment Map: Inspect POI details
Data Import: Upload CSV overrides
Catchment Summary: Review POI counts
Catchment Summary: Read narrative summary
Sales Estimator: Edit estimator assumptions
Sales Estimator: Review sales range
Candidates: Save candidate site
Comparison: Compare candidate sites
Dossiers: Generate catchment dossier
Dossiers: Download Word document
Dossiers: Export shareable link
Voice Q&A: Ask catchment question
Voice Q&A: Hear spoken answer