# Core User Flows

Six flows that represent the majority of a merchant's time in CommerceDex. Each is described as a sequence of merchant-visible steps and system behavior, referencing the IA sections from `01-information-architecture.md` and the modules from `../architecture/04-domain-modules.md` that back them (module references are for engineering traceability only — never surfaced to the merchant).

## 1. First-run onboarding

**Goal:** get from an empty store to a sellable first product with as few decisions as possible.

1. Merchant creates their account and names their store (Settings: Store details).
2. A short guided setup asks only what can't be defaulted: currency/locale (defaulted from account locale, editable), a payment method to connect, and whether they ship physical goods (if yes, one default shipping zone/rate is pre-filled and editable; if no, shipping setup is skipped entirely).
3. Tax is defaulted based on the merchant's country/region with a sensible starting rate table — not a blank form.
4. Merchant is guided directly into adding their first product (Products), where the upload-automation flow (#2 below) takes over.
5. On completing the first product, the merchant lands on **Home**, which shows an initial Store Health Score already populated with a first recommendation or two (e.g., "Add a second product to enable bundle suggestions") — the coaching starts immediately, not after weeks of data.

**Explicitly not part of onboarding:** theme customization, advanced tax jurisdictions, staff invites, or any Settings page not required to take a first order. Those are reachable from Settings whenever the merchant wants them, not forced upfront.

## 2. Product upload with automatic assistance

**Goal:** the merchant provides the minimum (a name, a price, a photo) and the system does the rest.

1. Merchant starts a new product in **Products**, enters name, price, and uploads one or more images.
2. On upload, images are compressed, responsive variants are generated, and alt text is auto-generated from the product name/context — all before the merchant finishes filling out the rest of the form (Media Manager, invisible).
3. A URL slug and basic SEO metadata (title, description) are auto-generated from the product name and category — shown pre-filled, editable, never a blank required field (Catalog).
4. As the merchant saves, catalog-quality checks run: duplicate detection against existing products, and a flag if key info (description, category) is still missing (Automation Engine) — surfaced as a small inline note, not a blocking error.
5. Once the product is saved, Automation Engine asynchronously proposes related/complementary products, bundle candidates, and upsell/cross-sell pairings based on category and existing catalog patterns. These appear as dismissible suggestions on the product detail page and, in aggregate, in Marketing's "Suggested campaigns."

**Merchant experience:** they filled out a name, a price, and a photo. Everything else was either done for them or offered as an easy accept/dismiss choice.

## 3. Order lifecycle

**Goal:** from sale to fulfilled, with the customer kept informed automatically.

1. Customer completes checkout; the order appears in **Orders** immediately, payment status shown inline (Orders, Payments).
2. Merchant reviews the order and marks items for fulfillment; if shipping a physical good, the merchant enters or confirms a tracking number (Shipping).
3. Order status updates trigger automatic customer notifications (confirmation, shipped, delivered) with no merchant action required beyond the status change itself (Notification Service, invisible).
4. If a return/refund is needed, the merchant initiates it from the order detail page; refund processing status is shown inline (Payments) and the customer is notified automatically.
5. Completed orders feed Reports (sales metrics) and Merchant Health (fulfillment speed, refund rate as health signals) without any merchant action.

## 4. Abandoned cart & re-engagement review

**Goal:** recover lost sales with minimal merchant oversight, while keeping the merchant in control of anything customer-facing.

1. Automation Engine detects a cart abandoned past a threshold (sensible default, not merchant-configured on day one) and schedules a recovery message.
2. The recovery campaign runs automatically on a default schedule and template — the merchant is not required to build this from scratch.
3. The merchant sees abandoned-cart activity summarized on **Home** ("20 abandoned carts awaiting recovery") and in full in **Marketing**, where they can review what was sent, adjust the default template/timing, or pause the automation — but they don't have to do anything for it to work correctly out of the box.
4. If a recovered cart converts, the order flows into the normal Order lifecycle (#3) and the recovery campaign's contribution is reflected in Reports.

**Design rule this flow demonstrates:** automation owns detection and the default action; the merchant retains visibility and override, never a required setup step, per `../architecture/02-principles-and-tradeoffs.md`'s resolution on automation and merchant trust.

## 5. Store Health review

**Goal:** turn "how is my store doing" into a short, prioritized to-do list.

1. Merchant opens **Home** and sees the Store Health Score plus a short list, split into what's working ("Checkout performing well," "Inventory synchronized") and what needs attention ("Five products missing descriptions," "Three best-selling products running low on stock").
2. Each attention item is a specific, clickable recommendation — clicking "Five products missing descriptions" deep-links to **Products**, pre-filtered to exactly those five.
3. Merchant resolves items directly in context (fills in the missing descriptions in Products) and returns to Home, where the score and list update to reflect the change.
4. No item on this list is ever a raw metric without an accompanying action — if Merchant Health can't suggest what to do about a signal, it doesn't surface that signal here (it may still appear in Reports, which is allowed to be descriptive rather than prescriptive).

## 6. Discount & campaign creation

**Goal:** let a merchant create a promotion in minutes, or accept one the system already drafted.

1. Merchant starts a new discount in **Marketing**, choosing a type (percentage off, fixed amount, free shipping, bundle price) from a short opinionated list — not an open-ended rule builder.
2. Eligibility (which products, which customer segment) is set using existing Products categories and Customers segments — no separate "rule engine" concept exposed to the merchant.
3. Alternatively, the merchant accepts a system-suggested discount (e.g., generated from slow-moving inventory detection) directly from **Marketing**'s "Suggested campaigns," pre-filled and ready to launch or lightly edit.
4. Once live, the discount applies automatically at checkout (Discount Engine, Core-tier — always correct, always synchronous) and its performance rolls up into Reports.