Shopfront Chennai Local Commerce

🏪 Shopfront: Local Shops, Found by AI

“Be the answer when people ask AI.”

*Shopfront makes local businesses visible to AI assistants through the open Model Context Protocol (MCP).*

---

---

⚡ Quick Links & Live Demos

---

📋 Table of Contents

1. The Core Novelty & Positioning
2. The Breakdown of Urban Apps vs. The AI Shift
3. The Solution: Three Key Differentiators
4. Deep Customization: You Decide What AI Says
5. System Architecture & Request Lifecycle
6. Live Endpoints & Model Context Protocol (MCP) Tools
7. Connect to AI Assistants (Claude, Cursor, ChatGPT)
8. Design System: "The Shutter Goes Up"
9. Scientific Offline Evaluation & Benchmarks
10. Local Development & Test Gates

---

1. The Core Novelty & Positioning

One line: Shopfront makes local businesses visible to AI assistants.

Tagline: *“Be the answer when people ask AI.”*

Short form: *“Local shops, found by AI.”*

┌────────────────────────────────────────────────────────────────────────┐

│ CUSTOMER ASKS AI: │ │ "Where can I get my iPhone battery replaced in Adyar right now under │ │ ₹2,000?" │ ├────────────────────────────────────────────────────────────────────────┤ │ WITHOUT SHOPFRONT: │ │ ❌ "I don't have real-time access to local shops or current prices. │ │ You may want to check Google Maps or call nearby stores." │ ├────────────────────────────────────────────────────────────────────────┤ │ WITH SHOPFRONT (MCP): │ │ ✅ "I found A1 Electronics in Adyar (450m away). They are open right │ │ now (verified 9m ago). Their iPhone Battery Replacement is │ │ ₹1,800. Click here to chat with the owner on WhatsApp: wa.me/..." │ └────────────────────────────────────────────────────────────────────────┘

Shopfront bridges the gap between physical urban retail and conversational intelligence. By turning neighborhood shops into queryable, authenticated nodes on the Model Context Protocol (MCP), merchants gain direct customer inquiries without building custom mobile apps or forfeiting 30% aggregator commissions.

---

2. The Breakdown of Urban Apps vs. The AI Shift

Urban commerce is experiencing a structural paradigm shift driven by consumer app fatigue and conversational AI:

flowchart TD

subgraph TheAppTrap["The Separate Franchise App & Marketplace Trap"] A1["Separate App per Franchise (McDonald's app, Domino's app, Swiggy, Zomato, Urban Company)"] A2["Severe App Fatigue (Users delete single-use apps; refuse to install 30 separate apps)"] A3["20% to 30% Aggregator Commissions (High take-rates erode independent merchant margins)"] A4["Walled-Garden Data Silos (Customer phone numbers masked; zero direct relationship)"] A1 --> A2 --> A3 --> A4 end

subgraph TheAIShift["The Conversational AI Revolution"] B1["Users Ask AI Instead of Opening Apps ('Find me a MacBook technician near Adyar')"] B2["AI Assistants Get ZERO Data (LLMs cannot read fragmented closed apps)"] B3["Result: Hallucinated defunct numbers or dead ends"] B1 --> B2 --> B3 end

TheAppTrap -.->|Broken Paradigm| Solution["Shopfront: The Authoritative Live Layer"] TheAIShift -.->|Needs Ground Truth| Solution

The Three Critical Industry Breakdown Points:

1. App Fatigue: Customers do not want to download, register, and update 30 different mobile apps for every local bakery, barber, and motorcycle garage.
2. The Aggregator Tax: Conventional aggregators extract 20% to 30% of gross transaction volume and mask customer identities, preventing merchants from building long-term loyalty.
3. The AI Search Blind Spot: When consumers ask Claude, Cursor, or ChatGPT for local recommendations, LLMs hallucinate or return generic blog scrapes because brick-and-mortar stores have no standard API or protocol representation.

---

3. The Solution: Three Key Differentiators

Shopfront replaces the fragmented app nightmare with a unified, protocol-driven architecture:

