Documentation

Getting started

What you get: What an install of themerchantengine puts on a box, what a store owner has on day one, and what is not in the first release.
Requirements: Everything to have ready before running the installer on a server. The box, the DNS records, the S3 bucket, the Resend domain, the Turnstile widget, the license file, and the optional search-engine credentials, each with the console page where it is created.
Get a license: What the license file is, why a production install needs one, how to get a free evaluation license or a commercial one, how domain binding works, and what happens when a license expires.
Install on a server: Install the engine on a prepared Linux box with the setup CLI. The two-box and one-box runs, every prompt in order with its default and its live check, what the installer writes, what it does, and how a run resumes.
Install locally: Run the whole engine on a laptop with Docker Desktop. Linux and macOS through setup.sh, Windows through setup.ps1, the local ports, the demo catalogue, where mail goes, how long it takes, and how to tear it down.
The first hour: What to do once the installer printed its closing line. Sign in as the owner, walk the settings screens, create the first category and product in two locales, place a cash-on-delivery test order, read the order email, download the invoice.
Go-live checklist: The checks to run on a freshly installed store before customers arrive, each with the command that proves it. DNS and TLS, the backup timer, Search Console and Bing, the IndexNow key, llms.txt, Turnstile, the owner password, the demo catalogue, the license binding.
Non-interactive runs and CI: Run the installer without a terminal from a JSON answers document, preview a run with —dry-run, start over with —reset, understand what the state file holds and never holds, and see the CI install smoke the engine runs on itself as a worked example.
Troubleshooting: Every line the wrapper, the stepper and the installer print when they stop, with the cause and the fix, plus the day-two failures an operator meets on a running store.

Operate

Topology: What an installed store looks like on the box. The containers per profile, the volumes, the rendered stack directory, the environment files, the timers, and the compose command every operation on this track starts from.
Update the store: An update is a re-run of the installer on a newer checkout. What it rebuilds, what it keeps, the order for two boxes, and the two things to do by hand only when you must, editing nginx and pushing the schema.
Rollback: Roll the application containers back to a previous release from a git ref, what the script leaves untouched, and what to do first when the release you are leaving changed the schema.
Backups and restore: The nightly database dump the installer scheduled, how to take one by hand before an update, how to restore into the running Postgres, what the dump does and does not contain, and why a copy has to leave the box.
TLS and renewal: How the certificates are issued and renewed, the renewal timer and what it checks beyond certbot, the self-hosted expiry alert and why it exists, how to test both, and what to look at when an alert arrives.
Timers, logs and disk: The three systemd timers an installed store runs, how to read the logs of each container and follow one request by its id, how to reclaim disk without deleting a volume, and the one-liners that answer the usual questions.
License renewal: What the admin shows as a license approaches and passes its expiry, how to install a renewed or re-issued file on a running store without a restart, and what a lapsed license does and does not change.
Store settings, secrets and integrations: Which values belong to the store and are edited in the admin’s settings screens, which belong to the box and change by re-running the installer, how to rotate each secret and third-party key, and how the search-engine submission credentials are rotated.

Customize

