Tenancy — stores and outlets

Concepts

• Store (stores table, StoreEntity) is the primary anchor for outlet-scoped data. Admin and vendor APIs take an explicit store_id (or resolve the store from the entity being edited) rather than inferring scope from a zone claim on the JWT.
• Vendor tenancy is keyed by vendor_id on the vendor JWT and by store_id for employee sessions where applicable.
• Master admin behavior: modules === null on the admin JWT means unrestricted module access in backend guards (see Admin panel overview).

API behavior

• Admin catalog and related flows call helpers such as assertStoreAllowedForAdmin(admin, storeId) to ensure the store_id is present and the store row exists before mutating catalog data. (Legacy docs referred to zone_id matching; that coupling has been removed from the Nest services and entities—zone_id may still exist on older MySQL rows but is not used for JWT scoping in this codebase.)
• Enforcement lives in services (explicit store checks, joins, vendor guards), not only in JWT guards — expect 403 when a role lacks a module key or a store is not visible to the actor.

Legacy schema note

• New columns on older tables may use the project TABLE_FIELD_PREFIX helper fp(...) in migrations — entity @Column({ name: fp('store_id') }) must match SQL. Do not rename legacy columns that already exist without a migration.

For a visual schema, generate an ERD from your MySQL database or link an internal diagram — the code sources of truth are StoreEntity, admin/vendor services, and module guards.

Related

• Authentication — JWT claims.
• Environment configuration — tenancy-related env vars if any.