Storefront

The Storefront module (branded in the admin UI as the "Website Builder") turns a site's existing accounting catalogue into a public e-commerce website — a simple product catalogue, or a full checkout store with Paystack payments. It's used by business owners/admins to configure and publish their site, and by shoppers on the public-facing storefront to browse, sign in, and check out. Every site gets one Storefront configuration record, and the module can serve the store from an instant <label>.lubb.co.za subdomain, a connected custom domain, or both at once.

What you can do

• Turn the public storefront off, set it to catalogue-only (browse, no checkout), or "for sale" (Paystack checkout enabled).
• Curate which products appear on the site: mark items visible, set their product line/category, features, badges and sort order — done directly from the existing Items grid (/g/acc-items), not a separate product list.
• Build and edit standard content pages — About Us, FAQs, Terms & Conditions, Privacy Policy, Return Policy, Reseller Programme — each toggle-able on/off and assignable to a "Company" or "Support" footer column.
• Brand the storefront: logo, favicon, primary colour, support email, WhatsApp number, phone, postal address, and a home-page hero (eyebrow/heading/subtext, with an optional photo background).
• Auto-generate a clean favicon from an uploaded logo, or generate a hero background image, using AI image generation (Gemini).
• Pick a page layout/theme from a set of presets (dark, midnight blue, warm sunset, minimal mono, light-grey, or a Takealot-style marketplace layout).
• Configure flat-rate courier shipping (a base charge covering the first N items, plus a per-extra-item charge).
• Enable Paystack as the checkout payment provider.
• Spin up an instant temporary subdomain (<label>.lubb.co.za) with no DNS work required.
• Connect a real custom domain, with automatic DNS verification and TLS certificate issuance.
• Let shoppers create an account and sign in via a 6-digit email one-time code.
• Let a reseller's storefront sign up new end-users under that reseller.
• Review orders placed through the storefront alongside all other sales orders, filtered/sorted by their "Source" column.
• Turn the in-page AI "Website Builder" chat bubble on or off for the site's builder/preview domain.

Common tasks