Repository layout: The Nx workspace: every app and library with its port, its purpose and how it builds, the path a request travels from the edge nginx to Prisma and back, and which app imports which library.
Development environment: Running the engine from a checkout: the docker services, the database commands, the seeds and the three store fixtures, the dev servers, the test stack, the three e2e harnesses and the traps each one guards against.
Conventions: The rules every change to the engine follows, each with the file that enforces it: envelopes, translatable text, permissions and ownership, idempotency keys, soft delete, atomic decrements, sort allowlists, validation, raw SQL, browser caching, session bootstrap and request correlation.
Add an endpoint: Add a route to an existing API module: the class-validator DTO, the controller method with its guard and OpenAPI summary, the service method, the shared admin route constant, and the unit and Supertest specs, with the carriers module as the worked example.
Add a module: Create a NestJS module under apps/api/src/modules, register it, keep it isolated behind injected services, give it a permission module in both catalogue copies, and plant the permission rows with the seed, with the carriers and countries modules as the worked examples.
Add a settings key: Register a store setting: the StoreSetting row it lives in, the key registry and default, the PATCH field, the Redis cache and the event that drops it, the public store config it may join, the admin editor that writes it and the storefront read.
Add a payment provider: What the engine captures today (cash on delivery, manual transfer, gift cards), what the provider allow-list promises and does not deliver, and the steps to wire the first card provider into the payments, orders, webhooks and checkout code.
Add a notification template: Add a transactional email flow: the flow code, the per-locale subject and body defaults, the file fallback, the event-to-template dispatch row, the seed, the token allow-list the editor enforces, and the preview and test-send endpoints.
Add a webhook event: Add an outbound webhook event type: the catalogue, the internal event a module emits, the listener bridge, the BullMQ dispatcher with its globally unique eventId, the signed delivery and its retry log, the admin subscription screen, and the URL validations.
Add a permission: Add a module:action key to the RBAC catalogue: the shared permissions library, the seed’s copy, the route that enforces it, the guard, the seeded role rows, the admin roles grid that reads the same constant, and the two drift specs.
Add a screen: Add a list or detail screen to the Angular admin: the shared route constant, the Zod-parsed service, the page component, the guarded route, the nav entry, the component spec and the Playwright journey against the real API.
Add a form field: Add a control to an existing admin form: the Zod schema, the Reactive Forms control, the error isolated on the invalid field, the submit button gated on dirty state, the Translatable editor, and the validator tests.
Add a settings tab: Add a screen under Settings in the Angular admin: the card on the settings home, the child route, the per-screen form over the settings service and its Zod schema, and the e2e journey that saves and restores.
Add a dialog: Open a modal in the Angular admin on the CDK dialog primitive: pass data in, get a typed result out, keep the focus trap and Escape behaviour CDK provides, and style it inside the brand rules.
Change brand tokens: Which colours in the Angular admin come from the store’s settings at runtime and which are the admin’s own build-time design tokens, how dark and light mode resolve, and the contrast gate that measures every pair.
Add a sortable column: Sort an admin list by a new field: the sort state in the URL query, the query schema the service parses, the NestJS DTO allowlist the field must join, the Prisma orderBy, and the tests on each side.
Change the theme: Where the storefront palette, font kit and logo come from at request time, what the admin owns, what a developer may still change in component styles, and how to test a change under the three scenario fixtures.
Add a page: A new storefront route under the locale prefix: the page file, its loader when it needs data at first byte, the title, description, canonical and hreflang block, the link helper, and the Playwright journey that runs it under every configured locale.
Add a home section type: How a home-page section type travels from the Prisma enum through the API’s per-type config DTO, the admin editor, the storefront’s Zod union and the component map, using the trust-signals strip as the worked example.
Change checkout fields: The shipping address shape on the API and the storefront, the phone and postal-code rules on both sides, how a rejected order surfaces as a stable error code and a localized message, and the tests that pin each half.
Add a string: Where the storefront’s own copy lives, the typed contract that makes every catalogue carry every key, the placeholders for the store name and country, how a template reads a string, and the tests that run each journey under every configured locale.
Change SEO and GEO output: Where the storefront’s JSON-LD, canonical and hreflang come from, how sitemaps, robots.txt and the llms.txt files are proxied from the API through Nitro server routes, and the IndexNow ping the API sends when a product becomes visible.
Load data at SSR: How a storefront page fetches at first byte: the .server.ts loader, the per-request API client, why the locale comes from the route params, why the query string rides a header on the production build, cookie forwarding, and the 304 short-circuit.
Add a Nitro alias: Why a server-side import through a tsconfig path alias builds green and fails at runtime on the production storefront, the nitro.alias map in vite.config.ts that fixes it, and the two gates that prove the fix.
Add a model: Declare a Prisma model with its soft-delete column and foreign keys, register it with the soft-delete filter, write the migration record, apply the schema the way the installer does, and guard any contested counter.
Seed a model: The three seed paths in prisma/seed.ts, what each one plants, how SEED_SCOPE keeps demo data off a production database, where the installer runs them, and how to add rows for a new model to the right one.
Search after schema changes: Why a bare prisma db push drops the product search column and leaves its trigger behind, what breaks, how the API refuses to boot on a broken dev database, the one repair command, and what the search index actually covers.
Testing and gates: The commands to run before a change ships, per application, what each one proves, what CI refuses on a push, and the rules the e2e harnesses hold: one harness at a time on the test database, a fail-closed identity check on the API, no skips, no route mocks.
Release your fork: What npm run release checks, builds, archives and tags, what the tarball holds and leaves out, the version and changelog convention it enforces, and how to keep a fork rebased on an upstream release tag without losing your seeds and env examples.

