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/routes.rb

@@ -0,0 +1,49 @@
+
+Rails.application.routes.draw do
+  Spree::Core::Engine.add_routes do
+    # Image Studio - custom admin page for the Photoroom pipeline.
+    # Must live here, not in an initializer: Spree draws engine routes before
+    # config/initializers run, so add_routes from an initializer is a silent
+    # no-op (the sidebar entry registers, the path helper never exists).
+    namespace :admin do
+      get  'image_studio',         to: 'image_studio#show',    as: :image_studio
+      post 'image_studio/preview', to: 'image_studio#preview', as: :preview_image_studio
+      post 'image_studio/apply',   to: 'image_studio#apply',   as: :apply_image_studio
+    end
+
+    # Admin authentication
+    devise_for(
+      Spree.admin_user_class.model_name.singular_route_key,
+      class_name: Spree.admin_user_class.to_s,
+      controllers: {
+        sessions: 'spree/admin/user_sessions',
+        passwords: 'spree/admin/user_passwords'
+      },
+      skip: :registrations,
+      path: :admin_user,
+      router_name: :spree
+    )
+  end
+  # This line mounts Spree's routes at the root of your application.
+  # This means, any requests to URLs such as /products, will go to
+  # Spree::ProductsController.
+  # If you would like to change where this engine is mounted, simply change the
+  # :at option to something different.
+  #
+  # We ask that you don't use the :as option here, as Spree relies on it being
+  # the default of "spree".
+  mount Spree::Core::Engine, at: '/'
+  devise_for :admin_users, class_name: "Spree::AdminUser"
+  devise_for :users, class_name: "Spree::User"
+
+  # Job dashboard (Mission Control) — inspect, retry, and discard Solid Queue
+  # jobs at http://localhost:3000/jobs. Guarded by its own HTTP Basic auth
+  # (see config/application.rb), independent of app sessions.
+  mount MissionControl::Jobs::Engine, at: "/jobs"
+
+  # Reveal health status on /up that returns 200 if the app boots with no exceptions, otherwise 500.
+  # Can be used by load balancers and uptime monitors to verify that the app is live.
+  get "up" => "rails/health#show", as: :rails_health_check
+
+  root to: redirect('/admin')
+end