metatrondelivery/IMPLEMENTATION_PLAN.md

Implementation Plan — Delivery Date & Time Shopify App

Audience: Claude Code (or any engineer) building this app from an empty repo. Read PRODUCT_STRATEGY.md first for the why and the feature rationale. This document is the how: stack, architecture, schema, file layout, and a phased, task-by-task build order with acceptance criteria. Target: All Shopify plans (Basic → Plus). Built-for-Shopify quality bar.

---

0. Ground rules for the build

• Stack is fixed (see §1). Do not swap frameworks. If a library choice is ambiguous, prefer the one Shopify's own app template uses.
• Build in phases (§6). Each phase ends with working, testable software and its own acceptance criteria. Do not start a phase before the previous one's acceptance criteria pass.
• Every phase includes tests. No phase is "done" with failing or absent tests for the logic it introduced.
• Scheduling correctness is sacred. Timezones, DST, capacity math, and slot-holds are where this app lives or dies. Write unit tests for every date/capacity function before wiring UI.
• Never trust the client. The storefront widget is a convenience; the Validation Function is the enforcement. Any rule that matters must be enforced server-side.
• Keep secrets out of git. Use .env (gitignored) + shopify.app.toml. Never commit API keys.
• Conventional commits, small PRs per task, feature-branch per phase.

---

1. Tech stack

Layer	Choice	Notes
App framework	Remix via @shopify/shopify-app-template-remix	Shopify's official embedded-app template
Admin UI	Polaris (@shopify/polaris) + App Bridge (@shopify/app-bridge-react)	BfS requirement
App DB	PostgreSQL (prod) / SQLite (dev) via Prisma	Transactional scheduling data
Cache / queue / holds	Redis + BullMQ	Slot-hold TTLs, notification jobs, capacity recompute
Shopify data	GraphQL Admin API (latest stable version)	via @shopify/shopify-api in the template
Storefront widget	Theme App Extension (App Embed + blocks), Preact or vanilla TS	Small bundle, no CLS; all plans
Checkout	Checkout UI Extensions (React)	Native picker on Plus; Thank-you + Order-status blocks on all plans
Enforcement / rules	Shopify Functions (Rust preferred, JS acceptable)	Cart/Checkout Validation, Delivery Customization, Payment Customization, Cart Transform
POS	POS UI Extension	Same capacity pool
Auth/session	Template's Prisma session storage
Billing	Shopify Billing API (managed pricing or GraphQL appSubscriptionCreate)	Tiers from strategy §6
Testing	Vitest (unit), Playwright (E2E admin), Function unit tests via function-runner
Language	TypeScript everywhere except Rust Functions	strict mode on

---

2. High-level architecture

                        ┌─────────────────────────────────────────────┐
                        │              Merchant (Admin)               │
                        │   Remix embedded app · Polaris · App Bridge  │
                        │  locations · slots · rules · dashboard · billing
                        └───────────────┬─────────────────────────────┘
                                        │ GraphQL Admin API + app DB
                        ┌───────────────▼─────────────────────────────┐
                        │            App Backend (Remix)               │
   Redis/BullMQ  ◄──────┤  Scheduling service (single source of truth) │──────►  Postgres (Prisma)
   holds·jobs           │  availability · capacity · holds · bookings  │        locations, slots,
                        │  REST/GraphQL app API · webhooks · billing   │        bookings, resources...
                        └───┬──────────────┬───────────────┬───────────┘
                            │              │               │ metafields / metaobjects write-back
              storefront    │   checkout   │     POS       │
        ┌───────────────────▼──┐  ┌────────▼─────────┐  ┌──▼────────────────┐
        │ Theme App Extension  │  │ Checkout UI Ext  │  │ POS UI Extension  │
        │ date/time picker     │  │ (Plus native /   │  │ staff scheduling  │
        │ → cart attributes    │  │ TY+status blocks)│  │ same pool         │
        └──────────┬───────────┘  └────────┬─────────┘  └───────────────────┘
                   │ cart attributes        │ reads booking
        ┌──────────▼────────────────────────▼─────────────────────────────┐
        │                     Shopify Functions                            │
        │  Cart/Checkout Validation  → block completion if slot invalid    │
        │  Delivery Customization     → rename/reorder/hide delivery opts   │
        │  Payment Customization      → hide payment methods by method      │
        │  Cart Transform             → line adjustments (deposits, fees)   │
        └──────────────────────────────────────────────────────────────────┘

