Terms you'll see across NUMU codebases, in the order they typically come up.Theme engine#
BYOT (Bring-Your-Own-Theme) — A merchant uploads/selects a theme bundle; the storefront loads it at runtime via module federation. Contrast: built-in.
Built-in theme — A theme that ships with numu-storefront (currently bazar). No bundle URL — the storefront renders sections from its own component registry.
Federation runtime — The mechanism that loads a theme bundle's JS into the storefront page with a shared React identity. Implementation: W3C import map.
Import map — Browser-native module-resolution config. Served at /__numu-runtime/import-map.json.
Bundle — The theme's built artifact (theme.js + theme.css + manifest.json). Lives on R2 in production.
Mount — The theme's exported entry function. Storefront calls mount(ctx) after loading the bundle.
Cleanup — The function mount() returns. Called when the theme is hot-swapped in the customizer's preview mode.
Customizer#
Customizer V3 — The merchant-facing theme editor at numo-merchant-hub/src/features/theme-editor-v3/. Three panels: sections, iframe preview, settings inspector.
Template — A page's section layout (e.g. templates.product). Defines which sections render in what order.
Section — A typed component instance on a template. Has type, settings, optional blocks.
Block — A typed child of a section. Same shape as a section but scoped under one.
Preset — A starter configuration. Theme-level (theme.json presets) or section-level (schemas/sections/<type>.json presets).
Schema — JSON declaration of a section's or block's settings + blocks + presets. Drives the customizer's form.
Input type — A schema setting's renderer (e.g. text, color, product_picker).
visible_if — A conditional that hides a setting based on other settings' values.
Variant (in customizer context) — A theme-level color/typography preset (light/dark/etc.) the merchant switches between.
Storefront#
[domain] — Next.js dynamic segment populated by the middleware via rewrite. Customers never see it in the URL.
Subdomain resolution — Mapping <sub>.numueg.app → store_id via the API.
BYOT fork — The pattern every storefront route follows: BYOT bundle if installed, else built-in template, else built-in component, else generic placeholder.
Built-in fallback — The non-BYOT rendering path. Maintained because every store must work even with no theme.
API proxy — A Next.js API route under app/api/ that forwards to NUMU-api. Handles cookie scope, CSRF, idempotency.
CSRF double-submit — A cookie + matching header pair used to defend against CSRF on cookie-authed writes.
E-commerce#
Variant (in product context) — A SKU-tracked combination of option values (Size=M × Color=Red). Has its own price + inventory + image.
Option axis — A dimension variants vary along (Size, Color, Material). Max 3 per product.
Tender — A method of payment that reduces what the gateway charges. Gift cards are tender; coupons are discounts (different tax treatment).
Snapshot price — cart_item.unit_price at add-time. Does NOT change when the merchant edits the live product price.
Current price — The live product price at request time. Compared to snapshot to flag "price changed" UX.
COD deposit — A pre-payment for cash-on-delivery orders. Reduces RTO (return-to-origin) by giving the customer skin in the game.
OOS override — Per-product flag continue_selling_when_out_of_stock. Only flips is_in_stock; raw inventory counters stay accurate.
Multi-tenancy#
Tenant — A merchant account. Roughly 1:1 with a store, but a user can own multiple tenants (agencies).
Tenant schema — Postgres schema named tenant_<...> containing all customer/product/order tables for one tenant.
search_path — Postgres session variable; the tenant middleware sets it per request so unqualified queries resolve to the right schema.
RLS (row-level security) — Defense-in-depth on cross-tenant tables. Tenant scope enforced via current_setting('app.current_tenant').
current_user.tenant_id — JWT claim that scopes the request.
Auth#
access_token — Short-lived merchant JWT cookie (~15min).
refresh_token — Long-lived merchant cookie (~30 days). Rotated on every refresh (Phase 5.1).
customer_access_token — Customer JWT, scoped to the storefront subdomain.
CSRF — Cross-site request forgery. Mitigated via numu_csrf cookie + x-numu-csrf header double-submit.
Idempotency-Key — Header on mutating requests; backend caches the response under (store, customer, key) for 10min so retries don't double-execute.
Marketplace#
Theme version — An immutable build (version: 1.2.0 etc.). Each numu-theme submit creates a new one.
Developer-install — The dev's ability to install their own pushed theme into their own test store, bypassing admin review.
Admin review — Manual gate before a theme version becomes publicly installable.
Sandbox — Per-developer pre-publish staging area. Bundles here are private; only the developer can install from them.
Infra#
Beat — The Celery beat scheduler. Emits scheduled tasks.
Worker — A Celery worker process consuming tasks from a queue.
DLQ — Dead-letter queue. Tasks that exhaust retries land here for manual inspection.
R2 — Cloudflare's S3-compatible object storage. Hosts theme bundles, backups, uploads.
Webhook — A POST callback. Inbound (gateways → us) AND outbound (us → merchants' integrations).
Storefront SEO + i18n#
MENA-first — Egypt + Arabic + RTL + EGP + ETA e-Invoice. Default locale ar for new stores.
Locale URL prefix — /ar/... is rewritten by middleware to set the numu_locale cookie. Phase 6.
JSON-LD — Structured data blocks emitted SSR for SEO (Product, Organization, BreadcrumbList, …).
ISR — Next.js Incremental Static Regeneration. Per-route revalidate: <seconds> controls cache TTL.
Tag revalidation — Server-side cache invalidation triggered by backend mutations (e.g. publishing a theme version revalidates theme:{storeId}).
Acronyms#
PDP — Product Detail Page
PLP — Product List Page (collection)
GMV — Gross Merchandise Volume
RTO — Return To Origin (COD orders refused on delivery)
HMR — Hot Module Replacement (Vite dev server)
SDK — Software Development Kit (@numueg/theme-sdk)
CLI — Command-Line Interface (numu-theme)
ETA — Egyptian Tax Authority (e-Invoice mandate)
ESM — ECMAScript Modules (the import map runtime)
CSP — Content Security Policy
CORS — Cross-Origin Resource Sharing
HMAC — Hash-based Message Authentication Code (webhook signatures)
OWASP — Open Worldwide Application Security Project (CWE / top-10 reference)
Modified at 2026-09-24 13:03:12
