# Walkthrough (https://prood.com/docs/run-locally/walkthrough)

This guide walks through the **end-to-end customer flow** using the default local setup. No code changes required — just env vars and running servers.

## Before you start [#before-you-start]

Ensure you have completed [Installation](/docs/run-locally/installation):

- `pnpm db:migrate` and `pnpm db:seed` completed successfully
- `pnpm dev` running (or at least the storefront `:3000`, the gateway `:3001`, dashboard `:3002`, checkout `:3004` and api `:3005`; the gateway is where `/dashboard`, `/pay` and `/v1` are served)
- `NEXT_PUBLIC_PLATFORM_DOMAIN=localhost` in `.env.local`, so the demo store is served at `prood-demo.localhost:3000`

The demo store is for browsing: the API refuses its orders with "This is a demo store, so it can't take orders." To take an order, [register a store](http://localhost:3001/dashboard/register) in the local dashboard, add a product with the status **Active**, and connect Stripe (or another provider) under **Integrations**. It's served at `{your-store-address}.localhost:3000`.

Checkout also needs Upstash Redis. Without it, checkout session creation fails.

## Step 1 — Browse the storefront [#step-1--browse-the-storefront]

Open [http://prood-demo.localhost:3000](http://prood-demo.localhost:3000). Bare `localhost:3000` isn't a store, so it redirects to the marketing site.

The home page loads featured products and categories. Catalog data is fetched from the Commerce API and cached per tenant with Next.js Cache Components (`'use cache'` + tenant-scoped cache tags).

Navigate to **Products** to see the full catalog with search and sort.

## Step 2 — Add items to the cart [#step-2--add-items-to-the-cart]

Switch to the store you registered, at `{your-store-address}.localhost:3000`, and click **Add to cart** on your product. The storefront:

1. Reads or creates a cart via the local BFF route `POST /api/commerce/cart/items`
2. Stores the cart ID in an HTTP-only cookie (`commerce_cart_id`, 30-day TTL)
3. Updates the cart drawer UI via React context

Open the cart drawer (header icon) to review items or adjust quantities.

## Step 3 — Start checkout [#step-3--start-checkout]

Go to `/checkout` or click **Checkout** in the cart drawer.

The checkout page collects:

- Customer email and name
- Shipping address (when fulfillment requires shipping)
- Billing address (optional)

When you submit, the server action `startCheckout()` in `apps/storefront/app/(checkout)/checkout/actions.ts`:

1. Calls the API `POST /v1/carts/{id}/place-order` to create an order
2. Creates a checkout session on `apps/checkout` via `POST /api/sessions`
3. Redirects the browser to `http://localhost:3001/pay/c/{sessionId}`

## Step 4 — Complete payment [#step-4--complete-payment]

On the checkout app payment page:

| Provider | Experience |
| --- | --- |
| **Stripe** | Embedded Payment Element: enter test card `4242 4242 4242 4242` |
| **Easypay** | Reference-based — Multibanco entity/reference or MB WAY |
| **Ifthenpay** | Reference-based — Multibanco, MB WAY, or card redirect |

After successful payment, you are redirected to `/confirm/{sessionId}` and then back to the storefront order confirmation page.

## Step 5 — Verify in the dashboard [#step-5--verify-in-the-dashboard]

Sign in to the merchant dashboard at [http://localhost:3001/dashboard](http://localhost:3001/dashboard).

Use the account you registered the store with.

Navigate to **Orders** to see the order you just placed. You can fulfill, refund, or view order details.

## What happened under the hood [#what-happened-under-the-hood]

```mermaid
sequenceDiagram
  participant C as Customer browser
  participant SF as Storefront
  participant API as Commerce API
  participant CHK as Checkout app
  participant PP as Payment provider

  C->>SF: Browse / cart / checkout
  SF->>API: BFF → /v1/carts/*
  C->>SF: startCheckout()
  SF->>API: POST place-order
  SF->>CHK: POST /api/sessions
  C->>CHK: /c/{id}
  CHK->>PP: Process payment
  PP->>CHK: Webhook
  CHK->>API: Forward webhook
  API->>API: Update order status
```

## API quick test [#api-quick-test]

You can also interact with the API directly:

```bash
# Health check
curl http://localhost:3001/v1/health

# List the demo store's products (tenant from the storefront host)
curl -H "x-storefront-host: prood-demo.localhost" http://localhost:3001/v1/products

# OpenAPI spec
curl http://localhost:3001/v1/openapi.json
```

Browse the interactive reference at [Commerce API](/docs/api).

## Next steps [#next-steps]

<Cards>
  <Card title="Storefront guide" href="/docs/apps/storefront" description="Deep dive into pages, cart BFF, and tenant resolution." />
  <Card title="Checkout guide" href="/docs/apps/checkout" description="Sessions, Redis, payment providers, and webhooks." />
  <Card title="Payment integration" href="/docs/guides/payment-integration" description="Configure Stripe, Easypay, or Ifthenpay per tenant." />
  <Card title="Multi-tenancy" href="/docs/architecture/multi-tenant" description="How organizations, domains, and RLS isolate merchant data." />
</Cards>