The single rule: every surface (widget, checkout, POS) calls the same Scheduling Service for availability, and the same capacity pool for holds/bookings. Behavior never diverges between channels. Functions enforce; UIs merely collect.

Data flow for a booking (non-Plus):

1. Widget calls Scheduling Service → gets available dates/slots for method+location+cart.
2. Shopper picks slot → widget writes selection to cart attributes and requests a SlotHold (TTL).
3. At checkout, Validation Function reads cart attributes, re-checks the hold/availability via a metafield-backed snapshot → blocks completion if invalid.
4. On orders/create webhook → convert hold to Booking, write date/time/location back to the order via order metafield, consume capacity/resources, release the hold.

---

3. Repository layout

delivery-datetime-app/
├── CLAUDE.md                     # root agent instructions (see §7)
├── README.md
├── PRODUCT_STRATEGY.md
├── IMPLEMENTATION_PLAN.md        # this file
├── shopify.app.toml              # app config, scopes, webhooks
├── .env.example
├── package.json
├── prisma/
│   ├── schema.prisma             # §4
│   └── migrations/
├── app/                          # Remix app
│   ├── routes/
│   │   ├── app._index.tsx        # dashboard home
│   │   ├── app.locations.*.tsx   # location CRUD
│   │   ├── app.slots.*.tsx       # slot templates / overrides
│   │   ├── app.rules.*.tsx       # product/collection rules
│   │   ├── app.blackouts.*.tsx
│   │   ├── app.rates.*.tsx
│   │   ├── app.dashboard.tsx     # ops/dispatch dashboard
│   │   ├── app.settings.*.tsx    # widget/i18n/templates
│   │   ├── app.billing.tsx
│   │   ├── api.availability.tsx  # PUBLIC app-proxy endpoint for widget
│   │   ├── api.hold.tsx          # create/release slot holds
│   │   └── webhooks.*.tsx        # orders/create, orders/updated, app/uninstalled, GDPR x3
│   ├── services/
│   │   ├── scheduling.server.ts  # availability engine (PURE, unit-tested)
│   │   ├── capacity.server.ts    # resource capacity math
│   │   ├── holds.server.ts       # Redis-backed holds w/ TTL
│   │   ├── booking.server.ts     # create/reschedule/cancel bookings
│   │   ├── zones.server.ts       # geocode + radius/distance eligibility
│   │   ├── rates.server.ts
│   │   ├── notifications.server.ts
│   │   ├── templates.server.ts   # vertical presets
│   │   └── shopify-sync.server.ts# metafield/metaobject write-back
│   ├── lib/
│   │   ├── time.ts               # tz/DST-safe date math (Luxon) — PURE, unit-tested
│   │   └── db.server.ts          # Prisma client
│   └── shopify.server.ts         # template auth/init
├── extensions/
│   ├── datetime-widget/          # Theme App Extension (storefront)
│   ├── checkout-datetime/        # Checkout UI Extension (Plus native + TY/status)
│   ├── pos-datetime/             # POS UI Extension
│   ├── validation-slot/          # Function: cart/checkout validation (Rust)
│   ├── delivery-customization/   # Function: delivery options (Rust)
│   ├── payment-customization/    # Function: payment methods (Rust)
│   └── cart-transform/           # Function: line adjustments (Rust)
├── jobs/
│   └── worker.ts                 # BullMQ worker: hold-expiry, notifications, capacity recompute
└── tests/
    ├── unit/                     # scheduling, capacity, time, zones
    └── e2e/                      # Playwright admin flows

