Pak Jabit: full stack — storefront, Spree customisations, catalogue tooling

A South African men's apparel store on Spree 5.6 + Next.js 15. 160 products
live, three markets, live Malaysian courier rates, customer-owned carts.

What is here:
  storefront/  the Next.js app
  backend/     ONLY the custom Spree code. Spree itself is a prebuilt image
               that mounts no app code, so every file here needs an explicit
               volume entry in docker-compose.yml or it is silently ignored.
  catalogue/   the scripts that loaded and maintain the products
  docs/        manifest, mock registry, napkins

Real .env files are committed deliberately. This lives on the house's private
Gitea, and a clone that runs beats a clone that needs a secrets handover.
LANDMINE.md maps every key, what it opens, and what must be rotated before this
repo goes anywhere less private.

The admin API key used to be a literal in six catalogue scripts. They now read
SPREE_ADMIN_KEY from the environment and refuse to run without it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

backend/config/initializers/customer_preferences.rb

@@ -0,0 +1,38 @@
+# Customer region preference — the anchor for currency, prices and shipping.
+#
+# A cart's currency and market are fixed by Spree at CREATION and cannot be
+# changed afterwards, so the choice has to exist before the cart does. Holding it
+# on the customer is what makes that possible: sign in, and every cart from then
+# on is created in the right market without asking again.
+#
+# Stock Spree's store API neither permits nor serializes public_metadata — a
+# PATCH carrying it answers 200 and saves nothing, the same silent drop that
+# hides a bad address label. This adds both.
+#
+# prepend, not class_eval: permitted_params is defined directly on that
+# controller, so redefining it in place would send `super` past the original and
+# drop every other permitted field.
+#
+# Bind-mounted — the prebuilt ghcr.io/spree/spree image mounts no app code, so
+# this file needs its own entry in docker-compose.yml's web volumes block.
+
+module PakJabit
+  module CustomerPublicMetadata
+    def permitted_params
+      super.merge(params.permit(public_metadata: {}))
+    end
+  end
+end
+
+Rails.application.config.to_prepare do
+  unless Spree::Api::V3::Store::CustomersController.include?(PakJabit::CustomerPublicMetadata)
+    Spree::Api::V3::Store::CustomersController.prepend(PakJabit::CustomerPublicMetadata)
+  end
+
+  Spree::Api::V3::CustomerSerializer.class_eval do
+    typelize public_metadata: 'Record<string, unknown>'
+    attribute :public_metadata do |user|
+      user.public_metadata || {}
+    end
+  end
+end