> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grouple.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Merchant Flows

> End-to-end flows for merchants and venue managers on Grouple

## Merchant Onboarding Flow

New merchants onboard via a 3-step flow (`client/components/merchant/onboarding/`):

```
StepOne — Business Profile
  - First name, last name, phone, company name, role
  - Company logo upload (→ Supabase Storage: Logos bucket)
  - Saves merchant record to DB
        ↓
StepTwo — Venue Details
  - Venue name, venue type, description, venue image (→ venue-images bucket)
  - Seated + floating capacity
  - City + neighbourhood (searched + auto-created if new)
  - Address, postal code
  - Cuisines (free text tags)
  - Amenities (free text tags)
  - DB Trigger: tr_check_venue_limit (BEFORE INSERT on venues)
        ↓
StepThree — Venue Pricing + Shifts
  - Currency selection (USD, AED, GBP, INR, EUR)
  - Min + max price per person
  - Operating hours (shifts with days + start/end time)
  - On complete → merchant.onboarding_completed = true
  - Redirects to /dashboard
        ↓
SuccessModal — "You're All Set! 🎉"
        ↓
DB Trigger: tr_check_venue_limit — enforces venue limit per subscription plan
```

## Lead Management Flow

```
Merchant receives new lead notification email (send-lead-email Edge Function)
        ↓
Goes to Leads page (/leads)
  Tabs: Pending | Accepted | Declined | Connected | Closed Won | Closed Lost | All
  Shows: RFQ ID, Customer Name, Venue, Event Date, Time Slot, 
         Group Size, Event Type, Budget, Status
        ↓
Clicks lead → RFQ Detail page (/rfq/RFQ-XXXX/pending/{venue_lead_id})
  Shows:
    Left: Event Type, Group Size, Event Date, Preferred Time, 
          Venue, Food Preference, Special Requirements
    Right: Budget Range (e.g. Standard $101-$250)
           Customer Details (Full Name, Company, Phone, Email)
  Actions: "Decline" or "Accept" buttons (when Pending)
        ↓
Merchant clicks Accept → status changes to "Accepted"
  → "Send Proposal" button appears top right
        ↓
Merchant clicks "Send Proposal" → goes to proposal creation page
        ↓
DB Trigger: trg_set_venue_lead_timestamps → records accepted_at
DB Trigger: trg_record_response_time → logs response time
```

## Lead Status Lifecycle

```
pending → accepted → connected → closed_won
                  ↘ declined
                  ↘ closed_lost
```

## Proposal Creation Flow

```
Merchant clicks "Send Proposal" on an accepted lead
        ↓
SendProposalPage → ProposalSendContainer
        ↓
Right side shows Enquiry Details (read-only context):
  Event Type, Group Size, Event Date, Event Time, Budget Range, Requirements
        ↓
Proposal form sections (all auto-filled by AI except noted):

1. Packages — Merchant selects from Sales Library
   (AI uses these for pricing context)

2. Proposal Details (AI fills automatically):
   - Proposal title
   - Choose a venue ← merchant can change
   - Event date + time (pre-filled from enquiry)
   - Group size (pre-filled from enquiry)
   - Offer validity date ← merchant fills manually

3. Executive Summary (AI fills automatically)

4. Package inclusions (AI fills automatically)

5. Pricing:
   - Amount (AI fills automatically)
   - Price type: "per person" (default) or "per event" (flat rate) ← merchant can change
   - Service fee ← merchant fills manually
   - Discount ← merchant fills manually

6. Optional add-ons (Label, Description, Price)
   → NOT included in Total Quote automatically
   → Only added to total if end customer selects them on the proposal

7. Payment terms (AI fills automatically)

8. Venue policies (AI fills automatically)

TOTAL QUOTE shown at bottom = Amount × Group Size (updates live)
        ↓
Merchant clicks "Send Proposal status: "sent"
        ↓
DB Trigger: proposal-updated-email → sends send-proposal-email Edge Function
```

## BEO (Banquet Event Order)

After a booking is confirmed, merchants can generate a BEO document (`beo/BEODocument.tsx`) containing:

* Event details, setup time, table setup
* AV requirements, staffing requirements
* Customer and venue contact information
* Financial summary

## Analytics Dashboard

`analytics/AnalyticsPage.tsx` powered by `merchant_analytics_v3` view shows:

* Total leads, wins, pending, accepted, connected, lost
* Average group size, average lead value
* Average response time (hours)
* Lead distribution by category
* Top budget tiers

## Subscription Plan Limits

Merchant actions are governed by their `subscription_plans` record:

| Limit                  | Field                      |
| ---------------------- | -------------------------- |
| Max venues             | `max_venues`               |
| Max menu PDFs          | `max_menu_pdfs`            |
| Monthly proposal limit | `monthly_proposal_limit`   |
| AI model access        | `ai_model_name`            |
| Performance insights   | `has_performance_insights` |
| Commission rate        | `success_fee_percentage`   |