---

4. Prisma schema (starting point)

Build incrementally per phase, but design toward this. shopDomain scopes every row (multi-tenant).

model Shop {
  id            String   @id @default(cuid())
  shopDomain    String   @unique
  plan          String   // basic|shopify|advanced|plus
  tier          String   @default("free") // free|starter|growth|pro
  timezone      String   @default("UTC")
  settings      Json     // widget copy, i18n, feature flags
  locations     Location[]
  createdAt     DateTime @default(now())
}

model Location {
  id            String   @id @default(cuid())
  shopDomain    String
  name          String
  address       String
  lat           Float?
  lng           Float?
  timezone      String
  active        Boolean  @default(true)
  slotTemplates SlotTemplate[]
  overrides     SlotOverride[]
  blackouts     BlackoutDate[]
  zones         Zone[]
  resources     CapacityResource[]
  @@index([shopDomain])
}

enum Method { SHIPPING LOCAL_DELIVERY PICKUP }

model SlotTemplate {
  id          String   @id @default(cuid())
  shopDomain  String
  locationId  String
  location    Location @relation(fields: [locationId], references: [id], onDelete: Cascade)
  method      Method
  weekday     Int      // 0-6
  startMin    Int      // minutes from midnight, local
  endMin      Int
  capacity    Int      // default order capacity if no resources
  cutoffMin   Int?     // cutoff before slot (minutes)
  leadTimeMin Int      @default(0)
  @@index([shopDomain, locationId, method, weekday])
}

model SlotOverride {
  id          String   @id @default(cuid())
  shopDomain  String
  locationId  String
  location    Location @relation(fields: [locationId], references: [id], onDelete: Cascade)
  date        DateTime // date-only, location-local
  method      Method
  closed      Boolean  @default(false)
  startMin    Int?
  endMin      Int?
  capacity    Int?
  @@index([shopDomain, locationId, date])
}

model BlackoutDate {
  id          String   @id @default(cuid())
  shopDomain  String
  locationId  String?  // null = all locations
  location    Location? @relation(fields: [locationId], references: [id], onDelete: Cascade)
  method      Method?  // null = all methods
  date        DateTime
  reason      String?
  source      String   @default("manual") // manual|holiday-import
  @@index([shopDomain, date])
}

model CapacityResource {
  id          String   @id @default(cuid())
  shopDomain  String
  locationId  String
  location    Location @relation(fields: [locationId], references: [id], onDelete: Cascade)
  name        String   // "oven", "driver", "picker"
  perSlotMax  Int
  @@index([shopDomain, locationId])
}

model Zone {
  id          String   @id @default(cuid())
  shopDomain  String
  locationId  String
  location    Location @relation(fields: [locationId], references: [id], onDelete: Cascade)
  type        String   // postal|radius|distance
  postalCodes String[]
  radiusKm    Float?
  minOrders   Int?     // delivery-density threshold
  @@index([shopDomain, locationId])
}

model ProductRule {
  id            String   @id @default(cuid())
  shopDomain    String
  scopeType     String   // product|collection|vendor|type|tag
  scopeValue    String
  allowedMethods Method[]
  leadTimeMin   Int?
  allowedLocationIds String[]
  blockSlotRule Json?    // cart-content constraints
  @@index([shopDomain, scopeType])
}

model Rate {
  id          String   @id @default(cuid())
  shopDomain  String
  method      Method
  zoneId      String?
  priceCents  Int
  keyedBy     String   // zone|distance|weight|value
  rules       Json
  @@index([shopDomain, method])
}

model SlotHold {
  id          String   @id @default(cuid())
  shopDomain  String
  cartToken   String
  locationId  String
  method      Method
  slotStart   DateTime
  resources   Json     // {resourceId: qty}
  expiresAt   DateTime
  @@index([shopDomain, slotStart])
  @@index([expiresAt])
}