---

4. Deep Customization: You Decide What AI Says

Shopfront provides local merchants with absolute sovereignty over their data. Through the mobile-first Owner Portal, owners decide exactly what AI assistants know and recommend:

mindmap

root((Owner Customization)) Hours & Shift Breaks Real-time IST schedule Afternoon lunch breaks Temple & festival closures Exact Rupee Pricing Fixed menu prices Transparent price ranges Warranty terms Live Availability 1-thumb out-of-stock switches Capacity limits Service Area & Coordinates Millimeter PostGIS location Locality bounding polygon Craftsmanship & Story 20+ years experience Specialist certifications WhatsApp Opening Template Pre-filled item context Direct wa.me deep links Bilingual Localization Tamil keywords ஷாப்ஃபிரண்ட் English terminology

The 8 Signature Customization Levers:

• 1. Operating Shifts & Lunch Breaks: Configure discrete shift intervals (e.g. 09:00–13:00 and 16:30–21:30) and upcoming holiday dates. AI never sends customers to a closed shutter.
• 2. Exact Rupee Pricing: List precise prices (e.g. *iPhone Battery: ₹1,800*) to qualify high-intent customers and eliminate haggling.
• 3. Instant Availability Toggle: Flip an item unavailable with a single thumb-tap from your phone when parts run out. AI updates immediately.
• 4. Spatial Service Area: Pinpoint exact physical coordinates and service radiuses in PostGIS (SRID 4326).
• 5. Authentic Brand Story: Provide background on your techniques, heritage, and quality guarantees for AI to champion.
• 6. Pre-Formatted WhatsApp Message: Customize the greeting message generated when customers click your action link.
• 7. Bilingual Tamil & English Support: Enable native Tamil script matching alongside standard English.
• 8. Persistent "AI Preview": A live dashboard card in the Owner Portal showing the exact conversational response and raw MCP JSON that AI assistants receive.

---

5. System Architecture & Request Lifecycle

Shopfront combines sub-25ms PostGIS SQL retrieval with an LLM semantic decision reranker and a fail-open circuit breaker.

flowchart TB

subgraph Ingress["1. Ingress Layer"] User["🌐 Customer Browser Next.js 15 App"] Agent["🤖 AI Agent (Claude Desktop) Streamable HTTP / Stdio"] Merchant["📱 Shop Owner Mobile Web Portal"] end

subgraph SecurityLayer["2. Gateway Security & Auth"] RateLimit["⏱️ Sliding Window Rate Limiter (60 req/min)"] CSRF["🛡️ CSRF & Origin Guard (Sec-Fetch-Site Check)"] Argon["🔐 Argon2id (m=64MB, t=3, p=1) SHA-256 Session Token Hash"] end

subgraph SearchPipeline["3. Two-Stage Retrieval Pipeline"] Stage1["⚡ Stage 1: PostGIS Fast SQL • Spatial Radius & Bounding Box (H1) • Live Status & Admin Lock Checks (H2) • IST Temporal Shift Matching (H6) • Statement Timeout: 250ms"]

Sanitizer["🧹 Prompt Injection Stripper • Strip ASCII Control Chars • Exclude GPS coords, prices, hours"]

Stage2["🧠 Stage 2: Jev Decisions LLM Reranker • Parallel Candidate Scoring • Expected Score E[score] Formulation • Strict Time Budget: min(timeout, rem-30ms)"]

FailOpen["⚡ Fail-Open Circuit Breaker (On timeout/fault -> Fallback to Stage 1)"] end

subgraph Storage["4. Authoritative Database (PostgreSQL 16 + PostGIS 3.4)"] PGPool["🐘 Dedicated Connection Pool (Zero ORM)"] Shops[("shops & localities Spatial GIST Index")] Catalog[("catalog_items Available Offerings")] Shifts[("operating_shifts IST Intervals")] end

User --> RateLimit --> Stage1 Agent --> RateLimit --> Stage1 Merchant --> CSRF --> Argon --> PGPool

Stage1 --> PGPoo