nick-doc/Multi-Surface Feature Parity Guide.md

Multi-Surface Feature Parity Guide

Rule source: AGENTS.md §8 — every feature change must be evaluated against all 4 surfaces and ported where an equivalent exists.

---

The 4 surfaces at a glance

/dashboard/seller/*          → Seller Dashboard
/dashboard/request-template/* → Seller Dashboard (product/template management)
/dashboard/shop-settings/*   → Seller Dashboard (shop branding & settings)

/shop/*                      → Platform Marketplace (public)
/dashboard/shops/*           → Platform Marketplace (buyer logged-in)

/dashboard/shop/[slug]/*     → White-label Shop Platform (tenant admin)
/store/*                     → White-label Shop Platform (public storefront)

/telegram/*                  → Telegram Mini App

---

Surface primitives — never mix

Seller Dashboard + Platform Marketplace

Both share the same layout and component system.

Concern	Primitive
Layout	DashboardContent, Card, CustomBreadcrumbs (MUI)
Styling	MUI sx + theme.vars.palette.* — no hex colors (see rule §1)
Strings	useTranslate() → src/locales/langs/en/common.json + fa/common.json
Data	useSWR + src/actions/*.ts hooks
Components	MUI + src/components/*

White-label Shop Platform

Uses the same MUI/SWR stack but a different layout shell.

Concern	Primitive
Layout	ShopDashboardLayout (src/sections/shop/shop-dashboard-layout.tsx) for admin; StorefrontLayout (src/sections/storefront/storefront-layout.tsx) for public
Sections	src/sections/shop/shop-*.tsx, src/sections/storefront/storefront-*.tsx
Strings	Same useTranslate() → common.json
Data	Same src/actions/*.ts — reuse actions, don't duplicate

Telegram Mini App

Completely different design system — never import MUI here.

Concern	Primitive
Layout	Full-bleed mobile, TelegramTabBar, bottom-sheets
Styling	TG_PALETTE CSS vars (var(--tg-saffron-600), var(--tg-ink-700), etc.) via inline style={{}}
Strings	t prop typed as TelegramDict — add to locales/en.ts + locales/fa.ts + declare in locales/types.ts
Data	src/sections/telegram/hooks/use-telegram-*.ts (wrap the same src/actions/*.ts calls)
Components	src/sections/telegram/components/telegram-*.tsx only

---

Feature → surface mapping

Legend: ✅ full ⚠️ partial (read/display only) ❌ not present 🔮 planned

Product Templates (کالا)

Feature	Seller Dash	Platform	White-label	Mini App
Create / edit template	✅ request-template-create/edit-view	❌	❌	❌
Template list (my products)	✅ request-template-list-view	❌	✅ shop-catalog-view	❌
Template detail (buyer)	❌	✅ request-template-shop-details-view	✅ storefront-item-view	✅ telegram-template-detail-view
Browse all templates	❌	✅ public-shops-view	✅ storefront-catalog-view	✅ telegram-shop-view

Collections (مجموعه)

Feature	Seller Dash	Platform	White-label	Mini App
Create / edit collection	✅ seller-collections-new-edit-form	❌	❌	❌
Browse by collection	❌	🔮	🔮	🔮
Collection detail (buyer)	❌	🔮	🔮	🔮

Shop / Seller Profile

Feature	Seller Dash	Platform	White-label	Mini App
My shop overview	⚠️ shop-settings/*	❌	✅ shop-overview-view	❌
Public shop page	❌	✅ public-seller-shop-view, seller-profile-view	✅ storefront-catalog-view	✅ telegram-seller-shop-view
Shop branding / settings	✅ shop-settings/	❌	✅ shop-settings-view	❌
Shop admins	❌	❌	✅ shop-admins-view	❌

Requests (درخواست‌ها)

Feature	Seller Dash	Platform	White-label	Mini App
Request list (seller side)	✅ seller/marketplace	❌	✅ shop-orders-view	✅ telegram-requests-view
Request list (buyer side)	❌	✅ /dashboard/request	❌	✅ telegram-requests-view
Request detail	✅	✅	✅	✅ telegram-request-detail-view
Create new request	❌	✅ /dashboard/request/new	✅	✅ telegram-new-request-view
Request from template	❌	✅ /dashboard/request/from-template	✅	✅
Archived requests	❌	✅	❌	✅ telegram-archived-requests-view

Chat

Feature	Seller Dash	Platform	White-label	Mini App
Chat list	✅ /dashboard/chat	✅	❌	✅ telegram-chat-view
Chat thread	✅	✅	❌	✅ telegram-chat-thread-view
Archived chats	❌	✅	❌	✅ telegram-archived-chats-view

Analytics & Reporting

Feature	Seller Dash	Platform	White-label	Mini App
Analytics dashboard	✅ seller-analytics-view	❌	✅ shop-overview-view	❌
Home stats summary	❌	❌	❌	✅ telegram-home-stats

Inventory

Feature	Seller Dash	Platform	White-label	Mini App
Inventory list	✅ inventory-list-view	❌	✅ shop-inventory-view	❌
Inventory detail	✅ inventory-detail-view	❌	⚠️	❌

Customers & Reviews

Feature	Seller Dash	Platform	White-label	Mini App
Customer list	✅ seller-customers-view	❌	✅ shop-customers-view	❌
Reviews	✅ seller-reviews-view	❌	❌	❌

Payments & Wallet

Feature	Seller Dash	Platform	White-label	Mini App
Cart	❌	✅ /dashboard/shops/checkout	✅ /store/checkout	✅ telegram-cart-view
Checkout	❌	✅ request-template-checkout-view	✅	✅ telegram-checkout-view
Payment flow	✅	✅	✅	✅ telegram-payment-view
Payment history	✅	✅	✅	✅ telegram-payment-history-view
Wallet	✅ /dashboard/account/wallet	✅	❌	✅ telegram-wallet-view

Account & Profile

Feature	Seller Dash	Platform	White-label	Mini App
Profile settings	✅ /dashboard/account	✅	✅	✅ telegram-account-view
Delivery addresses	✅ /dashboard/account/address	✅	❌	✅ telegram-addresses-view
Notifications settings	✅	✅	❌	✅ telegram-notifications-view
Passkey / security	✅	✅	❌	❌

Other

Feature	Seller Dash	Platform	White-label	Mini App
AI Assist	✅ /dashboard/assist	✅	❌	✅ telegram-settings-view (assist tab)
Points / loyalty	✅ /dashboard/points	✅	❌	✅ telegram-points-view
Disputes	✅ /dashboard/disputes	✅	❌	❌
Posts / blog	✅ /dashboard/post	✅ /post	❌	❌
Dynamic pricing	✅ (admin)	❌	❌	❌

---

Porting recipes by change type

Text / copy change

1. Update en/common.json + fa/common.json (covers Seller Dash, Platform, White-label).
2. Find the matching key in src/sections/telegram/locales/types.ts → update locales/en.ts + locales/fa.ts.
3. If key doesn't exist in Mini App yet: declare it in TelegramDict (types.ts) first.

New field displayed on an entity card/row

1. Find every view that renders that entity (use mapping table above).
2. Add the field to each view using that surface's primitives — no MUI inside telegram, no TG_PALETTE outside it.
3. Add locale strings for every surface involved.

New status / enum value

1. Update TG_REQUEST_STATUS_VARIANT or TG_ESCROW_STATE_CHIPS in src/sections/telegram/constants.ts.
2. Update the corresponding color/label map in src/sections/request/constants.ts (used by Seller Dash + Platform).
3. Add the label string to all locale files.
4. Check shop-orders-view.tsx for any inline status chip that also needs updating.

New API field on a shared type

1. Update the type in src/types/*.ts.
2. Update src/actions/*.ts — the normalization function that maps API responses to the type.
3. All 4 surfaces reuse the same types and actions — they get the field for free once it's in the type.
4. Decide per surface whether to display it (add UI) or just carry it silently.

Platform has a feature Seller Dashboard is missing

Platform (/shop/*) was built later and has richer discovery, cart, and public browsing. If Platform adds something that would benefit sellers too (e.g. a filter, a sort option, a field on a product card), evaluate adding it to the Seller Dashboard equivalent view in the same PR.

---

What's intentionally surface-specific (do NOT port)

Feature	Where only	Why
Template CRUD (create/edit)	Seller Dashboard	Sellers create products; buyers only view
Collection CRUD	Seller Dashboard	Sellers organize; buyers browse (future)
Shop admins management	White-label only	Multi-admin is a tenant feature
Admin dashboard (networks, trezor, thresholds, AML)	Dashboard /admin/*	Platform operator only
Haptic feedback	Mini App only	Telegram Web App SDK, no equivalent on web
TG_PALETTE dark/light toggle	Mini App only	Uses Telegram's native color scheme
Tenant slug routing [tenantSlug]	White-label only	Multi-tenant feature

---

Checklist before merging

• Identified which surface(s) the change affects
• Checked all 3 other surfaces against the mapping table
• Ported to every surface with a full or partial equivalent
• Used each surface's own primitives (no cross-contamination)
• Added locale strings to all surfaces involved (both fa + en)
• PR description names every surface updated — and explicitly names any surface skipped