model Booking {
  id            String   @id @default(cuid())
  shopDomain    String
  orderId       String   @unique
  orderName     String?
  locationId    String
  method        Method
  slotStart     DateTime
  slotEnd       DateTime
  status        String   @default("confirmed") // confirmed|rescheduled|cancelled|fulfilled|no_show
  resources     Json
  customerEmail String?
  customerPhone String?
  address       Json?
  reschedules   Reschedule[]
  createdAt     DateTime @default(now())
  @@index([shopDomain, slotStart])
  @@index([shopDomain, status])
}

model Reschedule {
  id          String   @id @default(cuid())
  bookingId   String
  booking     Booking  @relation(fields: [bookingId], references: [id], onDelete: Cascade)
  fromSlot    DateTime
  toSlot      DateTime
  reason      String?
  createdAt   DateTime @default(now())
}

model Waitlist {
  id          String   @id @default(cuid())
  shopDomain  String
  locationId  String
  method      Method
  slotStart   DateTime
  customerEmail String
  status      String   @default("waiting") // waiting|promoted|expired
  createdAt   DateTime @default(now())
  @@index([shopDomain, slotStart])
}

model Notification {
  id          String   @id @default(cuid())
  shopDomain  String
  bookingId   String?
  channel     String   // email|sms
  type        String   // reminder|eta|reschedule|waitlist
  sendAt      DateTime
  status      String   @default("pending")
  payload     Json
  @@index([shopDomain, sendAt, status])
}

(Deposit and RecurringBooking models are added in v2 — see strategy §3.3.)

---

5. Shopify configuration

5.1 Scopes (shopify.app.toml)

Request the minimum that covers the feature set (mirror DS but no more): read_products, read_customers, read_orders / write_orders (draft orders + order metafields), read_locations, write_metaobjects/read_metaobjects, write_cart_transforms, write_delivery_customizations, write_payment_customizations, plus the Functions' own access. Add read_markets/read_locales for i18n. Do not request write_customers or discounts unless a feature actually needs it — fewer scopes = faster review + more merchant trust.

5.2 Webhooks (mandatory + functional)

• app/uninstalled → wipe shop data (or soft-delete + purge job)
• orders/create → create Booking, consume capacity, write-back metafield, release hold
• orders/updated / orders/cancelled → sync booking status, free capacity
• customers/data_request, customers/redact, shop/redact → GDPR, required for BfS

5.3 App Proxy

Expose /apps/scheduling/availability and /apps/scheduling/hold via app proxy so the storefront widget can call the backend from the theme without CORS pain.

5.4 Functions — behavior contracts

• validation-slot (Cart & Checkout Validation): reject checkout if cart has schedulable items but no valid slot attribute, or if the slot's capacity snapshot shows it's full/blacked-out/past cutoff. This is the all-plan enforcement.
• delivery-customization: rename/reorder/hide delivery options to match chosen method; surface zone rate.
• payment-customization: hide payment methods incompatible with the method (e.g. no COD on shipping).
• cart-transform: add a deposit line or delivery fee where applicable (v2 for deposits).

---

6. Phased build order

Each phase: branch phase-N-..., ship working software, meet acceptance criteria, then merge.

Phase 0 — Scaffold & CI

• Init from shopify-app-template-remix; TypeScript strict; ESLint/Prettier.
• Prisma + Postgres/SQLite; Redis + BullMQ skeleton; Vitest + Playwright configured.
• shopify.app.toml with scopes, app proxy, GDPR + app/uninstalled webhooks wired (handlers can be stubs).
• Dev store install works; embedded app loads with a Polaris shell.
• Accept: shopify app dev runs, app installs, blank dashboard renders, CI runs lint+tests green.

Phase 1 — Core data model & admin CRUD

