shops-products

byShubham Patel

1. Discovery & Shopping 1. Home Already covered. Add: - Location selector - Search - Categories - Nearby shops - Nearby products - Trending - New arrivals - Deals - Recommended for you - Recently viewed - Popular shops - Festival collections - "Shop by occasion" - "Under ₹499 / ₹999 / ₹1,499" - Footer 2. Search Results Need two tabs: Products | Shops Example: Search: Black Kurti Filters: - Category - Gender - Size - Color - Brand - Price - Discount - Rating - Distance - Delivery time - Shop - Availability - Fabric - Occasion Sort: - Popular - Newest - Price low → high - Price high → low - Rating - Distance 3. Category Page Example: Women → Ethnic → Kurtis Include: - Subcategories - Category banner - Product count - Filters - Sort - Product grid - Recently viewed 4. Nearby Shops This is one of your core marketplace pages. Two modes: List | Map Each shop card: - Shop image - Logo - Shop name - Rating - Number of reviews - Distance - Open/closed - Delivery estimate - Minimum order - Categories - Offer - "View Shop" 5. Shop Details This should feel like a mini online store for each physical shop. Header: - Cover image - Shop logo - Shop name - Rating - Distance - Address - Opening hours - Call / Chat - Follow Shop Tabs: Products | Categories | About | Reviews Also: - Shop offers - Featured products - New arrivals - Best sellers - All products - Return policy - Delivery information 2. Product Shopping 6. Product Details Add more than just the image and price. Product information - Product images - Video - Product name - Brand - Rating - Reviews - MRP - Selling price - Discount - Tax information where relevant - Size - Color - Variant - Stock - SKU internally Clothing-specific information - Size chart - Fit - Fabric - Pattern - Sleeve type - Neck type - Length - Occasion - Wash care Delivery 📍 Deliver to Ahmedabad 380015 Then: ✓ Delivery available Expected tomorrow Shop Sold by Royal Fashion - Rating - Distance - Years/business information where appropriate - View shop Policies - Return - Exchange - Cancellation Discovery - Similar products - More from this shop - Customers also viewed 3. Shopping Cart & Checkout 7. Cart I recommend making this very detailed. Show: Shop grouping Royal Fashion Product A Size L • Green ₹999 Product B Size XL • Black ₹1,299 Then another shop separately. This is important because your marketplace has multiple sellers. Cart functionality - Quantity - Remove - Move to wishlist - Save for later - Change size - Change color - Stock warning - Coupon - Delivery estimate If multiple shops are in the cart: "Items from different shops will be delivered separately." For the first MVP, I strongly recommend separate checkout/order per shop rather than trying to create a complicated multi-seller checkout. 8. Address Management Need: - Add address - Edit - Delete - Default address - Home - Work - Other - Map location - PIN code - Landmark - Delivery instructions Example: "Please call when you arrive." 9. Checkout Break it into: Step 1 — Address Step 2 — Delivery Step 3 — Payment Step 4 — Review Show the complete calculation: Items ₹1,999 Discount -₹200 Delivery ₹60 Platform fee ₹10 ---------------------------- Total ₹1,869 Only include fees that your actual business model uses. 10. Payment Support the methods you actually enable: - UPI - Card - Net banking - Wallets if supported - COD Also design: Payment Processing Processing payment... Payment Failed Payment wasn't completed. Payment Pending We're verifying your payment. Payment Success Redirect to order confirmation. Don't rely only on the frontend redirect to determine payment success. Your backend should confirm payment through the payment provider's verified callback/webhook. 4. Order Management 11. Order Success / Thank You Include: - Order number - Shop - Products - Amount - Payment method - Delivery address - Estimated delivery - Track order - Continue shopping 12. My Orders Tabs: All | Processing | Shipped | Out for Delivery | Delivered | Cancelled | Returned Each order: - Order number - Date - Shop - Product - Amount - Status - Delivery date - View details 13. Order Details This is different from the order list. Show: Order #SL123456 Items Product + size + color + quantity Price breakdown Delivery address Payment Seller Delivery Order timeline Actions - Track - Cancel - Return - Exchange - Download invoice - Contact support - Buy again 14. Live Order Tracking Eventually: Order confirmed ↓ Shop preparing ↓ Ready for pickup ↓ Picked up ↓ Out for delivery ↓ Delivered Later you can add: - Delivery partner - Live location - ETA - Call/chat - Delivery OTP Don't build live GPS tracking until your delivery operation actually requires it. 5. Customer Account 15. My Account My Profile My Orders Wishlist Addresses Payments Reviews Returns Notifications Help & Support Settings Logout 16. Profile - Name - Mobile - Email - Profile image - Date of birth if you actually need it - Gender if needed for personalization Avoid collecting unnecessary customer information. 17. Wishlist Add: - Product - Price - Current discount - Stock status - Move to cart - Remove Also: 🔔 Notify me when back in stock 18. Recently Viewed Very useful for fashion. Example: Recently viewed Show the last 10–20 products. 19. Followed Shops This is another page I recommend adding. Customer can: ❤️ Follow Royal Fashion Then: New products from shops you follow New offers This helps you create repeat engagement. 6. Returns & Customer Service 20. Return / Exchange Flow: Select Order ↓ Select Product ↓ Select Reason ↓ Return or Exchange ↓ Upload Photos ↓ Choose Pickup ↓ Submit Reasons: - Wrong size - Wrong product - Damaged - Defective - Different from description - Other 21. Return Details Show: - Return request ID - Product - Reason - Status - Pickup date - Refund amount - Refund status Statuses: Requested → Approved → Pickup → Received → Refund 22. Refund Details Very important. Show: Refund amount: ₹999 Refund method: Original payment Status: Processing Expected by: ... For COD, you'll need a separate refund method/process. 23. Reviews Have two review types: Product review ★★★★★ "Good fabric and fitting." Shop review ★★★★★ "Shop delivered quickly." Potentially later: Delivery review ★★★★★ Don't allow reviews to be presented as verified purchases unless the order system confirms that the customer actually bought the item. 7. Communication & Engagement 24. Notifications Categories: - Orders - Offers - Shops - Payments - Returns - System Examples: Your order is out for delivery. Royal Fashion added 20 new products. Your refund has been processed. 25. Offers & Deals Dedicated page: - Today's deals - Flash deals - Festival offers - Shop offers - Category offers - Under ₹499 - Under ₹999 - Clearance 26. Coupons Customer can see: Available Coupons Each card: FIRSTORDER ₹100 OFF Minimum order ₹999 [Apply] Don't make customers manually remember codes whenever possible. Automatically show eligible coupons during checkout. 27. Referral Program This could be useful later. Example: Invite your friend You get ₹100 after their first completed order. Only launch this once you have validated your basic order economics. 8. Support & Legal 28. Help Center Categories: - Orders - Payment - Delivery - Returns - Refunds - Account - Marketplace - Shop issues 29. Contact Support - Order selection - Issue type - Description - Image upload - Ticket ID - Status Later: Chat support 30. FAQ Examples: How long does delivery take? Can I exchange my size? Can I cancel an order? How does COD work? How do refunds work? 31. Legal Pages You should design these too: - Terms & Conditions - Privacy Policy - Return Policy - Refund Policy - Cancellation Policy - Delivery Policy - Seller Terms - Cookie Policy if applicable - Grievance/contact information as required for your operating model These don't need fancy UI—just clean, readable layouts.

HomeSearch ResultsSign UpCategory PageLogin
Home

Comments (0)

No comments yet. Be the first!

System Requirements

System Requirements Document for Nearby Shops

1. Introduction

Nearby Shops is a hyperlocal fashion and clothing marketplace for Indian shoppers in cities such as Ahmedabad. It connects customers with physical clothing shops in their vicinity, letting them discover nearby shops and products, compare offers, and buy from one shop at a time with delivery to their door. The product intent is warm, human, and fast: nearby shops should feel alive and reachable, and shopping should be simple enough to complete in a few confident steps.

