route-commerce/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Route Commerce is a multi-tenant B2B e-commerce platform for fresh produce wholesale distribution. Brands sell to customers who pick up at scheduled stops or receive shipments. The platform includes admin dashboards for order management, stop/route scheduling, product catalogs, payment processing (Stripe + Square), and a communications module ("Harvest Reach") for email/SMS campaigns.

Tech stack: Next.js 16 (App Router) · Supabase (auth + Postgres + RLS) · Stripe · Square · Resend (email) · Tailwind CSS v4

---

Commands

npm run dev          # Start dev server (runs fix-agents.js first to patch Next.js App Router agent issues)
npm run build        # Production build
npm run lint          # ESLint
npm run migrate:one   # Push a migration (pass digits only, e.g. `npm run migrate:one 83` runs 083_*.sql)
npx tsc --noEmit     # TypeScript check (no emit)
npx playwright test  # Run E2E tests (Playwright)

The migrate script auto-detects Supabase CLI first, then falls back to direct PostgreSQL. For CLI mode: brew install supabase/tap/supabase then supabase link --project-ref wnzkhezyhnfzhkhiflrp For direct PG mode: pg and dotenv are already in devDependencies. If get_brand_settings migration fails with "cannot change return type", the function signature changed — drop and recreate it first.

Recent migration work is documented in MEMORY.md (Supabase login + link process, updates to push-migrations.js for modern CLI, specific SQL patches made to 091/145/148/200/201 so they would apply cleanly, and which migrations were pushed in the session). Cat MEMORY.md for details.

No test suite currently exists. E2E tests use Playwright (tests/ or test-e2e.ts).

---

Architecture

Authentication & Authorization

Dev mode bypasses Supabase auth entirely via dev_session cookie set by /login:

• dev_session=platform_admin — full access, all brands
• dev_session=brand_admin — full access to assigned brand only
• dev_session=store_employee — limited access (orders, pickup, wholesale only)

src/lib/admin-permissions.ts is the single source of truth for the current admin user. It uses a dev_session cookie in development and Supabase Auth in production. Never import this file directly into Client Components — use the getCurrentAdminUser server action from @/actions/admin-user instead.

The AdminUser type lives in src/lib/admin-permissions-types.ts and is shared across server/client boundary.

Server Actions Pattern

All database writes go through server actions in src/actions/. These:

1. Call getAdminUser() to verify auth
2. Check role/permission flags (can_manage_orders, etc.)
3. Call Supabase REST APIs (not the Supabase client directly in server actions) to trigger SECURITY DEFINER RPCs
4. Return typed results ({ success: true, ... } | { success: false, error: string })

Server actions are "use server" files that export async functions. Client components import and call them directly.

SECURITY DEFINER RPCs + Brand Scoping

The app uses PostgreSQL SECURITY DEFINER functions for all data access. These run with the function owner's privileges and bypass RLS entirely. This means:

• Brand isolation must be enforced at the application layer (in server actions), not in database policies
• Every RPC that touches brand-scoped data accepts a p_brand_id UUID parameter and filters by it
• The pattern in server actions: effectiveBrandId = brandId ?? adminUser.brand_id ?? null — use explicitly passed brandId when available (from page server components), falling back to the admin's assigned brand

Critical consequence: When getAdminUser() returns brand_id: null (e.g., dev_session platform_admin or certain dev auth states), p_brand_id passed to RPCs will be null. The RPCs handle this by returning all brands' data for platform_admin scope.

Brand ID Threading

Pages under /admin/ are server components that resolve brandId from getAdminUser() and pass it as a prop to client components. Always thread brandId through the entire component tree — never use hardcoded BRAND_ID constants in client components that accept a brandId prop. The pattern:

// admin/orders/page.tsx (server component)
const adminUser = await getAdminUser();
const effectiveBrandId = adminUser.brand_id ?? undefined; // platform_admin gets all brands
return <OrdersPanel brandId={effectiveBrandId} />;

// OrdersPanel.tsx (client component) — use brandId prop, not constants

Public Storefront Architecture

