ProjectR Docs
Screen MapDashboard

Products & groups

Dashboard: every screen, state and flow in Products & groups.

18 screens and overlays, 69 states, 1 flows. Frames show a real screenshot where one was captured and a wireframe card where the state needs data or conditions a device run cannot produce.

Flows

Products and groups

Step 1
Product Management (Web)
Product table with filters and bulk actions
Open a row
Step 2
Product Detail (Web)
Product detail with override form
Save All Overrides
Step 3
Product Detail, Save disabled unless dirty (Web)
Save stays disabled until a field changes
Open Groups
Step 4
Product Groups (Web)
Product groups list
Open a group
Step 5
Product group detail (Web)
Group detail
Edit
Step 6
Edit Product Group (Web)
Edit group, Details and Products tabs

Branches and edge cases

Errorfrom step 1
Create New Product, Product Creation Not Available (Web)
New Product
Edgefrom step 1
Set Badge (Web)
Bulk badge or featured
Edgefrom step 1
Wireframe

Product Management

Loading

Sync running

Sync button shows Syncing... and is disabled

Needs data: Needs specific backend rows, a role, or a submitted write on a disposable record

Sync from Shopify
Edgefrom step 1
Filters (Web)
Filters
Errorfrom step 2
Wireframe

Product Detail

Edge

Partial save

Nothing saved or Saved override, en. Failed: ms (message)

Not reachable on a device: Needs a server error, crash, race or code change

Some overrides fail
Gatefrom step 2
Wireframe

Delete Override?

Needs data: Needs a product that has overrides

Delete Override
Gatefrom step 2
Wireframe

Delete beauty tag

Needs data: Needs a product with a beauty tag

Beauty tag editor delete
Successfrom step 4
Wireframe

Create Product Group

Success

Group created

Toast Product group created successfully

Needs data: Needs specific backend rows, a role, or a submitted write on a disposable record

New group
Gatefrom step 5
Delete Group? (Web)
Delete group
Errorfrom step 6
Wireframe

Edit Product Group

Error

Mirrored group refused

Server refuses add, remove, reorder but UI shows generic failure

Needs data: Needs specific backend rows, a role, or a submitted write on a disposable record

Mirrored group refuses membership edits
Flow diagram

Screens and states

Unsaved Changes

Unsaved Changes (Web)
DialogUnsavedChangesDialog

Unsaved Changes

Guard leaving edit mode with unsaved override edits.

src/features/products/components/product-view.tsx

Entry

  • Toggle to View Mode while dirty

Exits

  • Discard → leaves edit mode
  • Stay → keeps editing

States · 1

Edge
Dirty form guard · Opens only when the override form has unsaved editssrc/features/products/components/product-view.tsx:497

Product Management

Product Management (Web)
Screen/dashboard/products

Product Management

Search and filter the mirrored Shopify catalogue; edit marketing overrides.

src/app/dashboard/products/page.tsx

Entry

  • Sidebar Products
  • Delete override redirect
  • Back from /products/new

Exits

  • Title or View Details → /products/[id]
  • View in Store → external store URL
  • New Product → /products/new
  • Sync → reads from Shopify, toast
  • Export (admin) → Export dialog
  • Bulk bar → Featured or badge

States · 9

Loading
Route skeleton · DataTableSkeleton 6x10 from loading.tsx, plus table skeleton while loadingsrc/app/dashboard/products/loading.tsx
Empty
No products · Same copy for no filter match and empty cataloguesrc/features/products/components/product-table.tsx:98
Error
Could not load products · Query error shown with the hook error stringsrc/features/products/components/product-listing.tsx:207
Edge
Filters not in URL · Search, tab and sheet filters live in React state and reset on reloadsrc/features/products/components/product-listing.tsx
Edge
Page resets to 1 · Changing tab, search or sheet filters resets paginationsrc/features/products/components/product-listing.tsx:69
Gate
Export admin only · Export button hidden behind AdminOnly; Create and Sync have no client gatesrc/features/products/components/product-listing.tsx:168
Loading
Sync running · Sync button shows Syncing... and is disabledsrc/features/products/components/product-listing.tsx:84
Success
Sync result toast · Toast shows the sync result messagesrc/features/products/components/product-listing.tsx:84
Edge
Mobile columns · Mobile shows only select, image, title and actionssrc/features/products/components/product-table.tsx:37

Filters

Filters (Web)
SheetProductFiltersSheet

Filters

Filter products by override and featured flags.

src/features/products/components/product-filters.tsx

Entry

  • Filters button on products list

Exits

  • Apply → closes, filters list
  • Clear → resets filters

States · 2