The audience is three active human roles: Shoppers who discover, buy, track, return, and review; Shop Owners who sell from a physical shop and prepare incoming orders for pickup; and Support Agents who resolve tickets, returns, refunds, and order issues. The marketplace is deliberately shop-centric: every order belongs to exactly one shop, and multi-shop carts are split into separate per-shop checkouts and orders.

This document is the System Requirements Document for the Nearby Shops product, covering discovery and shopping, product shopping, cart and checkout, order management, customer account, returns and customer service, communication and engagement, and support and legal surfaces.

Page 1 of 47

2. System Overview

Nearby Shops is delivered as a first-party web application with three runnable services: a shared FastAPI backend hosting all application APIs and domain modules, a MariaDB database for application-owned persistent data, and a React frontend for the user interface. The backend owns order, cart, address, return, refund, review, coupon, notification, and support-ticket state, and it verifies payments through the payment provider's callback/webhook rather than trusting the frontend redirect.

Current delivery covers the full shopper lifecycle — discovery, product browsing, cart, per-shop checkout, payment, order tracking, account, wishlist, returns, refunds, reviews, notifications, offers, coupons, help, and legal pages — plus the Shop Owner's order-preparation surface and the Support Agent's ticket-handling surface. Application-owned identity is used: Shoppers self-register and log in, while Shop Owners and Support Agents receive provisioned roles before protected work.

Removed from scope

  • Live GPS tracking (also: live location, delivery partner live map, delivery OTP) — not built until the delivery operation requires it.
  • Multi-seller combined checkout — replaced by separate per-shop checkout and order.
  • Delivery reviews — deferred to a later phase.
  • Chat support — deferred to a later phase.
  • Referral program launch — deferred until basic order economics are validated.
Page 2 of 47

2a. Product Interpretation and Delivery Boundary

Nearby Shops is a first-party marketplace application. All shopping, account, order, return, refund, review, notification, offer, coupon, help, and legal surfaces are owned and rendered by the application. Payment authorization is owned by the external payment provider; the application receives the provider's verified callback/webhook and only then treats a payment as successful. Shop Owners and Support Agents work inside the same application through role-restricted surfaces provisioned to them.

Identity is application-owned. A Shopper creates an account through Sign Up and returns through Login. Shop Owners and Support Agents are provisioned with their roles before reaching protected work. Public discovery surfaces (Home, Search Results, Category Page, Nearby Shops, Shop Details, Product Details, Offers & Deals, Help Center, FAQ, Legal Pages) are reachable without signing in; cart, checkout, payment, orders, account, wishlist, returns, reviews, notifications, coupons, referral, contact support, shop orders, and support tickets require an authenticated identity.

Current scope excludes live GPS tracking, delivery OTP, delivery partner live location, multi-seller combined checkout, delivery reviews, chat support, and referral launch. These remain future items and are not part of current pages or acceptance.

2c. Page Content and Component Coverage

Page 3 of 47

Home

  • Information/state: Location selector showing the current delivery location; search field; category row; nearby shops; nearby products; trending; new arrivals; deals; recommended for you; recently viewed; popular shops; festival collections; shop by occasion; price bands Under ₹499 / ₹999 / ₹1,499; footer.
  • Primary actions: Change location, submit search, open a category, open a shop, open a product, open a deal or collection, open a price band.
  • Supporting actions: Open footer links (legal, help, FAQ), open account entry.
  • Domain entities: Location, Category, Shop, Product, Deal, Collection, PriceBand, RecentlyViewedEntry.
  • Component responsibilities: Sticky search-and-location pill; illustrated category chips; shop cards with tilted sticker offer tags; colour-blocked price-band bands; footer link groups.
  • States: Loading skeletons per section; empty state per section when no content; success renders sections; error shows retry per section; recovery re-fetches the failed section without blocking others.

Login

  • Information/state: Credential entry for returning Shoppers, Shop Owners, and Support Agents.
  • Primary actions: Submit credentials; navigate to Sign Up.
  • Supporting actions: Recover access guidance.
  • Domain entities: Account, Role.
  • Component responsibilities: Form, validation, error messaging, role-aware post-login redirect.
  • States: Idle; submitting; invalid credentials error; success redirects to the intended protected destination; recovery guidance on repeated failure.
Page 4 of 47

Sign Up

  • Information/state: New Shopper registration form collecting only necessary details.
  • Primary actions: Create account; navigate to Login.
  • Supporting actions: Read terms and privacy links.
  • Domain entities: Account, Profile.
  • Component responsibilities: Form validation, consent links, submission.
  • States: Idle; submitting; validation error; duplicate-account error; success redirects to the pending protected destination.

Search Results

  • Information/state: Query echo (e.g., "Black Kurti"); two tabs Products | Shops; filters for Category, Gender, Size, Color, Brand, Price, Discount, Rating, Distance, Delivery time, Shop, Availability, Fabric, Occasion; sort by Popular, Newest, Price low → high, Price high → low, Rating, Distance.
  • Primary actions: Switch tab; apply/clear filters; change sort; open product or shop.
  • Supporting actions: Adjust location context.
  • Domain entities: Product, Shop, Filter, SortOption.
  • Component responsibilities: Tab switcher, filter panel, sort control, result grid/list.
  • States: Loading; empty results with filter-clear suggestion; success; error with retry; recovery preserves query and filters.
Page 5 of 47

Category Page

  • Information/state: Breadcrumb (e.g., Women → Ethnic → Kurtis); subcategories; category banner; product count; filters; sort; product grid; recently viewed.
  • Primary actions: Open subcategory; apply filters; change sort; open product.
  • Supporting actions: Open recently viewed product.
  • Domain entities: Category, Product, Filter, SortOption.
  • Component responsibilities: Breadcrumb, banner, subcategory chips, filter panel, sort control, grid, recently-viewed rail.
  • States: Loading; empty category; success; error with retry.

Nearby Shops

  • Information/state: List | Map mode toggle; shop cards showing shop image, logo, shop name, rating, number of reviews, distance, open/closed, delivery estimate, minimum order, categories, offer, and View Shop.
  • Primary actions: Toggle List/Map; open View Shop; select a map pin.
  • Supporting actions: Adjust location.
  • Domain entities: Shop, Location, Offer.
  • Component responsibilities: Mode toggle, list of shop cards, map with pins, card-to-pin linkage.
  • States: Loading; empty nearby result; success; map unavailable fallback to list; error with retry.
Page 6 of 47

Shop Details

  • Information/state: Header with cover image, logo, shop name, rating, distance, address, opening hours, Call / Chat, Follow Shop; tabs Products | Categories | About | Reviews; shop offers; featured products; new arrivals; best sellers; all products; return policy; delivery information.
  • Primary actions: Follow/unfollow shop; open tab; open product; call or chat; add to cart.
  • Supporting actions: Read policies and delivery information.
  • Domain entities: Shop, Product, Offer, Review, Policy.
  • Component responsibilities: Header, tab bar, product rails, policy blocks.
  • States: Loading; empty tab; success; error with retry; follow action optimistic with rollback on failure.
Page 7 of 47

Product Details

  • Information/state: Product images; video; product name; brand; rating; reviews; MRP; selling price; discount; tax information where relevant; size; color; variant; stock; internal SKU (not customer-facing); clothing information (size chart, fit, fabric, pattern, sleeve type, neck type, length, occasion, wash care); delivery block with PIN code (e.g., Ahmedabad 380015), delivery availability, expected date; shop block (sold by, rating, distance, years/business information where appropriate, View shop); policies (return, exchange, cancellation); discovery (similar products, more from this shop, customers also viewed).
  • Primary actions: Select size/color/variant; check delivery by PIN; add to cart; open shop; open similar product.
  • Supporting actions: Open size chart; read reviews; read policies.
  • Domain entities: Product, Variant, Shop, Review, Policy, DeliveryEstimate.
  • Component responsibilities: Media gallery, variant selector, delivery checker, shop block, policy block, discovery rails.
  • States: Loading; out-of-stock disables add-to-cart; delivery unavailable message; success; error with retry.
