route-commerce/CLAUDE.md

# CLAUDE.md

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

## Canonical Remote

There is exactly one remote — `origin` — pointing to the self-hosted Gitea repo:

- **URL:** `git@git.crispygoat.com:tyler/route-commerce.git`
- **Default branch:** `main`
- **Deploy:** push to `origin/main` triggers `.gitea/workflows/deploy.yml`

Do **not** add GitHub remotes. There is no `origin` on github.com and no separate "dev" repo. If you see `github.com/dzinesco/*` URLs in `.git/config`, that is stale configuration from a previous fork and should be removed (`git remote remove`).

## 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) · **Postgres** (direct) · **Neon Auth** (Better Auth) · Stripe · Square · Resend (email) · Tailwind CSS v4

> **Direction:** Auth is handled by Neon Auth (Better Auth). The `admin_users` table links to Neon Auth users by email. New DB code should connect to Postgres directly (via `pg` or the chosen driver — see Database section) and **must not** import from `@supabase/*` or call Supabase REST.

---

## Commands

```bash
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 (`supabase/push-migrations.js`) now only uses the direct `pg` path — the Supabase CLI branch is legacy. It reads `DATABASE_URL` from `.env.local` via `dotenv`. `pg` is already in devDependencies.
> If a 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.

E2E tests live in `tests/` and run via Playwright. Specs include `tests/smoke.spec.ts` and `tests/login/login-flow.spec.ts`. **Note: `playwright.config.ts` defaults `baseURL` to production** (`https://route-commerce-platform.vercel.app`); override with `PLAYWRIGHT_URL=http://localhost:3000` for local runs, or pass `--config` with a local config.

---

## Architecture

### Authentication & Authorization

**Neon Auth (Better Auth)** is the active auth system. Config lives in `src/lib/auth.ts`, with the route handler at `src/app/api/auth/[...nextauth]/route.ts`. Neon Auth manages users in the `neon_auth.user` table; our `admin_users` table links to Neon Auth users by email.

**Auth flow:**
1. User signs in via `/api/auth/sign-in` → Neon Auth validates credentials → session cookie set
2. `getAdminUser()` in `src/lib/admin-permissions.ts` reads the Neon Auth session and looks up `admin_users` by email
3. Middleware (`src/middleware.ts`) guards `/admin/*` routes at the edge level

**Key files:**
- `src/lib/auth.ts` — Neon Auth configuration (getSession, signIn, signOut, resetPassword, requestPasswordReset)
- `src/auth.config.ts` — Edge-safe config (baseUrl, cookieSecret)
- `src/middleware.ts` — Edge-level route protection
- `src/app/api/auth/sign-in/route.ts` — Email/password sign-in API
- `src/app/api/auth/forgot-password/route.ts` — Password reset request API
- `src/app/api/auth/reset-password/route.ts` — Password reset confirmation API
- `src/actions/auth-actions.ts` — Server actions (signOutAction)
- `src/actions/admin/password.ts` — Admin password update (setUserPassword)

**Environment variables:**
- `NEON_AUTH_BASE_URL` — from `neonctl neon-auth status`
- `NEON_AUTH_COOKIE_SECRET` — min 32-char secret: `openssl rand -base64 32`
- `NEXT_PUBLIC_SITE_URL` — site URL for redirects and Origin header

**Single source of truth for the current admin user:** `getAdminUser()` in `src/lib/admin-permissions.ts`. It reads the Neon Auth session via `getSession()` from `@/lib/auth`, then looks up `admin_users` by email. **Never import `admin-permissions.ts` into Client Components** — use server actions instead.

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

#### Auth API routes

| Route | Method | Purpose |
|-------|--------|---------|
| `/api/auth/sign-in` | POST | Email/password sign-in |
| `/api/auth/forgot-password` | POST | Request password reset email |
| `/api/auth/reset-password` | POST | Set new password (after reset link clicked) |
| `/api/auth/[...nextauth]` | GET/POST | Neon Auth handler (sign-out, OAuth callbacks, etc.) |

### 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 Postgres RPCs via the `pg` driver
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.

### Database (Postgres, direct)

The app connects to **Postgres directly** — no Supabase platform, JS client, or REST gateway. Server actions use the `pg` driver (or whatever the chosen connection layer is) to call `SECURITY DEFINER` PL/pgSQL functions. Storage of files (product images, etc.) is moving to an S3-compatible object store; until that's wired up, image references can stay as URLs.

#### Connection