Edge
Active filter badge · Filter count badge shows on the Filters buttonsrc/features/products/components/product-listing.tsx:74
Edge
Filter options · Override: Any, Custom, Default. Featured: Any, Featured Only, Regularsrc/features/products/components/product-filters.tsx:91

Set Badge

Set Badge (Web)
DialogProductBulkBadgeDialog

Set Badge

Apply a badge label to the selected products (Convex only).

src/features/products/components/product-bulk-actions.tsx

Entry

  • Bulk bar Set Badge

Exits

  • Confirm → useBulkSetBadge
  • Cancel → closes

States · 2

Success
Bulk featured or badge set · Set or Remove Featured and Set Badge write Convex only, never Shopifysrc/features/products/components/product-bulk-actions.tsx:83
Edge
Row actions not role gated · A dashboard-role user can click and gets Admin access requiredlib/access-control.ts

Create New Product

Create New Product (Web)
Screen/dashboard/products/new

Create New Product

Dead end that sends the user to Shopify admin to create products.

src/app/dashboard/products/new/page.tsx

Entry

  • New Product on products list

Exits

  • Go Back → previous page
  • Create in Shopify → Shopify admin (external)

States · 3

Edge
Product Creation Not Available · Static info card; the dashboard cannot create productssrc/features/products/components/product-form.tsx:282
Error
Creation not supported toast · Dead handleSave in create mode toasts Product creation not supportedsrc/features/products/components/product-form.tsx:201
Gate
products:create · Admin permission required; no loading, empty or validation statessrc/app/dashboard/products/new/page.tsx

Captured states

Create New Product, Product Creation Not Available (Web)
Product Creation Not Available

Product Detail

Product Detail (Web)
Screen/dashboard/products/[id]

Product Detail

View a product and edit override, localization, SEO and beauty tags.

src/app/dashboard/products/[id]/page.tsx

Entry

  • Products list title or menu
  • /products/[id]/edit redirect
  • Group detail product rows

Exits

  • View or Edit Mode toggle → ?mode=edit
  • View in Store → external link
  • Sync → reads product from Shopify
  • Featured switch → immediate toast
  • Save All Overrides → multi-step save
  • Delete Override → list

States · 14

Loading
Centred spinner · Spinner while loading; parent products skeleton shows on navigationsrc/features/products/components/product-view.tsx:524
Error
Product not found · Plain text error or Product not found with no back linksrc/features/products/components/product-view.tsx:535
Edge
Save disabled unless dirty · Cancel and Save All stay disabled until the override form is dirtysrc/features/products/components/product-view.tsx
Edge
Unsaved changes prompt · beforeunload prompt and Unsaved Changes dialog when leaving edit mode dirtysrc/features/products/components/product-view.tsx:325
Empty
Not in any group · This product is not in any custom product groupssrc/features/products/components/product-view.tsx:1054
Edge
Partial save · Nothing saved or Saved override, en. Failed: ms (message)src/features/products/components/product-override-form.ts:174
Error
Form validation toast · First Zod issue toasts (Check the form fallback); no inline field errorssrc/features/products/components/product-view.tsx:336
Error
Hero image URL invalid · Hero image must be an http(s) URLsrc/features/products/components/product-override-form.ts:26
Error
Badge too long · Badge must be 20 characters or lesssrc/features/products/components/product-override-form.ts:26
Error
No routine step selected · Beauty tag save toasts Please select a routine stepsrc/features/products/components/beauty-tags/product-beauty-tag-editor.tsx:181
Error
Missing Shopify reference · Beauty tag save toasts Missing Shopify product referencesrc/features/products/components/beauty-tags/product-beauty-tag-editor.tsx:181
Edge
English falls back to Shopify · Empty English title or description uses the Shopify valuessrc/features/products/components/product-override-form.ts
Edge
Locale saved only if filled · A locale is saved only when it has a non-blank fieldsrc/features/products/components/product-override-form.ts
Gate
Edit form shown to all · Page gated on products:view; saves fail server side for non-adminssrc/app/dashboard/products/[id]/edit/page.tsx:12

Captured states

Product Detail, Save disabled unless dirty (Web)
Save disabled unless dirty

Delete Override?

Wireframe

Delete Override?

Needs data: Needs a product that has overrides

DialogDeleteOverrideDialog

Delete Override?

Confirm removing the marketing override and reverting to Shopify data.

src/features/products/components/product-view.tsx

Entry

  • Delete Override button

Exits

  • Confirm → override deleted, /products
  • Cancel → closes

States · 1

Success
Override deleted · Toast Override deleted then redirect to the products listsrc/features/products/components/product-view.tsx:467

Delete beauty tag

Wireframe

Delete beauty tag

Needs data: Needs a product with a beauty tag

DialogBeautyTagDeleteDialog