Build a storefront

The storefront contract: What any storefront owes the engine: the ten obligations, why each exists, the flow page that shows it as requests, and the file in the shipped storefront that proves it.
Run the engine: Install the engine locally in two commands, learn what the demo fixture holds, where the API lives with its /api prefix, and make the first two requests: GET /health and GET /v1/store/config.
Config, locale and money: GET /v1/store/config, field by field: identity, brand tokens as CSS custom properties, locales and direction, the money format with a three-decimal currency, tax display, domains, the sixty-second public cache, and what GET /v1/storefront/config adds.
Auth and session: Better Auth under /api/v1/auth/*: sign-up and the verification mail, sign-in, get-session, sign-out, the two cookies a storefront carries with credentials: ‘include’, the atomic session bootstrap, and the bot protection a production store enables.
Catalog and search: The category tree, the product list with its filters, sort allowlist and pagination, the product detail, brand and specification facets, full-text search, suggestions and search filters, with the product shape a storefront renders, the asset variants it picks for srcset, and the same responses under both locales.
Cart: The anonymous cart behind the HttpOnly sessionId cookie: how the first add creates it, reading it under both locales, updating and removing lines, coupon and gift card, the shipping and tax estimate, clearing it, and folding it into the account cart on sign-in.
Checkout and orders: Read the checkout settings, quote shipping for an address, place a cash-on-delivery order with an idempotency key and retry it safely, read the order back as a guest or a customer, track it, cancel it, fetch its invoice, and map every error code to text in each locale.
Account: The signed-in customer’s routes behind the session cookie and the ownership check: profile, saved addresses and the default address, the order history, returns, the wishlist and its id list, notification preferences, and the 401 and 403 envelopes a storefront maps.
Content and sections: GET /v1/pages and GET /v1/pages/{slug} for the operator’s rich-text pages, GET /v1/storefront/sections/{pageSlug} for the home page blocks with every section type and its fields, the deprecated home-banners route, and what a storefront renders as HTML, what it must escape, and how it stays correct when a type or a field is missing.
SEO and GEO: The sitemap index and its three sitemaps, robots.txt, llms.txt and llms-full.txt that the API builds with your storefront’s URLs and that your storefront serves at its own root, the redirect table it honours with a 301 before routing, the IndexNow ping the engine sends, and the JSON-LD, canonical, hreflang, lang and dir a storefront emits per page type, with one product’s JSON-LD built from the pasted response.
Analytics and events: The write-side signals a storefront sends: analytics events, the search event id you echo on click and on conversion, reviews and questions with their helpful votes, the newsletter double opt-in, the contact form, and the honeypot and Turnstile headers both doors require.
Revalidation: The route a storefront exposes so the engine can tell it a page changed: the secret header, the body of paths and a reason, the events that fire it, the fast 200 it must answer, the dedup window, and what to invalidate in Next.js, Nuxt and SvelteKit.
Conformance checklist: The ten obligations of the storefront contract as a checklist: for each, the request that proves it and what you should see, plus the REST Client file and the Postman collection that hold every storefront request.
Reference implementation: How the shipped Analog.js storefront meets each of the ten obligations: the files, the functions and a real excerpt from each, so you can read a working answer.
Framework notes: What changes in Next.js, Nuxt 3 and SvelteKit against the framework-neutral fetch the flow pages show: cookie forwarding at SSR, the idempotency key on a retried action, 304 and the fetch caches, the base URL, the SEO proxy routes and the revalidation route.

Reference

Environment variables: Every environment variable the API and the storefront read, with the comment that explains it, from the example files in the repository.
Install CLI: Every flag of setup.sh and setup.ps1, the install profiles, and the schema of the answers file a non-interactive run reads.
Store config: The schema of GET /v1/store/config: identity, brand palette, font kit, locales, direction, money format and domains, field by field.
Permissions: Every module and action permission of the admin API, and the routes that enforce each one, read from the controllers.
Error codes: Every error code the API can answer with, its HTTP status, its messages and the module that raises it, read from the exception sites in the code.
Analytics (storefront API): The 1 storefront route of the analytics module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Cart (storefront API): The 12 storefront routes of the cart module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Categories (storefront API): The 3 storefront routes of the categories module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Checkout (storefront API): The 1 storefront route of the checkout module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Contact (storefront API): The 1 storefront route of the contact module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Gift cards (storefront API): The 1 storefront route of the gift cards module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Health (storefront API): The 2 storefront routes of the health module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Newsletter (storefront API): The 4 storefront routes of the newsletter module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Orders (storefront API): The 8 storefront routes of the orders module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Pages (storefront API): The 2 storefront routes of the pages module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Products (storefront API): The 11 storefront routes of the products module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Promotions (storefront API): The 2 storefront routes of the promotions module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Questions (storefront API): The 2 storefront routes of the questions module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Returns (storefront API): The 2 storefront routes of the returns module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Reviews (storefront API): The 3 storefront routes of the reviews module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Search (storefront API): The 5 storefront routes of the search module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Seo (storefront API): The 9 storefront routes of the seo module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Shipping (storefront API): The 1 storefront route of the shipping module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Store (storefront API): The 1 storefront route of the store module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Storefront (storefront API): The 3 storefront routes of the storefront module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Unsubscribe (storefront API): The 2 storefront routes of the unsubscribe module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Users (storefront API): The 8 storefront routes of the users module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Wishlist (storefront API): The 4 storefront routes of the wishlist module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Analytics (admin API): The 9 admin routes of the analytics module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Assets (admin API): The 6 admin routes of the assets module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Attributes (admin API): The 7 admin routes of the attributes module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Audit log (admin API): The 2 admin routes of the audit log module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Campaigns (admin API): The 9 admin routes of the campaigns module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Carriers (admin API): The 5 admin routes of the carriers module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Categories (admin API): The 5 admin routes of the categories module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Checkout (admin API): The 2 admin routes of the checkout module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Countries (admin API): The 2 admin routes of the countries module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Currencies (admin API): The 3 admin routes of the currencies module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Customers (admin API): The 4 admin routes of the customers module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Geo (admin API): The 3 admin routes of the geo module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Gift cards (admin API): The 6 admin routes of the gift cards module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Inventory (admin API): The 10 admin routes of the inventory module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
License (admin API): The 2 admin routes of the license module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Notifications (admin API): The 13 admin routes of the notifications module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Orders (admin API): The 12 admin routes of the orders module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Pages (admin API): The 4 admin routes of the pages module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Payment methods (admin API): The 6 admin routes of the payment methods module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Product specs (admin API): The 1 admin route of the product specs module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Product types (admin API): The 4 admin routes of the product types module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Products (admin API): The 17 admin routes of the products module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Promotions (admin API): The 5 admin routes of the promotions module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Questions (admin API): The 4 admin routes of the questions module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Returns (admin API): The 8 admin routes of the returns module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Reviews (admin API): The 5 admin routes of the reviews module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Roles (admin API): The 3 admin routes of the roles module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Search (admin API): The 10 admin routes of the search module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Seo (admin API): The 11 admin routes of the seo module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Settings (admin API): The 4 admin routes of the settings module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Shipping (admin API): The 7 admin routes of the shipping module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Staff (admin API): The 4 admin routes of the staff module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Storefront (admin API): The 8 admin routes of the storefront module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Subscribers (admin API): The 2 admin routes of the subscribers module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Tax (admin API): The 6 admin routes of the tax module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Webhooks (admin API): The 7 admin routes of the webhooks module: parameters, request bodies, responses and schemas, generated from the OpenAPI document.
Changelog: What each release of themerchantengine changed, from the CHANGELOG file in the repository.