metatrondelivery/CLAUDE.md

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, in order.

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 (Cart/Checkout Validation Function), never client-only. The storefront widget collects; the Function enforces. This is what makes the app work on non-Plus plans, which is the core competitive moat.
• All date math is timezone/DST-safe (Luxon) and unit-tested BEFORE any UI is wired.
• One Scheduling Service + one capacity pool feeds every surface (web / checkout / POS). Behavior must never diverge between channels.
• Multi-tenant: every DB query scoped by shopDomain.
• Request the MINIMUM OAuth scopes needed. Secrets live in .env, never committed.
• Each phase ships tested, working software; do not skip a phase's acceptance criteria.
• Slot-holds (Redis, TTL) prevent last-slot double-booking — this has a dedicated concurrency test that must pass.

Commands

• shopify app dev — local dev against a dev store
• npm test — Vitest unit tests
• npm run test:e2e — Playwright E2E
• npx prisma migrate dev — DB migrations
• shopify app deploy — deploy extensions / functions

Conventions

• Conventional commits; one feature branch per phase; small PRs per task.
• Polaris components only in the admin UI (Built-for-Shopify requirement).
• Pure functions in app/services/*.server.ts scheduling core — inject data, do no I/O inside the math so it stays unit-testable.
• No inline secrets or API keys anywhere in source.

Current status

Greenfield. Start at Phase 0 (Scaffold & CI) in IMPLEMENTATION_PLAN.md.