Delete beauty tag

Confirm removing a product beauty tag.

src/features/products/components/beauty-tags/product-beauty-tag-editor.tsx

Entry

  • Beauty tag delete action

Exits

  • Confirm → tag deleted
  • Cancel → closes

States · 1

Edge
Beauty tag form rules · AM/PM toggles, priority 1 to 100, display order >= 0, step requiredsrc/features/products/components/beauty-tags/product-beauty-tag-editor.tsx:495

Product edit redirect

Product edit redirect (Web)
Redirect/dashboard/products/[id]/edit

Product edit redirect

Server redirect to the product page in edit mode.

src/app/dashboard/products/[id]/edit/page.tsx

Entry

  • Old links and bookmarks

Exits

  • Redirect → /products/[id]?mode=edit&tab=override

States · 1

Edge
Not gated itself · Target is gated by products:view, not updatesrc/app/dashboard/products/[id]/edit/page.tsx:12

Product Groups

Product Groups (Web)
Screen/dashboard/products/groups

Product Groups

Manage curated product collections.

src/app/dashboard/products/groups/page.tsx

Entry

  • Product detail Groups tab
  • Direct URL

Exits

  • New Group → /groups/new
  • Name or View → /groups/[id]
  • Edit → /groups/[id]/edit
  • Delete → Delete dialog
  • Bulk Publish or Unpublish → per-group calls

States · 5

Loading
Suspense skeleton · Suspense skeleton and list loading flagsrc/app/dashboard/products/groups/page.tsx:13
Empty
No product groups · No product groups found. Create one to organize your products.src/features/products/components/groups/group-listing.tsx:99
Error
Groups failed to load · ErrorEmptyState shown on query errorsrc/features/products/components/groups/group-listing.tsx:149
Edge
Bulk partial failure · Toast Failed after publishing X of N groupssrc/features/products/components/groups/group-bulk-actions.tsx:48
Edge
Filter drawer · Status All, Published, Draft; Group Type All, Featured, Category, Seasonal, Promotion, Customsrc/features/products/components/groups/group-filters.tsx:118

Delete Product Group

Delete Product Group (Web)
DialogGroupDeleteDialog

Delete Product Group

Confirm permanent group delete; products themselves are kept.

src/features/products/components/groups/group-delete-dialog.tsx

Entry

  • Row menu Delete

Exits

  • Delete → toast, back to list
  • Cancel → closes

States · 2

Edge
Consequences listed · Permanent, unassigns products, removes localizations; products not deletedsrc/features/products/components/groups/group-delete-dialog.tsx:60
Success
Group deleted · Toast Product group deleted successfullysrc/features/products/components/groups/group-delete-dialog.tsx:43

Create Product Group

Create Product Group (Web)
Screen/dashboard/products/groups/new

Create Product Group

Create a group with slug, type, image and publish switch.

src/app/dashboard/products/groups/new/page.tsx

Entry

  • New Group button

Exits

  • Back to Groups link
  • Cancel → list (unsaved dialog)
  • Submit → /groups/[newId]

States · 11

Edge
Slug auto-generated · Slug follows the name until editedsrc/features/products/components/groups/group-form.tsx:270
Loading
Slug uniqueness check · Debounced check; Submit disabled while checking or takensrc/features/products/components/groups/group-form.tsx:160
Error
Slug taken · Slug x is already used by ysrc/features/products/components/groups/group-form.tsx:160
Error
Duplicate slug on server · A group with this slug already existspackages/backend/convex/dashboard/mutations.ts
Success
Image uploaded · Image uploaded. Save to confirm changes.src/features/products/components/groups/group-form.tsx:291
Error
Image upload failed · Upload failed. Please try again.src/features/products/components/groups/group-form.tsx:291
Edge
Localizations not saved · en, ms, zh name and description are collected but the backend ignores themsrc/features/products/components/groups/group-form.tsx:350
Edge
Mirrored collection handle · A set sourceCollectionHandle mirrors a Shopify collection and locks membershipsrc/features/products/components/groups/group-form.tsx
Error
Name required · Name is required, max 100 characterssrc/features/products/components/groups/group-form.tsx:59
Error
Slug format · Slug must be lowercase letters, numbers, and hyphens onlysrc/features/products/components/groups/group-form.tsx:59
Success
Group created · Toast Product group created successfullysrc/features/products/components/groups/group-form.tsx:386

Product group detail

Product group detail (Web)
Screen/dashboard/products/groups/[id]

Product group detail

Read-only group detail with its products.

src/app/dashboard/products/groups/[id]/page.tsx

Entry

  • Group list
  • Create redirect
  • Edit Back
  • Product Groups tab

