# UPI Storefront A mobile-first, single-merchant Indian shop that turns a shared product link into a paid, fulfilled order. Merchants manage their catalog and operations from a phone, and can change their brand without rebuilding commerce. ## Build contract Build the complete experience described here, using `design.md`, `acceptance.md` and `theme.schema.json`. This is a specification, not a tested application. Supply working code, migrations, seed data, automated tests, an operator guide and a verification report. Use synthetic data and Razorpay test credentials until the merchant approves a live rollout. Do not label integrations working unless verified. Default implementation: TypeScript, Next.js server-rendered storefront/admin, PostgreSQL, S3-compatible image storage, Razorpay Standard Checkout and a persistent background worker. Use supported stable dependency versions and a lockfile. Deploy to the owner's chosen compatible host; document required services and recurring costs. Switching infrastructure requires preserving the transaction and job semantics in this spec. ## Customer experience - Branded home with editable hero, collection grid, featured products, announcement and trust/support sections. Product and collection URLs are stable across theme changes. - Product pages show photos with alt text, description, INR price, variants/SKUs, availability, delivery estimate, return policy and related products. Each variant may override image and price. Search and filters work with pagination; unavailable variants are visibly disabled. - Cart supports quantity changes and removal. Guest checkout is the default: name, contact email, phone and delivery address, with six-digit PIN validation and merchant-configured serviceability. Show item, discount, tax and shipping amounts before payment. Never invent delivery coverage from PIN syntax alone. - Razorpay checkout offers UPI through supported provider/device flows. The customer returns to a resilient order-status page after switching apps. Pending payment is a real state, with retry/recheck guidance. Selecting an uninstalled app, cancelling or closing the browser must not lose the order. - A private, unguessable order-status link shows only necessary order information, never indexed or included in public sharing. Sensitive actions and full address visibility require verified access. Reordering rechecks catalog prices and stock. ## Merchant admin - Owner and staff access with server-enforced roles: owner controls credentials, staff access, policies and refunds; catalog staff edit catalog/stock; fulfillment staff process orders. Maintain an audit log with actor, timestamp, reason and before/after values for sensitive changes. - Draft/publish/archive products; reorder images; manage variants, SKU uniqueness, collections, featured products, prices and inventory. Preserve order snapshots when products change or disappear. - Stock adjustment ledger and low-stock queue; physical stock and reserved stock displayed separately. CSV catalog/inventory import with downloadable template, dry-run errors, explicit preview and atomic commit; exports escape spreadsheet formulas. Imports use optimistic versions and cannot silently overwrite newer edits. - Order queue filters by payment and fulfillment state. Pack, ship, record carrier/tracking URL, mark delivery or pickup, cancel eligible quantities and process authorized full/partial refunds. Internal notes remain private. Prevent shipping unpaid or exception orders. - Inventory restocking is an explicit, idempotent operation, separate from refunding money. Support partial line cancellations and quantities without refunding more than captured funds or restocking twice. - Sales dashboard: paid order count, gross merchandise value, discounts, refunds, net receipts, average order value and top products, with defined time zone and date range. Separate payment totals from shipping/tax; never imply these are audited accounting figures. Show payment/notification failures and operational exceptions. ## Brand and theme editor Use schema-validated theme documents independent of catalog/order data. Presets `minimal`, `editorial` and `bold` differ in composition, typography and density, not just colors. Edit logo, colors, font choices, imagery, corner radius, spacing and home-page section order. Support draft preview on desktop/mobile, publish and rollback to an immutable prior version. Preview URLs require authorization. Reject arbitrary script/HTML injection; rich text uses a safe block model. The same seeded catalog must look convincingly distinct in all three presets. Preserve contrast, keyboard navigation, focus visibility, readable error messages and reduced-motion behavior. Target WCAG 2.2 AA on core flows. All screens work at 360px width without horizontal scrolling. ## Sharing and discovery - Server-rendered product/collection pages have canonical URLs, titles, descriptions, Open Graph images and product structured data matching current visible content. Archived pages show a useful unavailable state; redirects preserve changed slugs. - Native share, copy link, WhatsApp link and downloadable branded product cards/QR codes. Sharing is user initiated; no automatic contacts access or unsolicited messages. - Share a product with a selected variant, a collection, or a curated bundle/cart. Public share records contain only published product/variant IDs and quantities, never buyer details, discounts tied to a customer, payment IDs or private order tokens. Rate-limit creation; cap line counts; support expiry and removal. Recipients receive independent carts and current quotes. - Optional campaign tags attribute visits and purchases without embedding personal data. Minimize analytics identifiers; honor applicable consent choices. Public previews show no private or draft data. Generate images from trusted assets; prevent server-side URL-fetch abuse. ## Delivery, promotions and communication Shipping is required by default; pickup is configurable. Merchant-defined PIN zones support flat rates and free-shipping thresholds, with explicit priority for overlapping zones. Quote shipping against discounted merchandise subtotal, excluding tax, and freeze the accepted quote on the order. Outside coverage cannot check out. Display merchant-authored estimates, not carrier promises. Carrier booking is a future adapter; initial tracking is manual. Coupons support percentage or fixed discounts, expiry, minimum subtotal, usage caps and eligible products. One coupon per order, discount capped at eligible subtotal, deterministic allocation across lines. Reserve limited uses transactionally and release on expiry; confirm on payment. Publish tax-inclusive or tax-exclusive pricing explicitly. Merchant supplies tax categories/rates and registration/invoice details; implement deterministic line rounding and tax snapshots, and have the merchant verify applicable tax requirements before launch. Order confirmations, shipping updates and refund updates use a transactional outbox. Provide a functional email adapter and delivery/error log. WhatsApp support is a click-to-chat link; automated WhatsApp requires a separately connected approved service, consent and templates. Keep disabled integrations visibly unconfigured. Never show a message as sent until the provider accepts it; acceptance is not delivery. Provide downloadable receipts and configurable invoice fields. ## Configuration Manifest inputs seed the shop; ongoing changes happen through admin. Shipping remains enabled; `pickup`, `coupons` and `reviews` are optional. If reviews are enabled, link verified-purchase eligibility to actual paid orders, moderate text safely, rate-limit and allow abuse reports; never seed fake customer endorsements. Demo reviews must be labeled synthetic. Razorpay is the payment implementation, not an optional mock for production. Each shop uses its own activated merchant account and settlement bank account. Spekkr does not receive or settle shoppers' money. No payment credentials belong in theme or exported public configuration.