• Implement Shop, Location, SlotTemplate, SlotOverride, BlackoutDate, Method in Prisma.
• Polaris CRUD screens: create/edit locations (address + geocode via zones.server stub), weekly slot template editor, blackout calendar.
• Vertical templates service: "Bakery/Florist/Grocer" one-click preset seeds locations+slots+copy.
• Accept: merchant can fully configure a single location's weekly slots + blackouts in the admin; data persists; a template seeds a working config in one click. Unit tests for template seeding.

Phase 2 — Scheduling engine (the heart)

• lib/time.ts: Luxon-based, tz/DST-safe helpers. 100% unit-tested (DST spring-forward/fall-back cases included).
• services/scheduling.server.ts: pure function getAvailability(shop, method, location, dateRange, cart) → applies templates, overrides, blackouts, cutoffs, lead-times, product rules. No DB or Shopify calls inside the pure core (inject data).
• services/capacity.server.ts: compute remaining capacity per slot from Bookings + Holds + resources.
• Accept: given a fixture config, availability output is correct across timezones, DST boundaries, cutoffs, and lead-times. Full unit-test suite green. No UI yet.

Phase 3 — Storefront widget + cart attributes

• Theme App Extension (App Embed + cart block), Preact/vanilla TS, no CLS, accessible, i18n-ready.
• Calls app-proxy /availability; renders method → date → slot; hides unavailable; writes selection to cart attributes.
• Method-specific, unambiguous copy (pickup vs delivery — fix DS's complaint).
• Accept: on a dev store theme, shopper picks method/date/slot; unavailable dates hidden; selection saved to cart attributes and visible in cart. Lighthouse: no significant CLS, fast widget load.

Phase 4 — Enforcement (Functions) + slot-holds

• holds.server.ts + Redis: create hold on slot select (TTL, e.g. 10 min); BullMQ job expires/releases holds.
• validation-slot Function: block checkout when slot missing/invalid/full. Deploy and test on a non-Plus dev store to prove all-plan enforcement.
• delivery-customization + payment-customization Functions.
• orders/create webhook → Booking creation, capacity consumption, order metafield write-back, hold release.
• Accept: on a non-Plus store, checkout is blocked without a valid slot; two concurrent carts cannot book the last unit of capacity (hold race test); completed order shows the slot on the order record. Function unit tests via function-runner.

Phase 5 — Multi-location, zones, rates, auto-assignment

• Zone model + zones.server: geocode address, radius/driving-distance eligibility, delivery-density thresholds, nearest-location auto-assign, inventory-based exclusion (query product stock per location).
• Rate model → surfaced through delivery-customization Function.
• Google Maps display of pickup locations in the widget.
• Accept: delivery eligibility correctly gates by zone/distance; order auto-assigns to nearest valid, in-stock location; rates vary by zone/method at checkout.

Phase 6 — Ops/dispatch dashboard

• app.dashboard.tsx: bookings by day/slot/location, capacity-utilization heatmap, revenue by method, upcoming-fulfillment list; filters + CSV export.
• Booking status transitions (confirmed→fulfilled/no_show).
• Accept: merchant sees an accurate, filterable schedule of all bookings and can export a day's dispatch list.

Phase 7 — POS + Checkout UI extensions

• POS UI Extension: staff run the same availability/hold/booking flow against the same pool.
• Checkout UI Extension: native picker on Plus; Thank-you + Order-status confirmation blocks on all plans.
• Accept: a POS order consumes the same capacity as online (no double-book); Plus checkout shows native picker; all plans show confirmed slot on thank-you/order-status.

Phase 8 — Billing & Built-for-Shopify hardening

• Billing API: Free/Starter/Growth/Pro tiers (strategy §6) with feature gating.
• Performance budget, accessibility pass, empty/loading/error states, onboarding checklist, help docs.
• Verify all GDPR webhooks; data purge on uninstall.
• Accept: tier upgrade/downgrade works and gates features; app passes an internal BfS checklist review; GDPR flows verified.

Phase 9 — Fast-follow (v1.x) — separate milestones

Waitlists, self-service reschedule portal (order-status + magic link), email→SMS reminders (BullMQ + Notification model), printable run sheets/picking lists, holiday auto-import, headless/Storefront-API support.

Phase 10 — v2

Predictive prep-time (AI on order history), deposits (Cart Transform + draft orders), recurring/subscription slots, merchant REST/GraphQL API + webhooks, group/multi-drop catering orders.

---

7. CLAUDE.md (place at repo root)

Create this so future Claude Code sessions have standing context:

# Delivery Date & Time — Shopify App

Scheduling app for Shipping / Local Delivery / Store Pickup with date-time slots,
capacity intelligence, and all-plan checkout enforcement. See PRODUCT_STRATEGY.md
(why) and IMPLEMENTATION_PLAN.md (how). Build in the phases defined there.

## Stack
Remix + Polaris + App Bridge · Prisma/Postgres · Redis/BullMQ · GraphQL Admin API ·
Theme App Extension (Preact) · Checkout UI Extensions (React) · Shopify Functions (Rust) ·
POS UI Extension · TypeScript strict · Vitest + Playwright.

## Non-negotiables
- Enforcement is server-side (Validation Function), never client-only.
- All date math is timezone/DST-safe (Luxon) and unit-tested before UI.
- One Scheduling Service + one capacity pool feeds every surface (web/checkout/POS).
- Multi-tenant: every query scoped by shopDomain.
- Minimal OAuth scopes. Secrets in .env, never committed.
- Each phase ships tested, working software; don't skip acceptance criteria.

## Commands
- `shopify app dev` — local dev against a dev store
- `npm test` — unit tests · `npm run test:e2e` — Playwright
- `npx prisma migrate dev` — DB migrations
- `shopify app deploy` — deploy extensions/functions

## Conventions
Conventional commits · feature branch per phase · Polaris components only in admin ·
no inline secrets · pure functions in services/*.server.ts core (inject data, no I/O in the math).

---

8. Testing & acceptance strategy

• Unit (Vitest): time/DST helpers, availability engine, capacity math, zone eligibility, template seeding, rate resolution. These are pure — test exhaustively with fixtures.
• Function tests: function-runner with recorded input JSON for validation/delivery/payment functions, including the "no slot," "slot now full," and "past cutoff" rejection cases.
• Integration: webhook → booking creation → metafield write-back; hold create → expire → release.
• E2E (Playwright): admin CRUD flows; storefront pick-a-slot happy path on a dev theme.
• Concurrency test (critical): two simultaneous checkouts for the last capacity unit — exactly one succeeds. This is the slot-hold moat; it must have a dedicated test.
• Manual matrix: verify enforcement on a non-Plus dev store (the whole point) and native checkout on a Plus dev store.

---

9. Risks & watch-items

• Checkout extensibility limits (non-Plus): the picker cannot live in the core checkout steps on non-Plus — that is expected. Enforcement comes from the Validation Function + cart-attribute selection in the theme, not from a checkout-step UI. Do not architect around putting the picker inside non-Plus checkout.
• Aug 26 2026 script deprecation: non-Plus stores are fully on the extensibility model; there is no checkout.liquid / Additional Scripts fallback. Build to extensions + Functions from day one (we already do).
• Function latency budget: Validation Functions run on the hot checkout path — keep them fast and side-effect-free; the capacity snapshot they read must be cheap (denormalize into a metafield the Function can read directly).
• Geocoding cost/quota: cache geocode results per address; don't call the maps API on every availability request.
• Timezone bugs are the #1 source of scheduling failures — treat lib/time.ts as safety-critical.
• BfS review: minimal scopes, GDPR webhooks, performance, and accessibility are gating. Bake them in, don't retrofit.