Page 8 of 47

Cart

  • Information/state: Items grouped by shop (e.g., Royal Fashion with Product A Size L • Green ₹999 and Product B Size XL • Black ₹1,299, then another shop separately); per-item quantity, size, color, price; stock warning; coupon; delivery estimate; message "Items from different shops will be delivered separately."
  • Primary actions: Change quantity; remove; move to wishlist; save for later; change size; change color; apply coupon; proceed to per-shop checkout.
  • Supporting actions: View delivery estimate per shop.
  • Domain entities: Cart, CartItem, Shop, Coupon, DeliveryEstimate.
  • Component responsibilities: Shop group headers, item rows, quantity stepper, variant editors, coupon field, per-shop checkout buttons.
  • States: Loading; empty cart; stock warning; coupon applied/rejected; success; error with retry.

Address Management

  • Information/state: Address list with default marker; labels Home, Work, Other; map location; PIN code; landmark; delivery instructions (e.g., "Please call when you arrive.").
  • Primary actions: Add; edit; delete; set default; select for checkout.
  • Supporting actions: Pick map location.
  • Domain entities: Address.
  • Component responsibilities: Address cards, form, map picker, default toggle.
  • States: Loading; empty address list; validation error; success; error with retry.
Page 9 of 47

Checkout

  • Information/state: Four steps — Step 1 Address, Step 2 Delivery, Step 3 Payment, Step 4 Review; full calculation (Items, Discount, Delivery, Platform fee, Total) using only fees the business model uses; per-shop scope.
  • Primary actions: Select/add address; choose delivery option; choose payment method; review and place order.
  • Supporting actions: Apply eligible coupon shown automatically.
  • Domain entities: Order draft, Address, Coupon, PaymentMethod, PriceBreakdown.
  • Component responsibilities: Step indicator, step panels, price breakdown, place-order action.
  • States: Loading; missing address prompt; coupon ineligible notice; success hands off to Payment; error with retry.

Payment

  • Information/state: Enabled methods (UPI, Card, Net banking, wallets if supported, COD); states Processing ("Processing payment..."), Failed ("Payment wasn't completed."), Pending ("We're verifying your payment."), Success (redirect to order confirmation).
  • Primary actions: Choose method; confirm payment; retry on failure.
  • Supporting actions: Return to checkout.
  • Domain entities: Payment, PaymentMethod, PaymentStatus.
  • Component responsibilities: Method selector, status panels, retry control, backend webhook confirmation indicator.
  • States: Processing; Failed with retry; Pending with verification notice; Success redirect; error with recovery.
Page 10 of 47

Order Success / Thank You

  • Information/state: Order number; shop; products; amount; payment method; delivery address; estimated delivery; Track order; Continue shopping.
  • Primary actions: Track order; continue shopping.
  • Supporting actions: Open order details.
  • Domain entities: Order, Payment, Address.
  • Component responsibilities: Confirmation summary, action buttons.
  • States: Loading; success; error with retry.

My Orders

  • Information/state: Tabs All | Processing | Shipped | Out for Delivery | Delivered | Cancelled | Returned; each order shows order number, date, shop, product, amount, status, delivery date, View details.
  • Primary actions: Switch tab; open View details.
  • Supporting actions: None beyond navigation.
  • Domain entities: Order.
  • Component responsibilities: Tab bar, order cards.
  • States: Loading; empty tab; success; error with retry.
Page 11 of 47