Brand storefronts (/tuxedo/*, /indian-river-direct/*) are isolated from the platform shell. The root layout.tsx detects brand routes via usePathname() and suppresses SiteHeader/SiteFooter for those paths. Brand pages use StorefrontHeader/StorefrontFooter directly.

Brand settings (hero tagline, about headline, feature toggles, etc.) are stored in brand_settings and fetched publicly via getBrandSettingsPublic(brandSlug) server action (no auth required). The get_brand_settings_by_slug RPC merges brand_settings + wholesale_settings.wholesale_enabled in one call.

The StorefrontHeader and StorefrontFooter components accept:

StorefrontHeader: { brandName, brandSlug, logoUrl?, showWholesaleLink?, isAdmin? }
StorefrontFooter: { brandName, brandSlug, logoUrl?, customFooterText?, contactEmail?, contactPhone?, isAdmin? }

Feature Flags + Add-ons

Add-on features are managed via the brand_features table and src/lib/feature-flags.ts. The ADDON_CATALOG defines all available add-ons. Check isFeatureEnabled(brandId, key) in server components. Toggle via toggleBrandFeature(brandId, key, enabled) in src/actions/settings/features.ts. The /admin/settings/apps page provides a UI for enabling/disabling add-ons per brand.

Billing + Plan Tiers

Each brand has a plan_tier in the brands table: starter | farm | enterprise. Plan limits (max_users, max_stops_monthly, max_products) are also stored on the brand. Usage is computed live from actual table counts via get_brand_plan_info RPC.

Tier	Price	Includes
Starter	$49/mo	Products, Stops (10/mo), Orders, Basic Pickup, 1 user, 25 products
Farm	$149/mo	Everything in Starter + Wholesale Portal, Harvest Reach, unlimited stops/products, 5 users, priority support
Enterprise	Custom	Everything in Farm + AI Intelligence Pack, SMS Campaigns, Square Sync, Water Log, unlimited users, unlimited brands, custom development, dedicated SLA

Add-ons are available à la carte on any plan: wholesale_portal ($99/mo), harvest_reach ($79/mo), ai_tools ($59/mo), water_log ($39/mo), square_sync ($39/mo), sms_campaigns ($29/mo).

Billing page: /admin/settings/billing — shows plan tier, usage stats, enabled add-ons, Stripe Customer Portal link (if stripe_customer_id set), and platform invoice history.

Stripe Billing Integration

Real Stripe subscription management is integrated via:

• src/actions/billing/stripe-checkout.ts — createStripeCheckoutSession, createPlanUpgradeCheckout, createAddonCheckoutSession, cancelAddonSubscription
• src/app/api/stripe/webhook/route.ts — handles checkout.session.completed, customer.subscription.updated/deleted, invoice.payment_succeeded/failed

When a subscription checkout completes, the webhook automatically:

1. Saves stripe_subscription_id, stripe_subscription_status, and stripe_current_period_end to the brand via set_brand_subscription RPC
2. Enables the corresponding feature flag via set_brand_feature for add-ons
3. Updates plan tier via update_brand_plan_tier for plan changes

Required Stripe Credentials

Environment variables (.env.local for local, hosting dashboard for production):

Variable	Format	Where to get
STRIPE_SECRET_KEY	sk_live_... or sk_test_...	Stripe Dashboard → Developers → API Keys → Secret key
STRIPE_PUBLISHABLE_KEY	pk_live_... or pk_test_...	Same page — used for Stripe.js in client components
STRIPE_WEBHOOK_SECRET	whsec_...	Stripe Dashboard → Developers → Webhooks → select endpoint → Signing secret

Stripe Price IDs (create products/prices in Stripe Dashboard first):

Variable	Product to create in Stripe
STRIPE_PRICE_STARTER	Recurring $49/mo — Starter plan
STRIPE_PRICE_FARM	Recurring $149/mo — Farm plan
STRIPE_PRICE_ENTERPRISE	Recurring $399/mo — Enterprise plan
STRIPE_PRICE_HARVEST_REACH	Recurring $79/mo — Harvest Reach add-on
STRIPE_PRICE_WHOLESALE_PORTAL	Recurring $99/mo — Wholesale Portal add-on
STRIPE_PRICE_WATER_LOG	Recurring $39/mo — Water Log add-on
STRIPE_PRICE_AI_TOOLS	Recurring $59/mo — AI Intelligence add-on
STRIPE_PRICE_SQUARE_SYNC	Recurring $39/mo — Square Sync add-on
STRIPE_PRICE_SMS_CAMPAIGNS	Recurring $29/mo — SMS Campaigns add-on

For annual pricing, create separate annual prices in Stripe (e.g., $441/yr for Starter = $49/mo * 12 * 0.75) and use different price IDs. Pass annual=true to createStripeCheckoutSession to select the annual price key.

Webhook setup (Stripe Dashboard → Developers → Webhooks → Add endpoint):

• URL: https://yourdomain.com/api/stripe/webhook
• Events to listen for: checkout.session.completed, customer.subscription.updated, customer.subscription.deleted, invoice.payment_succeeded, invoice.payment_failed

UI Payments settings (/admin/settings/payments):

• The stripe_customer_id on the brand record is set when the brand connects Stripe via the Payments settings UI (OAuth flow or manual key entry). Once set, billing checkout sessions can be created for that brand.

Adding a New Brand

1. Create brand record in brands table:

   INSERT INTO brands (id, name, slug, plan_tier, max_users, max_stops_monthly, max_products)
   VALUES (gen_random_uuid(), 'Sunrise Farms', 'sunrise-farms', 'starter', 2, 20, 50);
   

2. Initialize wholesale_settings (required for portal):

   INSERT INTO wholesale_settings (brand_id, require_approval, wholesale_enabled)
   VALUES ('<brand-uuid>', true, true);
   

3. Add-ons are always opt-in — enable specific features via brand_features table or /admin/settings/apps UI.

4. Create public storefront — duplicate /app/tuxedo/ → /app/sunrise-farms/, update brand constants and slug.

5. Set Stripe customer ID (for billing portal) — set stripe_customer_id column on the brand via Payments settings or API once Stripe is connected.

Multi-Tenant Data Model

• brands — each brand has its own products, stops, wholesale settings, communication contacts
• orders — belong to a brand (via brand_id), may belong to a stop (via stop_id) or be shipping-only
• order_items — each item has fulfillment: 'pickup' | 'ship'
• stops — belong to a brand, have address, datetime, status
• customers (communication_contacts) — belong to a brand, track email/sms opt-in separately

Communications Module ("Harvest Reach")

The communications system (/admin/communications) uses a separate set of tables that are NOT protected by RLS — they rely entirely on the SECURITY DEFINER RPCs + application-layer brand scoping. Key tables: communication_campaigns, communication_templates, communication_contacts, communication_message_logs.

send_campaign / send_stop_blast RPCs insert into communication_message_logs but do NOT populate event_id. The Resend webhook (src/app/api/resend/webhook/route.ts) must therefore look up logs by customer_email + subject + created_at (7-day window), not by event_id.

Payments

• Stripe — primary payment processor; src/actions/payments.ts and src/app/api/stripe/ handle checkout, webhooks, refunds
• Square — optional sync for inventory/products; src/actions/square-*.ts and src/app/api/square/
• Wholesale deposits use a separate wholesale_deposits table with payment_method: 'stripe' | 'square'

Water Log

Separate from orders/stops — tracks irrigation/water usage per brand. src/actions/water-log/ and src/app/admin/water-log/. Uses its own water_logs table.

---

Key Conventions

• All DB mutations use Supabase REST API (fetch to ${supabaseUrl}/rest/v1/rpc/...) from server actions, NOT the Supabase JS client (avoids SSR cookie issues)
• gen_random_uuid() used in migrations for primary keys
• Migrations use CREATE OR REPLACE FUNCTION for idempotency — never DROP then CREATE
• Status enums stored as TEXT — no PostgreSQL ENUM type
• Timestamps use TIMESTAMPTZ for timezone awareness
• Address fields on orders table are minimal (customer_address TEXT) — full structured address (postal_code, state, country) may not exist; check before assuming FedEx-ready address format
• Migration files: numbered sequentially (e.g., 083_*.sql), never reuse numbers
• All display dates use formatDate() from src/lib/format-date.ts (MM/DD/YYYY US locale) — never use raw toLocaleDateString() in components

---

Important File Locations

Concern	Location
Admin auth + permissions	src/lib/admin-permissions.ts, src/lib/admin-permissions-types.ts
Middleware (route protection)	src/middleware.ts
Server actions	src/actions/*.ts (one file per domain)
Admin pages	src/app/admin/[module]/page.tsx
Admin client components	src/components/admin/*.tsx
Migrations	supabase/migrations/
Supabase client	src/lib/supabase.ts
Email templates	src/lib/email-templates.ts
Date formatting	src/lib/format-date.ts
Feature flags	src/lib/feature-flags.ts
Square sync settings UI	src/app/admin/settings/square-sync/
Wholesale portal	src/app/wholesale/, src/actions/wholesale*.ts
Billing + plan actions	src/actions/billing/stripe-portal.ts
Add-on settings UI	src/app/admin/settings/apps/
Billing page	src/app/admin/settings/billing/
Brand storefront header/footer	src/components/storefront/StorefrontHeader.tsx, src/components/storefront/StorefrontFooter.tsx
Paginated stops (public)	src/components/storefront/PaginatedStops.tsx

---

Gotchas

• Dev mode brand_id: null: getAdminUser() returns brand_id: null for platform_admin dev sessions. Always pass explicit brandId to server action functions that accept it — don't rely on adminUser.brand_id alone.
• Communications = no RLS: The communications tables (campaigns, templates, contacts, message_logs) have RLS disabled. All brand scoping must be enforced in server actions.
• Webhook event_id: log_communication_messages never populates event_id, so the Resend webhook uses customer_email + subject lookup instead.
• Mixed fulfillment orders: An order can have both pickup and ship items. get_shipping_orders RPC returns orders with at least one fulfillment = 'ship' item.
• SMS opt-in defaults: communication_contacts.sms_opt_in defaults to FALSE (opt-out by default). email_opt_in defaults to TRUE. Always check sms_opt_in specifically for SMS sends, not email_opt_in.