Shopify Management System

Central management for multiple Shopify stores. Spec #1: foundation + read-only settings viewer.

Stack

Next.js (App Router) · TypeScript · Drizzle ORM + Postgres · Better-Auth · @shopify/shopify-api · Vitest + Playwright · Railway.

Local setup

1. cp .env.example .env and fill in values. Generate keys with openssl rand -hex 32.
2. Start a local Postgres (or use a Railway dev database) and set DATABASE_URL.
3. npm install && npm run db:migrate && npm run dev

Deploy (Railway)

• One service for the Next.js app + an attached Postgres plugin.
• Set every variable from .env.example in the Railway service. DATABASE_URL is provided automatically by the Postgres plugin.
• SHOPIFY_APP_URL and BETTER_AUTH_URL must be the Railway public URL.
• The deploy startCommand runs migrations then starts the server (see railway.json).

Scheduled jobs (cron)

The FedEx fuel-surcharge scraper needs to run weekly. Pick one of:

Option A — Railway cron service (recommended): in the Railway project, add a new service from the same repo with:

• Start command: npm run cron:refresh-fuel
• Cron schedule: 0 4 * * 1 (Monday 04:00 UTC = 11:00 ICT)
• Shared env: must see the same DATABASE_URL as the main app (Railway → service → Variables → Reference variable).

The script writes directly to Postgres; no HTTP layer, no auth token needed.

Option B — External HTTPS cron: point cron-job.org / EasyCron / GitHub Actions schedule at:

GET https://<your-railway-url>/api/cron/refresh-fuel
Authorization: Bearer <CRON_SECRET>

Set CRON_SECRET (generate with openssl rand -hex 32) in the Railway service env.

Both paths share the same core logic in features/carrier-rates/fuel-fetcher/apply.ts. The "Refresh from FedEx" button on the Surcharges page also calls the same function, so manual + scheduled refreshes are consistent.

Orders safety-net (in addition to FedEx fuel):

Add another Railway cron service from the same repo:

• Start command: npm run cron:sync-orders
• Cron schedule: 5 * * * * (every hour at minute 5)
• Reference variable: DATABASE_URL from the Postgres service
• Set restartPolicyType to NEVER and leave the healthcheck path empty (it's a one-shot per fire).

This service polls every active store for orders with updated_at >= last_cron_sync_at and reconciles them through the same upsertOrder() path the webhook handler uses. It's an idempotent safety net; webhooks remain the primary real-time channel.

Shopify Dev Dashboard app

• Create one app, unlisted. Set the OAuth redirect URL to <APP_URL>/api/auth/shopify/callback.
• Scopes: read_shipping,read_checkout_branding,read_products.
• Install the app into each store via the in-app "Connect a store" flow.

Testing

• npm run test — unit + integration tests (Vitest).
• npm run test -- --coverage — coverage; the 80% gate applies to the pure-logic core (crypto, registry, rbac, connector). DB-bound modules, route handlers, and UI are integration/E2E surface.
• npm run test:e2e — Playwright E2E. Requires a running app with a provisioned DATABASE_URL.

Branch protection

main is protected by the protect-main ruleset: pull request required, 1 approval, the verify CI check must pass, linear history, no force pushes, no direct deletions. .github/CODEOWNERS routes review of lib/shopify/, lib/crypto/, lib/auth/, and db/schema.ts to @ecommeanblvd.

Contributing

Open an issue first for non-trivial changes. PRs should be focused, include tests, and pass the CI gate. Features live in features/<key>/ folders; they may not touch lib/ or another feature's folder. The lib/shopify connector is read-only by design in spec #1 — do not introduce write paths until spec #2.

Roadmap

This is sub-project #1 of 6. See docs/superpowers/specs/ for the full design and the roadmap (settings write, theme control, feature-module framework, debug/monitoring, customer service).