1. Publish the catalogue. In Website Builder → Builder page, set Display Mode to "Catalogue only" (browsing) or "For sale" (checkout via Paystack), fill in store name/tagline/branding, and mark the site Published.
2. Curate the product catalogue. Open /g/acc-items, tick items "Visible" and set their product line, features, badge and sort order (a bulk curation pass can also populate these automatically from the site's existing Item Group hierarchy).
3. Build a content page. In the Website Builder, tick a standard page (e.g. "Terms & Conditions") to create it from starter boilerplate, then edit its title/body/footer column and enabled state from the storefront-pages grid.
4. Get a temporary domain live. Submit a label (3–32 lowercase letters/digits/hyphens) via POST /settings/storefront/temp-domain; the platform creates the <label>.lubb.co.za DNS record itself and provisions nginx + TLS, moving the domain from provisioning to live (or failed) with no DNS work needed from the site owner.
5. Connect a custom domain. Point the domain's A record at the platform's public IP, then submit it via POST /settings/storefront/domain; the backend polls until the record resolves here, then provisions nginx + a Let's Encrypt certificate automatically.
6. Turn on checkout and shipping. Enable Paystack, then set a flat shipping base amount, how many items it covers, and the per-extra-item charge — charged automatically on every order once the base is greater than zero.

Data model

• Storefront (storefronts) — one row per site: display mode (catalogue_disabled / catalogue_only / for_sale), published flag, Paystack toggle, branding JSON, template preset, hero copy, flat shipping rates, and both the custom-domain and temporary-domain state machines (status/error/verified/cert-issued timestamps).
• StorefrontPage (storefront_pages) — a built/edited standard content page (title, slug, footer nav group, HTML body, enabled flag, sort order).
• StorefrontSession (storefront_sessions) — an email-OTP sign-in session for a shopper: bcrypt-hashed one-time code, expiry, and a JWT revocation counter, tied to an acc_customer row.
• AccItem (accounting module) — carries the storefront's own catalogue-curation columns directly (visible, product_line, features, feature_values, badge, sort_order); an item's storefront category is not stored but derived live from its Item Group. There is no separate product/SKU model — the storefront catalogue is a live view over accounting's item master.
• AccSalesOrder (accounting module) — orders placed through the storefront are ordinary Sales Orders with source="storefront" plus checkout-specific columns; there is no separate order/order-item model. This is also the join point to Buying/Accounting: a storefront sale is stock-checked and invoiced exactly like any other sales order.

Configuration & integrations

• InterWorx NodeWorx — the DNS control panel used to create the temporary subdomain's CNAME record (via a stored interworx_host3 credential) and looked up when verifying a custom domain's own DNS.
• nginx + Let's Encrypt (certbot) — vhost creation and TLS issuance for both custom and temporary domains are done by a narrow, argument-validated root helper script invoked via sudo -n, never a shell string.
• Paystack — the checkout payment provider when paystack_enabled is on (keys/config are managed separately, in the Paystack settings module).
• Gemini image generation — used to isolate a favicon-ready icon from an uploaded logo and to generate a hero background image; both are preview-only until the admin saves.
• storefront-web — a separate Next.js/Once UI project that renders the actual public site at request time, calling back into this API over a shared-secret header for config, catalogue, checkout, auth and content-page data.
• External storefront integrations (e.g. telecloud.co.za, moviemagic) — authenticate with a personal API key against the read/write lookup endpoints (item/price lookup, customer lookup/creation, Paystack checkout-session creation for a submitted Sales Order).

API reference

Admin settings (/settings/storefront/..., admin/superuser only)

• GET /settings/storefront — read the current storefront configuration.
• PUT /settings/storefront — update display mode, branding, template, hero copy, shipping rates, etc.
• GET /settings/storefront/pages / PUT /settings/storefront/pages — list/toggle the standard content pages.
• POST /settings/storefront/domain — submit a custom domain for DNS verification + provisioning.
• GET /settings/storefront/domain/status — poll custom-domain provisioning status.
• DELETE /settings/storefront/domain — tear down and release the custom domain.
• POST /settings/storefront/temp-domain — claim and provision a <label>.lubb.co.za temporary subdomain.
• GET /settings/storefront/temp-domain/status — poll temporary-domain provisioning status.
• DELETE /settings/storefront/temp-domain — tear down and release the temporary domain.
• POST /settings/storefront/extract-favicon — AI-generate a transparent favicon from an uploaded logo (preview only).
• POST /settings/storefront/generate-hero-image — AI-generate a hero background image from a prompt (preview only).

External storefront lookups (/storefront/..., personal API key)

• GET /storefront/items — look up items by comma-separated SKU.
• GET /storefront/item-prices — look up item prices by SKU (optionally by price list).
• GET /storefront/customers — find a customer by exact email match.
• POST /storefront/customers — create a new customer.
• POST /storefront/orders/{order_id}/pay — turn a submitted Sales Order into a Paystack checkout session.

Public storefront (/public/storefront/..., shared-secret, called by storefront-web)

• GET /public/storefront/resolve — resolve a domain to its site.
• GET /public/storefront/config — fetch a site's public storefront configuration (branding, template, display mode).
• GET /public/storefront/catalogue — fetch the visible product catalogue.
• GET /public/storefront/pages/{slug} — fetch a published content page.
• POST /public/storefront/checkout — place an order and start payment.
• POST /public/storefront/contact — submit the storefront contact form.
• GET /public/storefront/orders/{token} — look up order status by token.
• POST /public/storefront/auth/send-otp / POST /public/storefront/auth/verify-otp — email OTP sign-in flow.
• GET /public/storefront/auth/me — fetch the signed-in shopper's info.
• POST /public/storefront/auth/login / POST /public/storefront/auth/sso-exchange — password login and SSO token exchange.
• GET /public/storefront/reseller/users / POST /public/storefront/reseller/users — list/create a reseller's end-users from their storefront.

Grid CRUD

Content pages are also editable as a standard grid at /g/storefront-pages (edit-only — rows are created by building a page in the Builder, not by the grid). Catalogue curation and order history are not separate grids: they're the standard /g/acc-items and /g/acc-sales-orders grids, filtered/sorted by their storefront-specific columns.