Order Details

  • Information/state: Order number (e.g., #SL123456); items with product + size + color + quantity; price breakdown; delivery address; payment; seller; delivery; order timeline; actions Track, Cancel, Return, Exchange, Download invoice, Contact support, Buy again.
  • Primary actions: Track; cancel; return; exchange; download invoice; contact support; buy again.
  • Supporting actions: Open seller shop.
  • Domain entities: Order, OrderItem, Payment, Address, Shop, Timeline.
  • Component responsibilities: Header, item list, breakdown, timeline, action bar.
  • States: Loading; action unavailable by status; success; error with retry.

Live Order Tracking

  • Information/state: Stages Order confirmed → Shop preparing → Ready for pickup → Picked up → Out for delivery → Delivered. No live GPS tracking.
  • Primary actions: View current stage.
  • Supporting actions: Open order details.
  • Domain entities: Order, TrackingStage.
  • Component responsibilities: Stage timeline.
  • States: Loading; success; error with retry.
Page 12 of 47

My Account

  • Information/state: Links to My Profile, My Orders, Wishlist, Addresses, Payments, Reviews, Returns, Notifications, Help & Support, Settings, Logout.
  • Primary actions: Open any section; log out.
  • Supporting actions: None beyond navigation.
  • Domain entities: Account.
  • Component responsibilities: Menu list.
  • States: Loading; success; error with retry.

Profile

  • Information/state: Name; mobile; email; profile image; date of birth if actually needed; gender if needed for personalization. No unnecessary data collection.
  • Primary actions: Edit and save fields.
  • Supporting actions: Upload profile image.
  • Domain entities: Profile.
  • Component responsibilities: Form, image uploader.
  • States: Loading; validation error; success; error with retry.
Page 13 of 47

Wishlist

  • Information/state: Product; price; current discount; stock status; Move to cart; Remove; Notify me when back in stock.
  • Primary actions: Move to cart; remove; request back-in-stock notification.
  • Supporting actions: Open product.
  • Domain entities: WishlistItem, Product, StockStatus.
  • Component responsibilities: Item cards, stock badge, notify control.
  • States: Loading; empty wishlist; out-of-stock with notify; success; error with retry.

Recently Viewed

  • Information/state: Last 10–20 products.
  • Primary actions: Open product.
  • Supporting actions: None beyond navigation.
  • Domain entities: RecentlyViewedEntry, Product.
  • Component responsibilities: Product rail.
  • States: Loading; empty; success; error with retry.

Followed Shops

  • Information/state: Followed shops; new products from followed shops; new offers.
  • Primary actions: Open shop; unfollow.
  • Supporting actions: Open product.
  • Domain entities: Follow, Shop, Product, Offer.
  • Component responsibilities: Shop list, new-product rail, offer rail.
  • States: Loading; empty follow list; success; error with retry.
Page 14 of 47

Return / Exchange

  • Information/state: Ordered flow — Select Order → Select Product → Select Reason → Return or Exchange → Upload Photos → Choose Pickup → Submit. Reasons: Wrong size, Wrong product, Damaged, Defective, Different from description, Other.
  • Primary actions: Complete each step; submit request.
  • Supporting actions: Upload photos; choose pickup slot.
  • Domain entities: ReturnRequest, Order, OrderItem, Reason, Pickup.
  • Component responsibilities: Step wizard, reason selector, photo uploader, pickup chooser.
  • States: Loading; validation error; success shows request ID; error with retry.

Return Details

  • Information/state: Return request ID; product; reason; status; pickup date; refund amount; refund status. Statuses Requested → Approved → Pickup → Received → Refund.
  • Primary actions: View status; open refund details.
  • Supporting actions: Contact support.
  • Domain entities: ReturnRequest, Refund.
  • Component responsibilities: Status timeline, detail blocks.
  • States: Loading; success; error with retry.
Page 15 of 47

Refund Details

  • Information/state: Refund amount (e.g., ₹999); refund method (Original payment); status (e.g., Processing); expected by date. COD refunds use a separate refund method and process.
  • Primary actions: View refund status.
  • Supporting actions: Contact support.
  • Domain entities: Refund, Payment.
  • Component responsibilities: Amount block, method block, status block, expected-date block.
  • States: Loading; success; error with retry.

Reviews

  • Information/state: Product review (e.g., ★★★★★ "Good fabric and fitting."); shop review (e.g., ★★★★★ "Shop delivered quickly."). Verified-purchase label only when the order system confirms the customer bought the item.
  • Primary actions: Write product review; write shop review.
  • Supporting actions: Read reviews.
  • Domain entities: Review, Product, Shop, Order.
  • Component responsibilities: Review form, rating input, verified badge logic.
  • States: Loading; not-eligible notice; success; error with retry.
Page 16 of 47

Notifications

  • Information/state: Categories Orders, Offers, Shops, Payments, Returns, System; examples "Your order is out for delivery.", "Royal Fashion added 20 new products.", "Your refund has been processed."
  • Primary actions: Open notification; filter by category.
  • Supporting actions: Mark read.
  • Domain entities: Notification.
  • Component responsibilities: Category tabs, notification list.
  • States: Loading; empty; success; error with retry.

Offers & Deals

  • Information/state: Today's deals; flash deals; festival offers; shop offers; category offers; Under ₹499; Under ₹999; clearance.
  • Primary actions: Open deal, offer, or price band.
  • Supporting actions: None beyond navigation.
  • Domain entities: Deal, Offer, Category, Shop.
  • Component responsibilities: Colour-blocked deal bands, offer cards.
  • States: Loading; empty section; success; error with retry.

Coupons

  • Information/state: Available coupons with code (e.g., FIRSTORDER), discount (e.g., ₹100 OFF), minimum order (e.g., ₹999), Apply action. Eligible coupons are shown automatically during checkout.
  • Primary actions: Apply coupon; copy code.
  • Supporting actions: None beyond navigation.
  • Domain entities: Coupon.
  • Component responsibilities: Coupon cards, apply control.
  • States: Loading; empty; success; error with retry.
Page 17 of 47

Referral Program

  • Information/state: Referral entry point (e.g., "Invite your friend — You get ₹100 after their first completed order."). Launch only after basic order economics are validated.
  • Primary actions: View referral entry.
  • Supporting actions: None beyond navigation.
  • Domain entities: Referral.
  • Component responsibilities: Referral explanation block.
  • States: Loading; not-yet-launched notice; success; error with retry.

Help Center

  • Information/state: Categories Orders, Payment, Delivery, Returns, Refunds, Account, Marketplace, Shop issues.
  • Primary actions: Open category; open article.
  • Supporting actions: Open FAQ; open Contact Support.
  • Domain entities: HelpCategory, HelpArticle.
  • Component responsibilities: Category grid, article list.
  • States: Loading; empty; success; error with retry.

Contact Support

  • Information/state: Order selection; issue type; description; image upload; ticket ID; status.
  • Primary actions: Submit ticket; view ticket status.
  • Supporting actions: Upload images.
  • Domain entities: SupportTicket, Order.
  • Component responsibilities: Form, uploader, ticket status block.
  • States: Loading; validation error; success shows ticket ID; error with retry.
Page 18 of 47

FAQ

  • Information/state: Questions on delivery time, size exchange, order cancellation, COD, and refunds.
  • Primary actions: Expand question.
  • Supporting actions: Open Contact Support.
  • Domain entities: FAQItem.
  • Component responsibilities: Accordion list.
  • States: Loading; success; error with retry.

Legal Pages

  • Information/state: Terms & Conditions; Privacy Policy; Return Policy; Refund Policy; Cancellation Policy; Delivery Policy; Seller Terms; Cookie Policy if applicable; grievance/contact information as required for the operating model. Clean, readable layouts.
  • Primary actions: Read policy; navigate between policies.
  • Supporting actions: None beyond navigation.
  • Domain entities: LegalDocument.
  • Component responsibilities: Document layout, section navigation.
  • States: Loading; success; error with retry.

Shop Orders

  • Information/state: Incoming orders for the Shop Owner's shop; order number, items, customer delivery details, status, preparation actions.
  • Primary actions: Accept order; mark preparing; mark ready for pickup.
  • Supporting actions: View order details.
  • Domain entities: Order, OrderItem, Shop.
  • Component responsibilities: Order queue, status controls.
  • States: Loading; empty queue; success; error with retry.
Page 19 of 47

Support Tickets

  • Information/state: Ticket queue with ticket ID, order reference, issue type, description, images, status; related returns, refunds, and order issues.
  • Primary actions: Open ticket; update status; respond.
  • Supporting actions: Filter by status.
  • Domain entities: SupportTicket, ReturnRequest, Refund, Order.
  • Component responsibilities: Ticket list, ticket detail, status controls.
  • States: Loading; empty queue; success; error with retry.
Page 20 of 47

3. Functional Requirements

Discovery & Shopping

  • As a Shopper I should see a location selector on Home so that nearby shops and products reflect my delivery location. (explicit) — Trigger: open Home. Result: location selector shows current location. Failure: location unavailable shows a prompt to set location; recovery re-selects.
  • As a Shopper I should search from Home so that I can find products and shops. (explicit) — Trigger: enter query and submit. Result: Search Results opens with the query. Failure: empty query blocked; recovery returns focus to search.
  • As a Shopper I should browse categories from Home so that I can reach a Category Page. (explicit) — Trigger: tap a category. Result: Category Page opens. Failure: category unavailable shows retry.
  • As a Shopper I should see nearby shops, nearby products, trending, new arrivals, deals, recommended for you, recently viewed, popular shops, festival collections, shop by occasion, and price bands Under ₹499 / ₹999 / ₹1,499 on Home so that I can discover relevant items quickly. (explicit) — Trigger: open Home. Result: each section renders its content. Failure: a failed section shows retry without blocking others.
  • As a Shopper I should see a footer on Home so that I can reach legal, help, and FAQ links. (explicit) — Trigger: scroll to footer. Result: footer links render.
  • As a Shopper I should see two tabs Products | Shops on Search Results so that I can switch between product and shop results. (explicit) — Trigger: switch tab. Result: matching result set renders. Failure: empty tab shows clear-filters suggestion.
Page 21 of 47
  • As a Shopper I should filter Search Results by Category, Gender, Size, Color, Brand, Price, Discount, Rating, Distance, Delivery time, Shop, Availability, Fabric, and Occasion so that I can narrow results. (explicit) — Trigger: apply filter. Result: results update. Failure: no matches shows empty state with clear-filters.
  • As a Shopper I should sort Search Results by Popular, Newest, Price low → high, Price high → low, Rating, and Distance so that I can order results. (explicit) — Trigger: change sort. Result: results reorder.
  • As a Shopper I should see subcategories, category banner, product count, filters, sort, product grid, and recently viewed on a Category Page so that I can browse a category in context. (explicit) — Trigger: open Category Page. Result: all elements render. Failure: empty category shows message; recovery via parent category.
  • As a Shopper I should switch Nearby Shops between List and Map modes so that I can browse shops either way. (explicit) — Trigger: toggle mode. Result: matching view renders. Failure: map unavailable falls back to list.
  • As a Shopper I should see shop image, logo, shop name, rating, number of reviews, distance, open/closed, delivery estimate, minimum order, categories, offer, and View Shop on each shop card so that I can compare nearby shops. (explicit) — Trigger: view Nearby Shops. Result: cards render all fields.
  • As a Shopper I should see cover image, logo, shop name, rating, distance, address, opening hours, Call / Chat, Follow Shop, tabs Products | Categories | About | Reviews, shop offers, featured products, new arrivals, best sellers, all products, return policy, and delivery information on Shop Details so that each shop feels like a mini online store. (explicit) — Trigger: open Shop Details. Result: header, tabs, and sections render. Failure: empty tab shows message; recovery via another tab.
  • As a Shopper I should follow a shop from Shop Details so that I can see its new products and offers later. (explicit) — Trigger: tap Follow Shop. Result: follow state saved; Followed Shops reflects it. Failure: rollback and error message.
Page 22 of 47

Product Shopping

  • As a Shopper I should see product images, video, product name, brand, rating, reviews, MRP, selling price, discount, tax information where relevant, size, color, variant, stock, and internal SKU on Product Details so that I can evaluate a product fully. (explicit) — Trigger: open Product Details. Result: all fields render; SKU is internal only.
  • As a Shopper I should see size chart, fit, fabric, pattern, sleeve type, neck type, length, occasion, and wash care on Product Details so that I can judge clothing fit and care. (explicit) — Trigger: open Product Details. Result: clothing information renders.
  • As a Shopper I should check delivery availability for a PIN code (e.g., Ahmedabad 380015) with an expected date on Product Details so that I know when it will arrive. (explicit) — Trigger: enter PIN. Result: delivery availability and expected date render. Failure: unavailable PIN shows message.
  • As a Shopper I should see the selling shop with rating, distance, years/business information where appropriate, and View shop on Product Details so that I know who sells it. (explicit) — Trigger: open Product Details. Result: shop block renders.
  • As a Shopper I should see return, exchange, and cancellation policies on Product Details so that I know my options. (explicit) — Trigger: open Product Details. Result: policy block renders.
  • As a Shopper I should see similar products, more from this shop, and customers also viewed on Product Details so that I can keep discovering. (explicit) — Trigger: open Product Details. Result: discovery rails render.

Cart & Checkout

  • As a Shopper I should see cart items grouped by shop with size, color, and price per item so that I understand which shop each item belongs to. (explicit) — Trigger: open Cart. Result: shop groups render with item details.
Page 23 of 47
  • As a Shopper I should change quantity, remove, move to wishlist, save for later, change size, change color, apply a coupon, and see a delivery estimate in Cart so that I can manage my basket. (explicit) — Trigger: perform action. Result: cart updates. Failure: stock warning shown; recovery via variant change or removal.
  • As a Shopper I should see the message "Items from different shops will be delivered separately." when multiple shops are in the cart so that I understand split delivery. (explicit) — Trigger: cart contains multiple shops. Result: message renders.
  • As a Shopper I should check out and order separately per shop so that each order belongs to one shop. (explicit) — Trigger: proceed to checkout from a shop group. Result: checkout scoped to that shop only.
  • As a Shopper I should add, edit, delete, set default, and label addresses Home/Work/Other with map location, PIN code, landmark, and delivery instructions so that delivery reaches me correctly. (explicit) — Trigger: manage addresses. Result: address list updates. Failure: validation error; recovery via correction.
  • As a Shopper I should complete Checkout in four steps — Address, Delivery, Payment, Review — so that I can confirm my order. (explicit) — Trigger: start checkout. Result: steps advance in order. Failure: missing address prompts add; recovery returns to step.
  • As a Shopper I should see the full calculation of Items, Discount, Delivery, Platform fee, and Total in Checkout so that I know what I pay, using only fees the business model uses. (explicit) — Trigger: reach Review step. Result: breakdown renders.
  • As a Shopper I should see eligible coupons automatically during checkout so that I do not need to remember codes. (explicit) — Trigger: reach checkout. Result: eligible coupons shown. Failure: ineligible coupon shows notice.

Payment

Page 24 of 47
  • As a Shopper I should pay with UPI, Card, Net banking, wallets if supported, or COD so that I can use an enabled method. (explicit) — Trigger: choose method. Result: method flow starts. Failure: method unavailable hidden.
  • As a Shopper I should see Processing, Failed, Pending, and Success states so that I know the payment outcome. (explicit) — Trigger: submit payment. Result: state renders with the specified copy. Failure: Failed shows retry; Pending shows verification notice; Success redirects to order confirmation.
  • As the system I should confirm payment through the payment provider's verified callback/webhook so that success is not determined only by the frontend redirect. (explicit) — Trigger: provider callback received. Result: payment marked confirmed; order proceeds. Failure: unverified callback ignored; order remains pending.

Order Management

Page 25 of 47
  • As a Shopper I should see order number, shop, products, amount, payment method, delivery address, estimated delivery, Track order, and Continue shopping on Order Success / Thank You so that I can confirm and continue. (explicit) — Trigger: payment success. Result: confirmation renders.
  • As a Shopper I should see tabs All | Processing | Shipped | Out for Delivery | Delivered | Cancelled | Returned on My Orders so that I can filter my orders. (explicit) — Trigger: switch tab. Result: matching orders render.
  • As a Shopper I should see order number, date, shop, product, amount, status, delivery date, and View details on each order in My Orders so that I can scan my history. (explicit) — Trigger: open My Orders. Result: order cards render.
  • As a Shopper I should see order number, items with size/color/quantity, price breakdown, delivery address, payment, seller, delivery, and order timeline on Order Details so that I can review the full order. (explicit) — Trigger: open Order Details. Result: all blocks render.
  • As a Shopper I should Track, Cancel, Return, Exchange, Download invoice, Contact support, and Buy again from Order Details so that I can act on my order. (explicit) — Trigger: tap action. Result: action executes or opens the relevant surface. Failure: unavailable action hidden by status.
  • As a Shopper I should see stages Order confirmed → Shop preparing → Ready for pickup → Picked up → Out for delivery → Delivered on Live Order Tracking so that I know where my order is, without live GPS tracking. (explicit) — Trigger: open tracking. Result: current stage renders.

Customer Account

Page 26 of 47
  • As a Shopper I should reach My Profile, My Orders, Wishlist, Addresses, Payments, Reviews, Returns, Notifications, Help & Support, Settings, and Logout from My Account so that I can navigate my account. (explicit) — Trigger: open My Account. Result: menu renders.
  • As a Shopper I should edit name, mobile, email, profile image, date of birth if actually needed, and gender if needed for personalization on Profile so that my details stay correct, without unnecessary data collection. (explicit) — Trigger: edit and save. Result: profile updates. Failure: validation error.
  • As a Shopper I should see product, price, current discount, stock status, Move to cart, Remove, and Notify me when back in stock on Wishlist so that I can act on saved items. (explicit) — Trigger: open Wishlist. Result: items render. Failure: out-of-stock shows notify control.
  • As a Shopper I should see the last 10–20 products on Recently Viewed so that I can return to what I browsed. (explicit) — Trigger: open Recently Viewed. Result: recent products render.
  • As a Shopper I should see new products and new offers from shops I follow on Followed Shops so that I stay engaged. (explicit) — Trigger: open Followed Shops. Result: followed shops and their updates render.

Returns & Customer Service

Page 27 of 47
  • As a Shopper I should complete Return / Exchange through Select Order → Select Product → Select Reason → Return or Exchange → Upload Photos → Choose Pickup → Submit so that I can return or exchange an item. (explicit) — Trigger: start return. Result: request submitted with request ID. Failure: validation error; recovery returns to step.
  • As a Shopper I should choose a reason from Wrong size, Wrong product, Damaged, Defective, Different from description, or Other so that my return is categorized. (explicit) — Trigger: select reason. Result: reason saved.
  • As a Shopper I should see return request ID, product, reason, status, pickup date, refund amount, and refund status on Return Details so that I can follow my return. (explicit) — Trigger: open Return Details. Result: details render.
  • As a Shopper I should see statuses Requested → Approved → Pickup → Received → Refund on Return Details so that I know the return stage. (explicit) — Trigger: view status. Result: current stage renders.
  • As a Shopper I should see refund amount, refund method, status, and expected date on Refund Details so that I know my refund. (explicit) — Trigger: open Refund Details. Result: refund details render.
  • As a Shopper I should receive a separate refund method and process for COD orders so that COD refunds are handled correctly. (explicit) — Trigger: COD refund initiated. Result: COD-specific refund method shown.

Communication & Engagement

Page 28 of 47
  • As a Shopper I should write a product review and a shop review so that I can share feedback. (explicit) — Trigger: submit review. Result: review saved. Failure: not-eligible notice.
  • As the system I should mark a review as verified purchase only when the order system confirms the customer bought the item so that verified labels are truthful. (explicit) — Trigger: review submitted. Result: verified badge only on confirmed purchase.
  • As a Shopper I should see Notifications in categories Orders, Offers, Shops, Payments, Returns, and System so that I can follow updates. (explicit) — Trigger: open Notifications. Result: categorized notifications render.
  • As a Shopper I should see today's deals, flash deals, festival offers, shop offers, category offers, Under ₹499, Under ₹999, and clearance on Offers & Deals so that I can find savings. (explicit) — Trigger: open Offers & Deals. Result: sections render.
  • As a Shopper I should see available coupons with code, discount, minimum order, and Apply on Coupons so that I can use them. (explicit) — Trigger: open Coupons. Result: coupon cards render.
  • As a Shopper I should see the Referral Program entry point so that I can invite friends when it launches. (explicit) — Trigger: open Referral Program. Result: referral entry renders; launch gated on validated order economics.

Support & Legal

Page 29 of 47
  • As a Shopper I should see Help Center categories Orders, Payment, Delivery, Returns, Refunds, Account, Marketplace, and Shop issues so that I can find help. (explicit) — Trigger: open Help Center. Result: categories render.
  • As a Shopper I should submit Contact Support with order selection, issue type, description, image upload, and receive a ticket ID and status so that my issue is tracked. (explicit) — Trigger: submit ticket. Result: ticket ID and status render. Failure: validation error.
  • As a Shopper I should read FAQ answers on delivery time, size exchange, order cancellation, COD, and refunds so that I can self-serve. (explicit) — Trigger: open FAQ. Result: answers render.
  • As a Shopper I should read Terms & Conditions, Privacy Policy, Return Policy, Refund Policy, Cancellation Policy, Delivery Policy, Seller Terms, Cookie Policy if applicable, and grievance/contact information on Legal Pages so that I understand the rules. (explicit) — Trigger: open Legal Pages. Result: readable documents render.

Identity & Roles

Page 30 of 47
  • As a Shopper I should create an account through Sign Up before protected shopping work so that my cart, orders, and account persist. (required_inference) — Trigger: attempt protected action while anonymous. Result: Sign Up opens; on success returns to the pending destination. Failure: validation error.
  • As a returning Shopper, Shop Owner, or Support Agent I should verify identity through Login so that I can resume my work. (required_inference) — Trigger: submit credentials. Result: session established; redirect to intended destination. Failure: invalid credentials error.
  • As a Shop Owner I should receive a provisioned role before protected work so that I can access Shop Orders. (required_inference) — Trigger: provisioned account logs in. Result: Shop Orders accessible.
  • As a Support Agent I should receive a provisioned role before protected work so that I can access Support Tickets. (required_inference) — Trigger: provisioned account logs in. Result: Support Tickets accessible.
  • As a Shop Owner I should see incoming orders and mark them preparing and ready for pickup on Shop Orders so that the order lifecycle advances. (required_inference) — Trigger: order placed. Result: order appears in queue; status updates propagate to Live Order Tracking. Failure: error with retry.
  • As a Support Agent I should handle tickets, returns, refunds, and order issues on Support Tickets so that customer issues are resolved. (required_inference) — Trigger: ticket submitted. Result: ticket appears in queue; status updates propagate to Contact Support. Failure: error with retry.

4. User Personas

Page 31 of 47

Shopper

The Shopper is the primary customer of Nearby Shops, shopping for clothing from physical shops near their location in cities such as Ahmedabad. Their product context is discovery-first: they open Home, set their location, search or browse categories, and compare nearby shops and products. Their primary goal is to find the right clothing item from a nearby shop and receive it reliably.

Their distinct responsibilities include selecting a delivery location, searching and filtering, evaluating product details (size, fabric, fit, delivery availability), managing a multi-shop cart, completing a per-shop checkout with address, delivery, payment, and review steps, tracking orders, managing their account, wishlist, addresses, and followed shops, initiating returns and exchanges, following refunds, writing product and shop reviews, reading notifications, using offers and coupons, and contacting support. Their inputs are search queries, filters, variant selections, addresses, payment methods, return reasons, and review text. They interact with Shop Owners indirectly through orders and returns, and with Support Agents through tickets. Their observable success is a confirmed order with a clear delivery estimate, a trackable status, and a resolved return or refund when needed.

Page 32 of 47

Shop Owner

The Shop Owner runs a physical clothing shop listed on Nearby Shops. Their product context is a real storefront with its own offers, policies, delivery estimate, and minimum order. Their primary goal is to receive customer orders and prepare them for pickup so that customers get their items on time.

Their distinct responsibilities include maintaining the shop's presence (cover image, logo, address, opening hours, categories, offers, return policy, delivery information), receiving incoming orders on Shop Orders, and advancing each order through preparing and ready-for-pickup stages. Their inputs are order details and preparation status. They interact with Shoppers through the orders they fulfill and with Support Agents when order issues arise. Their observable success is orders moving cleanly from confirmed to ready for pickup, reflected in the Shopper's Live Order Tracking.

Support Agent

The Support Agent resolves customer issues for Nearby Shops. Their product context is the support queue covering tickets, returns, refunds, and order issues. Their primary goal is to resolve each ticket accurately and keep the Shopper informed.

Their distinct responsibilities include reviewing submitted tickets with order reference, issue type, description, and images, updating ticket status, and coordinating returns and refunds. Their inputs are ticket details and order context. They interact with Shoppers through ticket responses and with Shop Owners when shop-side issues arise. Their observable success is tickets resolved with status visible to the Shopper on Contact Support and Return Details.

5. Core User Flows

Page 33 of 47

Flow 1 — Shopper discovers nearby shops and products

  1. Shopper opens Home (public).
  2. Shopper sets location via the location selector; nearby content refreshes.
  3. Shopper browses categories, nearby shops, nearby products, trending, new arrivals, deals, recommended for you, recently viewed, popular shops, festival collections, shop by occasion, and price bands Under ₹499 / ₹999 / ₹1,499.
  4. Shopper taps a category → Category Page shows subcategories, banner, product count, filters, sort, product grid, and recently viewed.
  5. Shopper taps a shop → Shop Details shows header, tabs, offers, featured products, new arrivals, best sellers, all products, return policy, and delivery information.
  6. Shopper taps a product → Product Details shows full product and clothing information, delivery check, shop block, policies, and discovery rails.
  7. Failure: a section fails to load → retry per section; recovery does not block other sections.

Flow 2 — Shopper searches with filters and sort

  1. Shopper enters a query (e.g., "Black Kurti") on Home and submits.
  2. Search Results opens with Products | Shops tabs.
  3. Shopper switches tabs, applies filters (Category, Gender, Size, Color, Brand, Price, Discount, Rating, Distance, Delivery time, Shop, Availability, Fabric, Occasion), and changes sort (Popular, Newest, Price low → high, Price high → low, Rating, Distance).
  4. Shopper opens a product or shop.
  5. Failure: no matches → empty state with clear-filters suggestion; recovery preserves query.
Page 34 of 47

Flow 3 — Shopper browses Nearby Shops in List and Map

  1. Shopper opens Nearby Shops (public).
  2. Shopper toggles List | Map.
  3. Each shop card shows shop image, logo, name, rating, number of reviews, distance, open/closed, delivery estimate, minimum order, categories, offer, and View Shop.
  4. Shopper taps View Shop → Shop Details.
  5. Failure: map unavailable → list fallback; recovery via retry.

Flow 4 — Shopper follows a shop

  1. Shopper opens Shop Details.
  2. Shopper taps Follow Shop.
  3. Follow state saves; Followed Shops later shows new products and new offers from that shop.
  4. Failure: save fails → optimistic state rolls back with error; recovery via retry.

Flow 5 — Shopper builds a multi-shop cart

  1. Shopper adds products from Product Details.
  2. Shopper opens Cart; items are grouped by shop (e.g., Royal Fashion with Product A Size L • Green ₹999 and Product B Size XL • Black ₹1,299, then another shop separately).
  3. Shopper changes quantity, removes, moves to wishlist, saves for later, changes size or color, applies a coupon, and sees a delivery estimate.
  4. Cart shows "Items from different shops will be delivered separately."
  5. Failure: stock warning → Shopper changes variant or removes item; recovery continues.
Page 35 of 47

Flow 6 — Shopper completes per-shop checkout

  1. Shopper proceeds to checkout from one shop group in Cart.
  2. Checkout Step 1 Address: Shopper selects or adds an address via Address Management (add, edit, delete, default, Home/Work/Other, map location, PIN code, landmark, delivery instructions).
  3. Step 2 Delivery: Shopper chooses delivery option.
  4. Step 3 Payment: Shopper chooses an enabled method (UPI, Card, Net banking, wallets if supported, COD); eligible coupons are shown automatically.
  5. Step 4 Review: Shopper sees the full calculation (Items, Discount, Delivery, Platform fee, Total) using only fees the business model uses, and places the order.
  6. Failure: missing address → prompt to add; recovery returns to the step.

Flow 7 — Shopper pays and the backend confirms

  1. Shopper submits payment on Payment.
  2. Payment shows Processing ("Processing payment...").
  3. On failure, Payment shows Failed ("Payment wasn't completed.") with retry.
  4. On pending, Payment shows Pending ("We're verifying your payment.").
  5. The backend receives the payment provider's verified callback/webhook and confirms payment.
  6. On confirmed success, Payment redirects to Order Success / Thank You.
  7. Failure: unverified callback ignored; order remains pending; recovery via retry or support.
Page 36 of 47

Flow 8 — Shopper confirms order and tracks it

  1. Order Success / Thank You shows order number, shop, products, amount, payment method, delivery address, estimated delivery, Track order, and Continue shopping.
  2. Shopper taps Track order → Live Order Tracking shows Order confirmed → Shop preparing → Ready for pickup → Picked up → Out for delivery → Delivered (no live GPS tracking).
  3. Shopper taps Continue shopping → Home.

Flow 9 — Shop Owner prepares an order

  1. Shop Owner logs in through Login with a provisioned role.
  2. Shop Owner opens Shop Orders and sees the incoming order.
  3. Shop Owner marks the order preparing, then ready for pickup.
  4. The Shopper's Live Order Tracking reflects the new stage.
  5. Failure: update fails → error with retry; recovery preserves order state.

Flow 10 — Shopper manages orders

  1. Shopper opens My Orders and switches tabs All | Processing | Shipped | Out for Delivery | Delivered | Cancelled | Returned.
  2. Each order shows order number, date, shop, product, amount, status, delivery date, and View details.
  3. Shopper opens Order Details showing order number, items with size/color/quantity, price breakdown, delivery address, payment, seller, delivery, and order timeline.
  4. Shopper uses Track, Cancel, Return, Exchange, Download invoice, Contact support, or Buy again.
  5. Failure: action unavailable by status → hidden; recovery via available actions.
Page 37 of 47

Flow 11 — Shopper manages account, wishlist, and recently viewed

  1. Shopper opens My Account and navigates to My Profile, My Orders, Wishlist, Addresses, Payments, Reviews, Returns, Notifications, Help & Support, Settings, or Logout.
  2. On Profile, Shopper edits name, mobile, email, profile image, date of birth if actually needed, and gender if needed for personalization.
  3. On Wishlist, Shopper sees product, price, current discount, stock status, Move to cart, Remove, and Notify me when back in stock.
  4. On Recently Viewed, Shopper sees the last 10–20 products.
  5. Failure: validation error → correction; recovery continues.

Flow 12 — Shopper returns or exchanges an item

  1. Shopper opens Return / Exchange and selects an order.
  2. Shopper selects a product, selects a reason (Wrong size, Wrong product, Damaged, Defective, Different from description, Other), chooses Return or Exchange, uploads photos, chooses pickup, and submits.
  3. Return Details shows return request ID, product, reason, status, pickup date, refund amount, and refund status, with statuses Requested → Approved → Pickup → Received → Refund.
  4. Refund Details shows refund amount, refund method, status, and expected date; COD refunds use a separate refund method and process.
  5. Failure: validation error → return to step; recovery continues.
Page 38 of 47

Flow 13 — Support Agent resolves a ticket

  1. Support Agent logs in through Login with a provisioned role.
  2. Support Agent opens Support Tickets and sees the submitted ticket with order reference, issue type, description, images, and status.
  3. Support Agent updates status and coordinates returns and refunds.
  4. The Shopper sees the updated status on Contact Support and Return Details.
  5. Failure: update fails → error with retry.

Flow 14 — Shopper writes reviews

  1. Shopper opens Reviews.
  2. Shopper writes a product review (e.g., ★★★★★ "Good fabric and fitting.") and a shop review (e.g., ★★★★★ "Shop delivered quickly.").
  3. The system marks the review as verified purchase only when the order system confirms the purchase.
  4. Failure: not eligible → notice; recovery via eligible order.

Flow 15 — Shopper uses notifications, offers, and coupons

  1. Shopper opens Notifications and filters by Orders, Offers, Shops, Payments, Returns, or System.
  2. Shopper opens Offers & Deals and browses today's deals, flash deals, festival offers, shop offers, category offers, Under ₹499, Under ₹999, and clearance.
  3. Shopper opens Coupons and sees available coupons with code, discount, minimum order, and Apply; eligible coupons also appear automatically during checkout.
  4. Failure: empty section → message; recovery via other sections.
Page 39 of 47

Flow 16 — Shopper gets help and reads legal pages

  1. Shopper opens Help Center and browses Orders, Payment, Delivery, Returns, Refunds, Account, Marketplace, and Shop issues.
  2. Shopper opens FAQ for delivery time, size exchange, order cancellation, COD, and refunds.
  3. Shopper opens Contact Support, selects an order, issue type, description, uploads images, and submits; receives ticket ID and status.
  4. Shopper opens Legal Pages to read Terms & Conditions, Privacy Policy, Return Policy, Refund Policy, Cancellation Policy, Delivery Policy, Seller Terms, Cookie Policy if applicable, and grievance/contact information.
  5. Failure: validation error → correction; recovery continues.

Flow 17 — New Shopper creates an account

  1. Shopper attempts a protected action (e.g., add to cart) while anonymous.
  2. Sign Up opens; Shopper creates an account with only necessary details.
  3. On success, Shopper returns to the pending protected destination.
  4. Failure: validation or duplicate-account error; recovery via correction or Login.

Flow 18 — Returning user logs in

  1. Shopper, Shop Owner, or Support Agent opens Login.
  2. User submits credentials.
  3. Session established; user redirects to the intended protected destination.
  4. Failure: invalid credentials error; recovery via retry or Sign Up.
Page 40 of 47

6. Visuals Colors and Theme

Muse: Haraldur Thorleifsson — big-hearted boldness for a local fashion marketplace.

Headline: Shops near you, ready to deliver.

Color tokens (light mode):

  • Background: #FFF6E9 (cream)
  • Surface: #FFFFFF
  • Text: #1C1A17 (ink)
  • Primary: #E8452C (coral)
  • Accent: #FFC531 (sunflower)
  • Muted: #6F655B

Typography:

  • Headings: Sora, Bold, tight tracking, sentence case, heavy weight for shop names and section titles.
  • Body: Outfit.
  • Scale: 1.333 modular; display clamp 40px to 112px; body sizes 40/28/20/16.

Shape language: Chunky rounded cards with 20px radii; pill buttons; colour-blocked bands; sticker-like offer tags overlapping card corners.

Layout: Colour-blocked sections stacked in a single flow; sticky search and location bar at the top; shop cards in a two-up grid that becomes one column at 375px.

Imagery: Custom flat character and spot illustrations of shoppers and shopkeepers; bold iconography for categories; no stock photography in the hero.

Page 41 of 47

Motion: Lively entrance animations with short pops on hover; cards rise 4px on hover; offer tags tilt slightly on hover.

Avoid: No gradient blobs or glass panels; no identical hover-lift card grid; no blue-indigo accent on white; no Inter, Roboto, or Poppins fonts; no stock photography in the hero.

Readability: Headlines, wordmarks, labels, numbers, cards' text and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling to fit; no other element covers any part of them. Imagery and decoration may be cropped, bled, rotated, overlapped, or cut as the direction asks, as long as they cover no readable text or control. Scrollable rows may cross the viewport edge by design; with prefers-reduced-motion, provide a usable static arrangement.

7. Signature Design Concept

The public entry is Home. Its hero is a coral #E8452C colour block filling the top half of the screen. A large Sora headline sits left in cream #FFF6E9: "Shops near you, ready to deliver." Below it, a cream search bar with a location selector sits as one pill. A sunflower #FFC531 band with illustrated shop fronts runs across the bottom edge, carrying the hyperlocal promise visually. The subline reads "Find local fashion shops and products in your area. Compare offers and order with ease." and the call to action is "Shop nearby".

The signature moves carry through the page: the sticky top bar pairs the location selector with the search field in one pill; shop cards carry a tilted sticker offer tag on the top-right corner; the category row uses bold illustrated icons on colour chips; and the price bands Under ₹499, ₹999, and ₹1,499 appear as three stacked colour blocks. All of this recomposes accepted Home content and controls only.

Page 42 of 47

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: expressive Hero Dimensionality: layered_2d

Landing Hero Motion Brief

  • Focal subject: The coral hero block with the cream search-and-location pill and the sunflower illustrated shop-front band.
  • Input → transformation → outcome thesis: As the Shopper lands, the coral block settles into place, the headline and search pill rise into view, and the sunflower shop-front band slides in from the bottom edge — outcome: the Shopper sees the location selector and search field ready to use.
  • Motion vocabulary: Lively entrance animations with short pops; cards rise 4px on hover; offer tags tilt slightly on hover.
  • Composed first frame: Coral block top half, cream headline left, cream search pill below, sunflower band with illustrated shop fronts across the bottom edge.
  • Reduced-motion state: All elements render in their final positions without entrance animation; hover lifts and tag tilts are disabled; the shop-front band remains static and fully readable.

9. Non-Functional Requirements

Page 43 of 47
  • Payment integrity: The backend must confirm payment through the payment provider's verified callback/webhook; the frontend redirect alone must not determine success. (explicit) — Rationale: prevents false order confirmation.
  • Per-shop order isolation: Checkout and order must be separate per shop; no multi-seller combined checkout in the first MVP. (explicit) — Rationale: keeps order ownership and delivery clear.
  • Fee honesty: Only fees the actual business model uses appear in the checkout calculation. (explicit) — Rationale: avoids misleading totals.
  • Payment method honesty: Only actually enabled payment methods are offered. (explicit) — Rationale: avoids dead-end payment flows.
  • No live GPS tracking: Live GPS tracking, delivery partner live location, ETA, and delivery OTP are not built until the delivery operation requires them. (explicit) — Rationale: scope discipline.
  • Verified purchase integrity: Reviews are not presented as verified purchases unless the order system confirms the customer bought the item. (explicit) — Rationale: trust.
  • Data minimization: Avoid collecting unnecessary customer information; date of birth and gender only if actually needed. (explicit) — Rationale: privacy.
  • Coupon convenience: Eligible coupons are shown automatically during checkout; customers should not need to remember codes. (explicit) — Rationale: usability.
  • Referral gating: The referral program launches only after basic order economics are validated. (explicit) — Rationale: business readiness.
  • Readability: Readable text and controls stay whole at 375px, 768px, and 1280px; reduced-motion provides a usable static arrangement. (explicit) — Rationale: accessibility.
  • Identity continuity: Application-owned identity with Sign Up and Login; Shop Owners and Support Agents provisioned with roles. (required_inference) — Rationale: durable cart, order, and account state.
Page 44 of 47

10. Tech Stack

  • Frontend: React application UI.
  • Backend: Shared FastAPI process hosting all application APIs and domain modules, including payment webhook handling, order, cart, address, return, refund, review, coupon, notification, and support-ticket logic.
  • Database: MariaDB for application-owned persistent data.
  • Payment provider: External provider owning payment authorization; the backend verifies its callback/webhook.
  • Deployment: docker-compose with the three services (backend, database, frontend).
Page 45 of 47

11. Assumptions and Constraints

  • The first MVP uses separate checkout and order per shop; multi-seller combined checkout is out of scope. (explicit)
  • Only fees the actual business model uses appear in checkout. (explicit)
  • Only actually enabled payment methods are offered. (explicit)
  • Payment success is determined by the backend's verified provider callback/webhook, not the frontend redirect. (explicit)
  • Live GPS tracking, delivery partner live location, ETA, and delivery OTP are not built until the delivery operation requires them. (explicit)
  • Reviews are marked verified only when the order system confirms the purchase. (explicit)
  • Unnecessary customer information is not collected; date of birth and gender only if actually needed. (explicit)
  • Eligible coupons are shown automatically during checkout. (explicit)
  • The referral program launches only after basic order economics are validated. (explicit)
  • Application-owned identity is used; Shop Owners and Support Agents receive provisioned roles. (required_inference)
  • Delivery reviews and chat support are deferred to a later phase. (explicit)
  • The visual direction (palette, fonts, shape language, motion) is authoritative for presentation. (explicit)
Page 46 of 47

12. Glossary

  • Shopper: The customer who discovers, buys, tracks, returns, and reviews clothing from nearby shops.
  • Shop Owner: The operator of a physical clothing shop who receives and prepares orders.
  • Support Agent: The role that handles tickets, returns, refunds, and order issues.
  • Per-shop checkout: A checkout scoped to a single shop's items, producing one order for that shop.
  • Verified purchase: A review label applied only when the order system confirms the customer bought the item.
  • Live Order Tracking: The stage timeline Order confirmed → Shop preparing → Ready for pickup → Picked up → Out for delivery → Delivered, without live GPS.
  • COD: Cash on delivery, with a separate refund method and process.
  • Price band: The Under ₹499 / ₹999 / ₹1,499 discovery groupings.
  • Sticker offer tag: The tilted offer label overlapping a shop card's top-right corner.
Page 47 of 47
Live
Home design preview
Home: Open account entry
Login: Sign in with provisioned role
Shop Orders: View incoming order queue
Shop Orders: Accept incoming order
Shop Orders: 1. Mark order preparing
Shop Orders: Mark ready for pickup
Shop Orders: 2. Retry failed status update
Legal Pages: Read seller terms
Live
Home design preview
Home: Open account entry
Login: Sign in with provisioned role
Shop Orders: View incoming order queue
Shop Orders: Accept incoming order
Shop Orders: 1. Mark order preparing
Shop Orders: Mark ready for pickup
Shop Orders: 2. Retry failed status update
Legal Pages: Read seller terms