- `DATABASE_URL` in `.env.local` (and hosting dashboard) is the only required DB env var.
- A single shared `pg` `Pool` is exported from `src/lib/db.ts` (TBD — to be created/confirmed during the migration). Server actions and API routes import it and call `pool.query(...)` against RPC names.
- No `NEXT_PUBLIC_SUPABASE_URL` / `SUPABASE_SERVICE_ROLE_KEY` / `@supabase/*` imports — these are being purged from the codebase.

#### First production deploy / new prod DB bootstrap (critical for admin access)

The `admin_users` + `admin_user_brands` tables (and the rest of the schema) come **only** from `db/migrations/0001_init.sql`.

If the prod `DATABASE_URL` has never had the migrations applied, `getAdminUser()` will fail with "relation \"admin_users\" does not exist", the layout will show "Access Denied", and even a signed-in Neon Auth user will be blocked.

**Correct bootstrap sequence (do this from a machine with the full source tree before the first push that exercises /admin):**

1. Ensure the Gitea secret `DATABASE_URL` points at the real prod Neon Postgres (the one with `neon_auth.user` already present).
2. Sign in once at the live prod URL (`/login`) with the email you want as the first `platform_admin`. This creates the row in `neon_auth.user`.
3. From your laptop (or any box with the checkout):

   ```bash
   # Paste the real prod connection string (get it from Gitea secrets or the target's .env.production)
   DATABASE_URL="postgresql://...prod-full-string..." node scripts/migrate.js

   # Then provision (the script will link to the first brand it finds)
   DATABASE_URL="postgresql://...prod-full-string..." \
     npx tsx scripts/provision-admin.ts you@real.com platform_admin
   ```

4. Push to main. The deploy workflow now has a hard gate (see `.gitea/workflows/deploy.yml` "Run migrations" + verification query for `admin_users`) and ships the migrate runner + SQL files, so future deploys and server-side recovery are protected.

See the full root-cause + plan: `docs/superpowers/plans/2026-06-prod-db-schema-migration-reliability.md`

The old `|| echo` masking around `npm run migrate:one` has been removed; a missing critical table will now fail the CI job with a clear message.

#### 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 any future RLS. 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:

```tsx
// 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:
```typescript
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:
   ```sql
   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):
   ```sql
   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`. (The "no RLS" framing carries over from the Supabase era; on raw Postgres this just means no row-level policies — scoping is still enforced by RPC + app layer.)

`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`.

**Scheduled automations** (declared in `vercel.json`):
- `POST /api/email-automation/abandoned-cart` — every 6h, fires abandoned-cart sequence emails
- `POST /api/email-automation/welcome-sequence` — every 6h, fires welcome onboarding sequence
- `POST /api/cron/send-scheduled` — daily 09:00, sends scheduled campaigns
- `POST /api/wholesale/notifications/{send,dispatch,pickup-reminder}` — wholesale lifecycle
- `POST /api/square/process-queue` — every 2 min, drains Square sync queue

These endpoints are also reachable via curl for manual triggering; the email-automation routes accept `Authorization: Bearer $CRON_SECRET`.

### 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 access goes through a shared `pg` `Pool` (see Database section). Server actions call SECURITY DEFINER RPCs via `pool.query('SELECT * FROM fn_name($1, $2)', [...])`. Do not introduce `@supabase/*` imports or REST fetch to `*/rest/v1/`.
- `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 |
|---|---|
| Neon Auth configuration | `src/lib/auth.ts`, `src/auth.config.ts` |
| Auth API routes | `src/app/api/auth/sign-in/route.ts`, `src/app/api/auth/forgot-password/route.ts`, `src/app/api/auth/reset-password/route.ts`, `src/app/api/auth/[...nextauth]/route.ts` |
| 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; also grouped into `src/actions/{admin,ai,billing,communications,harvest-reach,integrations,orders,products,settings,shipping,stops,water-log,platform,route-trace,time-tracking,email-automation}/`) |
| Admin pages | `src/app/admin/[module]/page.tsx` |
| Admin client components | `src/components/admin/*.tsx` |
| Migrations | `db/migrations/` |
| Postgres pool / driver | `src/lib/db.ts` (TBD) |
| 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 no row-level policies. 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`.
- **Neon Auth session cookie**: The session cookie is managed by Neon Auth. Do not manually set or clear it — use `signOut()` from `@/lib/auth` instead.
- **Password reset**: The forgot-password API returns success even if the email doesn't exist (to prevent email enumeration). Check server logs to verify reset emails were sent.