CartistoDocs
⌕

Architecture

Multi-tenancy, the request flow, and how storefronts render.

A high-level map of how a Cartisto store serves a request. You don’t need this to build a theme or an integration, but it explains why the contracts are shaped the way they are.

Multi-tenancy by row-level security

Every store is a tenant, and all tenants share one database with row-level security (RLS): each per-tenant table has a policy that filters rows to the current tenant automatically. A request establishes its tenant context, and from then on every query — read or write — can only see that tenant’s rows.

The consequence for you: there is no tenant id to pass and no way to reach across stores. Isolation isn’t application logic you can forget to apply; it’s enforced beneath the query layer.

The request flow

HTTP request
  → reverse proxy (TLS, adds the tenant-domain header)
  → identify tenant   (resolves the store from the host, sets the tenant context)
  → authenticate      (session JWT or API key)
  → authorize         (role / key permissions)
  → route handler     (reads/writes only this tenant's data)

Global data (the platform user table, the theme marketplace, exchange rates, plans) lives in a master schema; per-tenant data (products, orders, customers, carts, themes) lives in the tenant-scoped schema under RLS.

How storefronts render

  • Every theme — platform and custom — renders through one sandboxed Liquid engine. Platform themes read templates from disk; custom themes read them from the store’s database. The contract is identical.
  • Commerce behavior is a platform JavaScript bundle (window.cartisto), content-hashed and served with a long cache plus instant invalidation, so a fix reaches every store at once.
  • The money path is locked. Checkout and order-confirmation render from platform-owned templates in a platform-owned layout — no theme script or merchant custom JS runs on the payment surface.

Where the docs map onto this

Layer Portal
Liquid templates, the client SDK, the CLI Theme Developer
The REST API + webhooks App & API
The contracts + how they version Versioning & Specifications