Exits

  • Back to Groups
  • Edit → /groups/[id]/edit
  • Product row → /products/[id]

States · 4

Loading
Detail skeleton · Header, details card with 8 rows, products card with 5 rowssrc/app/dashboard/products/groups/[id]/loading.tsx
Error
Failed to Load Group · Error card with message, Code, Error ID, Back and Try Againsrc/app/dashboard/products/groups/[id]/error.tsx:23
Error
Group not found · Plain Group not found textsrc/features/products/components/groups/group-view.tsx:50
Empty
No products in this group yet · Group has no productssrc/features/products/components/groups/group-view.tsx:168

Edit Product Group

Edit Product Group (Web)
Screen/dashboard/products/groups/[id]/edit

Edit Product Group

Edit group details and manage its products.

src/app/dashboard/products/groups/[id]/edit/page.tsx

Entry

  • Group list menu Edit
  • Group detail Edit

Exits

  • Back → /groups/[id]
  • Save details → /groups/[id]
  • Delete Group → Delete dialog
  • Add products → picker dialog
  • Remove products → confirm
  • Drag reorder → reorder call

States · 9

Loading
Edit skeleton · Route loading.tsx while group loadssrc/app/dashboard/products/groups/[id]/edit/loading.tsx
Error
Edit error boundary · Route error.tsxsrc/app/dashboard/products/groups/[id]/edit/error.tsx
Error
Group not found · Group not found with Back to Groups buttonsrc/features/products/components/groups/group-edit-view.tsx:79
Edge
Details saved, publish failed · updateProductGroup then publish call; second failure leaves details savedsrc/features/products/components/groups/group-form.tsx:358
Error
Mirrored group refused · Server refuses add, remove, reorder but UI shows generic failuresrc/features/products/components/groups/group-products-manager.tsx:244
Error
Generic remove failure · Failed to remove product(s) or Failed to reorder productssrc/features/products/components/groups/group-products-manager.tsx:307
Success
Products updated toasts · Product removed, Removed N product(s), Products reordered successfullysrc/features/products/components/groups/group-products-manager.tsx
Edge
Optimistic reorder · Drag reorder is optimistic and rolls back on failuresrc/features/products/components/groups/group-products-manager.tsx
Edge
Slug check skipped · In edit the uniqueness check skips when slug is unchangedsrc/features/products/components/groups/group-form.tsx:198

Unsaved Changes

Unsaved Changes (Web)
DialogGroupUnsavedTabDialog

Unsaved Changes

Guard switching tabs with a dirty Details form.

src/features/products/components/groups/group-edit-view.tsx

Entry

  • Switch tab while dirty

Exits

  • Stay → keeps editing
  • Discard → switches tab

States · 1

Edge
Dirty tab switch · Opens only when the Details form is dirtysrc/features/products/components/groups/group-edit-view.tsx:215

Delete Group?

Delete Group? (Web)
DialogGroupDeleteAlert

Delete Group?

Confirm delete from the edit screen.

src/features/products/components/groups/group-edit-view.tsx

Entry

  • Delete Group button

Exits

  • Delete → /products/groups
  • Cancel → closes

States · 1

Success
Group deleted · Toast Group deleted successfullysrc/features/products/components/groups/group-edit-view.tsx:60

Add products

Add products (Web)
DialogProductPickerDialog

Add products

Server-side product search (limit 100) to add products to a group.

src/features/products/components/groups/group-product-picker.tsx

Entry

  • Add products on Products tab

Exits

  • Select → adds to group
  • Close → cancels

States · 1

Edge
Mirrored group add refused · Add relies on the picker's own handling of the server refusalsrc/features/products/components/groups/group-product-picker.tsx

Remove Product(s)?

Wireframe

Remove Product(s)?

Needs data: Needs a group with products

DialogGroupRemoveProductsAlert

Remove Product(s)?

Confirm removing one or many products from a group.

src/features/products/components/groups/group-products-manager.tsx

Entry

  • Remove action or multi-select

Exits

  • Remove → toast
  • Cancel → closes

States · 1

Success
Removed from group · Toast Product removed or Removed N product(s)src/features/products/components/groups/group-products-manager.tsx:435

Orders & checkout sessions

Dashboard: every screen, state and flow in Orders & checkout sessions.

Content: campaigns, carousel, avatars

Dashboard: every screen, state and flow in Content: campaigns, carousel, avatars.

On this page

FlowsProducts and groupsScreens and statesUnsaved ChangesProduct ManagementFiltersSet BadgeCreate New ProductProduct DetailDelete Override?Delete beauty tagProduct edit redirectProduct GroupsDelete Product GroupCreate Product GroupProduct group detailEdit Product GroupUnsaved ChangesDelete Group?Add productsRemove Product(s)?