diff --git a/docs/BACKEND_INTEGRATION.md b/docs/BACKEND_INTEGRATION.md
new file mode 100644
index 0000000..222a5f9
--- /dev/null
+++ b/docs/BACKEND_INTEGRATION.md
@@ -0,0 +1,4349 @@
+# Backend Integration — Canonical Specification
+
+**This is the single source of truth for backend implementation.** It supersedes and merges `docs/BACKEND_API.md`, `docs/AUTH.md`, `docs/ADMIN.md`, and `docs/BACKEND_API_REMAINING_WORK.md` (all archived — see `docs/archive/` and the note at the end of this file). It incorporates `docs/AUTHENTICATION.md` (§4) and `docs/ERROR_CONTRACT.md` (§6) in full; those files remain in place as standalone references but this document is authoritative. `docs/MAINTENANCE_MODE.md` is a companion doc, referenced from §6.
+
+Everything here is derived from the actual current frontend source code (branch `B2B`), not from prior/stale documentation. Primary input: `docs/context/BACKEND-AUDIT.md` (exhaustive audit of every HTTP call, gateway, facade, and model in the frontend).
+
+**Convention used throughout:** where the frontend already implies a concrete behavior, it's documented as-is. Where the frontend has no opinion and a real backend needs one, it's marked **"Requires backend decision"** — nothing beyond what the frontend requires is invented.
+
+## Table of contents
+
+1. [Bootstrap](#1-bootstrap)
+2. [Endpoint Documentation Framework](#2-endpoint-documentation-framework)
+3. [CRUD Contracts](#3-crud-contracts)
+4. [Authentication](#4-authentication)
+5. [Security](#5-security)
+6. [Error Model](#6-error-model)
+7. [Uploads](#7-uploads)
+8. [Real Backend Implementation Guide](#8-real-backend-implementation-guide)
+9. [Backend Checklist](#9-backend-checklist)
+
+---
+## 1. Bootstrap
+
+The bootstrap document is the single runtime-configuration payload that drives
+the entire multi-tenant storefront/builder/backoffice. It is fetched once at
+app startup and held in memory; nearly every feature (theme, navigation,
+localization, catalog behavior, static pages, feature flags, widget registry)
+reads from it rather than from dedicated per-feature endpoints.
+
+Source of truth for this section:
+`src/app/core/bootstrap/providers/api-bootstrap.provider.ts`,
+`src/app/core/config/config.service.ts`,
+`src/app/core/config/api-config.service.ts`,
+`src/app/core/config/tenant-resolver.service.ts`,
+`src/app/shared/models/config/*`, and the mock document
+`src/assets/mock/bootstrap/bootstrap.json`. Cross-referenced against
+`docs/context/BACKEND-AUDIT.md` §6, §2 and the prior `docs/BACKEND_API.md`.
+
+### 1.1 Request contract
+
+| Property | Value |
+|---|---|
+| Method | `GET` |
+| Route (API mode) | `/bootstrap` — relative; rewritten onto the resolved tenant API base by `apiBaseUrlInterceptor` (see §1.10) |
+| Route (mock/local mode) | `GET /assets/mock/bootstrap/bootstrap.json` (static asset, no backend) |
+| Request body | none |
+| Query params | none |
+| Auth requirement | **None.** Bootstrap is fetched before any login and must be publicly cacheable per tenant. It carries no `Authorization` header and no `WebSessionID` is required for it to succeed. |
+
+**Headers.** The provider itself (`ApiBootstrapProvider`) sets no explicit
+headers — it issues a plain `HttpClient.get<BootstrapConfig>('/bootstrap')`.
+Because the URL is `/api`-relative only after interceptor rewrite (the literal
+is `/bootstrap`, not `/api/bootstrap`), whether `apiHeadersInterceptor`'s
+marketplace headers (`X-Region`, `X-Language`, `Currency`, `WebSessionID`)
+attach depends on `ApiConfigService.isApiRequest()` matching the resolved URL.
+In practice the backend must treat all of these as **optional** on the
+bootstrap call — none are load-bearing for it, and the document is expected to
+resolve from tenant/origin alone (§1.9).
+
+> **Requires backend decision:** whether the bootstrap endpoint should honor
+> an `X-Language`/`Accept-Language` hint to pre-select a localization, or
+> always return the full multi-locale document (the frontend today always
+> receives and holds the full multi-locale document and selects locale
+> client-side).
+
+### 1.2 Which provider actually fires
+
+`CONFIG_PROVIDER` (`src/app/core/config/config-provider.token.ts`) is a factory
+bound by `RuntimeProviderStrategyService.getBootstrapProviderMode()`:
+
+- Returns **mock** (`MockBootstrapProvider` → static asset) when
+  `environment.useMockData === true`, **or** when
+  `environment.useMockBootstrapOnLocal === true` **and** the host is localhost.
+- Otherwise returns **api** (`ApiBootstrapProvider` → `GET /bootstrap`).
+
+With the current `environment.ts` (`useMockData: false`,
+`useMockBootstrapOnLocal: true`), a localhost dev session reads the static
+`bootstrap.json`; a deployed tenant host reads the live `GET /bootstrap`.
+
+### 1.3 Response shape — `BootstrapConfig`
+
+Copied faithfully from
+`src/app/shared/models/config/bootstrap-config.model.ts`:
+
+```ts
+export interface BootstrapConfig {
+  schemaVersion: string;
+  generatedAt: string;
+  tenant: TenantConfig;
+  branding: BrandingConfig;
+  theme: ThemeConfig;
+  company: CompanyConfig;
+  featureFlags: FeatureFlagsConfig;
+  features?: MarketplaceFeaturesConfig;
+  apiEndpoints: ApiEndpointsConfig;
+  localization: LocalizationConfig;
+  seo: SeoConfig;
+  permissions: PermissionsConfig;
+  header?: HeaderConfig;
+  catalog?: CatalogConfig;
+  layout?: PlatformLayoutConfig;
+  navigation: NavigationConfig;
+  footer?: FooterConfig;
+  productPage?: ProductPageConfig;
+  userExperience?: UserExperienceConfig;
+  pages: PageConfig[];
+  staticPages?: StaticPagesConfig;
+  widgetRegistry?: WidgetRegistryConfig;
+}
+```
+
+Required (non-optional) top-level keys the backend must always emit:
+`schemaVersion, generatedAt, tenant, branding, theme, company, featureFlags,
+apiEndpoints, localization, seo, permissions, navigation, pages`. Everything
+marked `?` may be omitted; the frontend supplies defaults (e.g.
+`DEFAULT_CATALOG_CONFIG`, `DEFAULT_USER_EXPERIENCE_CONFIG`) when absent.
+
+Each nested field, with its source model file under
+`src/app/shared/models/config/`:
+
+- **`schemaVersion`** (`string`) — document schema version (e.g. `"1.0.0"`).
+  Not enforced by a validator today; see §1.6.
+- **`generatedAt`** (`string`, ISO 8601) — when the tenant's config snapshot
+  was produced. Advisory/diagnostic only today.
+- **`tenant`** (`TenantConfig`, `tenant.model.ts`) —
+  `{ id (UUID), slug, code, host, name, websiteBaseUrl, builderBaseUrl,
+  backofficeBaseUrl, defaultLocale, supportedLocales[], defaultCurrency,
+  supportedCurrencies[], timezone }`. Identifies the tenant and its per-surface
+  base URLs, locale/currency sets, and timezone.
+- **`branding`** (`BrandingConfig`, `branding.model.ts`) —
+  `{ brandName, legalName, slogan?, logoUrl, logoCompactUrl?, faviconUrl,
+  appIconUrl?, socialImageUrl?, galleryUrls?, supportEmail?, supportPhone? }`.
+  Drives header logo, favicon, PWA icon, social share image.
+- **`theme`** (`ThemeConfig`, `theme.model.ts`) —
+  `{ themeId, mode: 'light'|'dark'|'system', palette (12 named colors:
+  primary/secondary/accent/success/warning/danger/info/textPrimary/
+  textSecondary/backgroundPrimary/backgroundSecondary/border), typography
+  (primaryFontFamily, headingFontFamily?, baseFontSize), spacing (unit, scale[]),
+  borderRadiusScale (Record<string,string>), shadows (Record<string,string>),
+  iconSet }`. Consumed by `ThemeEngineService`/`BrandingEngineService` to emit
+  CSS variables at runtime.
+- **`company`** (`CompanyConfig`) — legal entity + address + contacts block
+  (see mock JSON §1.5 for shape: `companyName, registrationNumber, taxId,
+  address{country,region,city,street,postalCode}, contacts{email,phone,
+  telegram,website}`).
+- **`featureFlags`** (`FeatureFlagsConfig`, `feature-flags.model.ts`) — a
+  `Record<string, boolean>` with well-known keys `wishlist, compare, reviews,
+  questions, comments, recommendations, blog, chat, analytics, notifications,
+  coupons, loyalty, giftCards, invoices` plus an open index signature for
+  arbitrary custom flags. Toggle features on/off per tenant.
+- **`features`** (`MarketplaceFeaturesConfig`, optional) — richer per-feature
+  config beyond boolean flags.
+- **`apiEndpoints`** (`ApiEndpointsConfig`, `api-endpoints.model.ts`) —
+  `{ bootstrap: ApiEndpointConfig, website: Record<string,ApiEndpointConfig>,
+  builder: Record<string,ApiEndpointConfig>, backoffice:
+  Record<string,ApiEndpointConfig> }` where `ApiEndpointConfig =
+  { path, method, timeoutMs? }`. **This is where a tenant declares its planned
+  per-surface endpoint paths at runtime.** The `website/builder/backoffice`
+  maps are empty `{}` in the mock today — no builder/backoffice CRUD path
+  exists as a code literal anywhere (BACKEND-AUDIT §24); those endpoints, if
+  ever built, are declared here rather than hard-coded.
+- **`localization`** (`LocalizationConfig`, `localization.model.ts`) —
+  `{ defaultLocale, supportedLocales[], currencyByLocale (Record<locale,
+  currency>), dictionaries: [{ locale, dictionaryUrl, version }] }`. Note the
+  three supported locales are `ru, en, hy`; the marketplace API uses codes
+  `RU, EN, AM` (mapped by `apiHeadersInterceptor` / `ApiService.normalizeLang`,
+  `am↔hy`).
+- **`seo`** (`SeoConfig`, `seo.model.ts`) —
+  `{ default: SeoPageConfig, byPageKey: Record<pageKey, SeoPageConfig> }` where
+  `SeoPageConfig = { title, description, canonicalUrl?, robots?, metaTags? }`.
+- **`permissions`** (`PermissionsConfig`, `permissions.model.ts`) —
+  `{ definitions: [{ key, description? }], roles: [{ role, permissions[] }] }`.
+  Bootstrap-level RBAC catalog. (Distinct from the Ed25519 JWT `AdminRole`
+  union — see `docs/AUTHENTICATION.md` §9 for the flagged `AdminRole` naming
+  collision.)
+- **`header`** (`HeaderConfig`, optional) — header layout config.
+- **`catalog`** (`CatalogConfig`, `catalog-config.model.ts`, optional) — the
+  storefront catalog behavior contract:
+  `{ layout, loadingStrategy: 'pagination'|'loadMore'|'infiniteScroll',
+  navigationMode, defaultSort, availableSorts[], enabledFilters[],
+  showBreadcrumbs, showCategoryBanner, showSubcategoryChips, showRatings,
+  showDiscounts, showAvailability, suggestionsEnabled, searchHistoryEnabled }`.
+  `defaultSort`/`availableSorts` enumerate `relevance | latest | price_asc |
+  price_desc | rating | popular | discount` (see §2.3). Defaults in
+  `DEFAULT_CATALOG_CONFIG`.
+- **`layout`** (`PlatformLayoutConfig`, optional) — global layout type.
+- **`navigation`** (`NavigationConfig`, `navigation.model.ts`) —
+  `{ header: NavigationItemConfig[], footer: NavigationItemConfig[] |
+  FooterNavigationGroupConfig[], sidebar?: NavigationItemConfig[] }`. Items
+  carry `{ id, labelKey?|label?, route?, icon?, order?, visible?,
+  visibleWhenFlags?, children? }` — note `visibleWhenFlags` lets a nav item be
+  gated on a `featureFlags` key.
+- **`footer`** (`FooterConfig`, `footer-config.model.ts`, optional) —
+  `{ logoUrl?, paymentIcons?, copyrightText? (string|localized), columns?
+  (FooterColumnConfig[]), socialLinks? }`. `legalPageKeys`/`staticPageKeys` are
+  `@deprecated` in favor of `columns` but still resolve for older saved configs.
+- **`productPage`** (`ProductPageConfig`, optional) — per-PDP config; in the
+  mock: `rating{enabled}, reviews{enabled,pageSize,showSummary},
+  questions{enabled,pageSize}, tabs{enabled,items[]}, relatedProducts{enabled}`.
+  Note `reviews.pageSize`/`questions.pageSize` (5 in mock) are the storefront
+  engagement page sizes (§2.2).
+- **`userExperience`** (`UserExperienceConfig`, `user-experience-config.model.ts`,
+  optional) — `{ wishlist, compare{maxItems,...}, recentlyViewed{maxItems,...},
+  share, continueBrowsing, savedSearches{maxItems} }` limits/toggles for the
+  guest-first UX features. Defaults in `DEFAULT_USER_EXPERIENCE_CONFIG`.
+- **`pages`** (`PageConfig[]`, `page.model.ts`) — the dynamic page tree the
+  renderer builds routes from: each `{ id, key, title, route{path,exact?},
+  layout, sections: SectionConfig[], seoKey?, featureFlag?, visible? }`. Each
+  section holds ordered `widgets` with `props` (see mock §1.5 for a full
+  hero/categories/product-collection example). This is the builder's output.
+- **`staticPages`** (`StaticPagesConfig`, `static-page.model.ts`, optional) —
+  either `Record<slug, StaticPageConfig>` or a legacy array. Each page carries
+  localized `title` + `html`/`content`, `route`, `seo`, `status:
+  'draft'|'published'`, `enabled`, `visibility`, `updatedAt`, etc. Storefront
+  legal/content pages live here (about-us, privacy-policy, terms-of-service in
+  the mock). Content-management edits operate on this in-memory (BACKEND-AUDIT
+  §16) — no dedicated content backend.
+- **`widgetRegistry`** (`WidgetRegistryConfig`, optional) —
+  `{ manifestUrl: string }`; the URL `WidgetManifestService` fetches the widget
+  manifest from (§2 "Widget manifest" endpoint).
+
+### 1.4 Versioning
+
+`BootstrapConfig.schemaVersion` (string) **does** exist and is the schema/version
+field. Current usage:
+
+- The mock document sets `"schemaVersion": "1.0.0"`.
+- `bootstrap-diagnostics.validator.ts:44` surfaces it as a diagnostic entry
+  (`['schemaVersion', bootstrap.schemaVersion]`).
+- `AdminDashboardFacade` (`admin-dashboard.facade.ts:110`) derives the
+  `dashboard.healthBootstrapValid` health check purely as
+  `healthy: !!current?.schemaVersion` — i.e. "bootstrap is valid" today means
+  only "a schemaVersion string is present," **not** any real semantic-version
+  compatibility check.
+
+> **Requires backend decision:** whether `schemaVersion` should be enforced
+> (frontend rejecting/ warning on an unknown major version). No such
+> enforcement exists today — any string is accepted, and only its presence is
+> checked.
+
+### 1.5 Example JSON
+
+Realistic example, taken from the actual mock document
+`src/assets/mock/bootstrap/bootstrap.json` (abridged — pages/staticPages
+trimmed for length; full versions in that file):
+
+```json
+{
+  "schemaVersion": "1.0.0",
+  "generatedAt": "2026-07-03T00:00:00Z",
+  "tenant": {
+    "id": "tenant-default-001",
+    "slug": "default",
+    "code": "DEFAULT",
+    "host": "default.local",
+    "name": "Marketplace",
+    "websiteBaseUrl": "https://marketplace.local",
+    "builderBaseUrl": "https://builder.marketplace.local",
+    "backofficeBaseUrl": "https://backoffice.marketplace.local",
+    "defaultLocale": "ru",
+    "supportedLocales": ["ru", "en", "hy"],
+    "defaultCurrency": "RUB",
+    "supportedCurrencies": ["RUB", "USD", "EUR", "AMD"],
+    "timezone": "Europe/Moscow"
+  },
+  "branding": {
+    "brandName": "Marketplace",
+    "legalName": "Marketplace LLC",
+    "slogan": "Digital commerce marketplace",
+    "logoUrl": "/icons/icon-192x192.png",
+    "faviconUrl": "/favicon.ico",
+    "supportEmail": "support@marketplace.local",
+    "supportPhone": "+7-900-000-00-00"
+  },
+  "theme": {
+    "themeId": "default-light",
+    "mode": "light",
+    "palette": {
+      "primary": "#497671", "secondary": "#a1b4b5", "accent": "#a7ceca",
+      "success": "#10b981", "warning": "#f59e0b", "danger": "#ef4444",
+      "info": "#3b82f6", "textPrimary": "#1e3c38", "textSecondary": "#667a77",
+      "backgroundPrimary": "#ffffff", "backgroundSecondary": "#f5f5f5",
+      "border": "#d3dad9"
+    },
+    "typography": { "primaryFontFamily": "DM Sans, sans-serif", "baseFontSize": 16 },
+    "spacing": { "unit": 4, "scale": [0, 4, 8, 12, 16, 24, 32, 48] },
+    "borderRadiusScale": { "sm": "8px", "md": "12px", "lg": "16px", "xl": "22px" },
+    "shadows": { "sm": "0 2px 8px rgba(0,0,0,0.1)" },
+    "iconSet": "default"
+  },
+  "company": {
+    "companyName": "Marketplace LLC",
+    "registrationNumber": "1027700000000",
+    "taxId": "7700000000",
+    "address": { "country": "Russia", "region": "Moscow", "city": "Moscow", "street": "Tverskaya 1", "postalCode": "125009" },
+    "contacts": { "email": "support@marketplace.local", "phone": "+7-900-000-00-00", "telegram": "@marketplace_support", "website": "https://marketplace.local" }
+  },
+  "featureFlags": {
+    "wishlist": true, "compare": true, "reviews": true, "blog": false,
+    "chat": false, "analytics": true, "notifications": true, "coupons": true,
+    "loyalty": false, "giftCards": false, "invoices": true
+  },
+  "apiEndpoints": {
+    "bootstrap": { "path": "/bootstrap", "method": "GET", "timeoutMs": 10000 },
+    "website": {}, "builder": {}, "backoffice": {}
+  },
+  "localization": {
+    "defaultLocale": "ru",
+    "supportedLocales": ["ru", "en", "hy"],
+    "currencyByLocale": { "ru": "RUB", "en": "USD", "hy": "AMD" },
+    "dictionaries": [
+      { "locale": "ru", "dictionaryUrl": "/assets/i18n/ru.json", "version": "1.0.0" },
+      { "locale": "en", "dictionaryUrl": "/assets/i18n/en.json", "version": "1.0.0" },
+      { "locale": "hy", "dictionaryUrl": "/assets/i18n/hy.json", "version": "1.0.0" }
+    ]
+  },
+  "seo": {
+    "default": { "title": "Marketplace", "description": "Digital commerce marketplace", "robots": "index,follow" },
+    "byPageKey": { "home": { "title": "Marketplace - Home", "canonicalUrl": "https://marketplace.local/", "robots": "index,follow" } }
+  },
+  "permissions": {
+    "definitions": [
+      { "key": "builder.pages.edit", "description": "Edit pages in builder" },
+      { "key": "backoffice.products.read", "description": "Read products in backoffice" }
+    ],
+    "roles": [
+      { "role": "builder_admin", "permissions": ["builder.pages.edit"] },
+      { "role": "backoffice_manager", "permissions": ["backoffice.products.read"] }
+    ]
+  },
+  "catalog": {
+    "layout": "grid", "navigationMode": "default", "defaultSort": "relevance",
+    "availableSorts": ["relevance", "latest", "price_asc", "price_desc", "rating", "popular", "discount"],
+    "enabledFilters": ["price", "availability", "rating", "brand", "category", "subcategory", "discount", "new", "color", "size", "attributes"],
+    "showBreadcrumbs": true, "showRatings": true, "showDiscounts": true, "showAvailability": true
+  },
+  "productPage": {
+    "rating": { "enabled": true },
+    "reviews": { "enabled": true, "pageSize": 5, "showSummary": true },
+    "questions": { "enabled": true, "pageSize": 5 },
+    "relatedProducts": { "enabled": true }
+  },
+  "navigation": {
+    "header": [
+      { "id": "nav-home", "labelKey": "nav.home", "route": "/", "icon": "home", "order": 1 },
+      { "id": "nav-search", "labelKey": "nav.search", "route": "/search", "icon": "search", "order": 2 }
+    ],
+    "footer": [
+      { "id": "footer-about", "labelKey": "nav.about", "route": "/about-us", "order": 1 }
+    ]
+  },
+  "footer": {
+    "copyrightText": { "ru": "© 2026 Marketplace. Все права защищены.", "en": "© 2026 Marketplace. All rights reserved." },
+    "legalPageKeys": ["about-us", "privacy-policy", "terms-of-service"]
+  },
+  "widgetRegistry": { "manifestUrl": "/assets/mock/bootstrap/widget-manifest.json" },
+  "staticPages": {
+    "about-us": {
+      "route": "/about-us",
+      "title": { "ru": "О компании", "en": "About Us", "hy": "Մեր մասին" },
+      "html": { "ru": "<h2>О компании</h2><p>…</p>", "en": "<h2>About Us</h2><p>…</p>" }
+    }
+  },
+  "pages": [
+    {
+      "id": "page-home", "key": "home", "title": "Home",
+      "route": { "path": "/", "exact": true },
+      "layout": { "type": "default" }, "seoKey": "home", "visible": true,
+      "sections": [
+        {
+          "id": "section-hero", "type": "hero", "order": 1,
+          "layout": { "strategy": "hero", "columns": 1, "gap": "1.5rem", "align": "stretch" },
+          "visible": true,
+          "widgets": [
+            {
+              "id": "widget-hero-main", "type": "hero", "version": "1.0.0", "order": 1,
+              "props": {
+                "title": { "ru": "Добро пожаловать на Маркетплейс", "en": "Welcome to Marketplace Platform" },
+                "ctaLabel": { "ru": "Начать покупки", "en": "Start Shopping" }
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 1.6 Lifecycle
+
+- There is **no `APP_INITIALIZER`** wiring bootstrap fetch as a hard app
+  precondition. `main.ts` calls `bootstrapApplication(App, appConfig)` with no
+  initializer that blocks on config. (`docs/AUTHENTICATION.md` §5.2 separately
+  notes the Ed25519 `restoreSession()` initializer is also not wired.)
+- Bootstrap is instead loaded lazily-but-eagerly by the first consumer to need
+  it. Multiple root-level services subscribe to `ConfigService.loadBootstrap()`
+  at construction: `UiRuntimeFacade` (`ui-runtime.facade.ts:32`),
+  `PlatformRuntimeService`, `ThemeEngineService`, `BrandingEngineService`, the
+  `FooterComponent`, etc. Because `ConfigService` de-dupes (§1.7), the first
+  one triggers the single HTTP call and the rest share it.
+- The `languageGuard` (`src/app/guards/language.guard.ts`, wrapping every
+  `:lang` route) runs on navigation and preloads the locale dictionary; it is
+  **not** itself the bootstrap fetcher, but it runs in the same startup window.
+  Bootstrap and language resolution are effectively concurrent — the app does
+  not gate rendering on bootstrap completion, so components must tolerate a
+  transient null snapshot.
+
+### 1.7 Caching behavior (what the frontend actually does)
+
+`ConfigService` (`src/app/core/config/config.service.ts`) is the cache, and it
+is **in-memory only** — no `localStorage`, no HTTP cache header logic:
+
+- Holds `bootstrapSnapshot: BootstrapConfig | null` (last successful value) and
+  a shared `bootstrap$` observable with `shareReplay(1)`.
+- `loadBootstrap(forceRefresh = false)`: returns the cached `bootstrap$` when a
+  snapshot exists and `forceRefresh` is false; otherwise (re)issues the
+  provider call.
+- On error, it clears both `bootstrap$` and `bootstrapSnapshot` so the next
+  call retries cleanly (`catchError` rethrows).
+- A `bootstrapRevision` signal increments on every successful load/override —
+  consumers use it to react to config changes.
+- `getBootstrapSnapshot()` returns the current in-memory value synchronously
+  (used by `WidgetManifestService`, diagnostics, etc.).
+- The cache does **not** survive a page reload — every full page load re-fetches
+  bootstrap. There is also a separate client-side `cacheInterceptor`
+  (GET-response caching, BACKEND-AUDIT §3) that may cache the `/bootstrap`
+  response at the HTTP layer within a session, but nothing persists it across
+  sessions.
+
+### 1.8 ETag / conditional requests
+
+**Requires backend decision — no ETag / conditional-request logic exists in
+the frontend today.** The bootstrap provider issues a plain unconditional
+`GET`; nothing reads or sends `ETag`, `If-None-Match`, `Last-Modified`, or
+`If-Modified-Since`. If the backend wants conditional revalidation of the
+(large, per-tenant, infrequently changing) bootstrap document, both the wire
+strategy and the frontend handling for it would be new work.
+
+### 1.9 Tenant resolution
+
+Tenant is resolved by **subdomain**, not by header or path (full detail in
+`docs/AUTHENTICATION.md` §10; source
+`src/app/core/config/tenant-resolver.service.ts`):
+
+- `TenantResolverService.getTenantKey()`: localhost →
+  `environment.fallbackTenantKey ?? 'default'`; otherwise the **first DNS
+  label** of the hostname, skipping a leading `www` (e.g.
+  `dexarmarket.api.dexarmarket.ru` → `dexarmarket`; `www.acme.com` → `acme`).
+- That tenant key feeds `ApiConfigService.getBaseUrl()`, which picks the
+  marketplace API base: localhost → `environment.localhostApiUrl` (`/api`);
+  else `environment.tenantApiBaseUrls[tenantKey]`; else
+  `environment.tenantApiTemplate` with `{tenant}` substituted; else (only when
+  `allowBootstrapApiOverride` is true — off by default) a value read out of the
+  already-loaded bootstrap (`apiEndpoints.website.baseUrl` /
+  `tenant.apiBaseUrl`).
+- **No `X-Tenant` header or `/tenant/{id}` path prefix is ever sent.** Tenant
+  isolation for `GET /bootstrap` is achieved purely by *which origin/subdomain
+  the request goes to* — the backend must infer the tenant from the request
+  host, and return that tenant's bootstrap document.
+
+### 1.10 Draft vs Published
+
+The storefront and the builder read the **same** in-memory `BootstrapConfig`;
+there is no separate "draft bootstrap" vs "live bootstrap" endpoint today
+(BACKEND-AUDIT §17):
+
+- The builder (`ProjectEditorFacade`,
+  `src/app/features/project-editor/facade/project-editor.facade.ts`) loads the
+  bootstrap via `ConfigService.loadBootstrap(true)` (force refresh), edits an
+  in-memory `History<BootstrapConfig>` (undo/redo), and persists **drafts to
+  localStorage** through `ProjectEditorDraftStorageService`.
+- `ConfigService.applyBootstrapOverride(next)` swaps the in-memory snapshot
+  (deep-cloned) so a preview reflects edits immediately — but this is purely
+  client-side.
+- **There is no publish/write HTTP call.** No `PUT /bootstrap`, no
+  builder-write endpoint exists anywhere in code. "Publishing a marketplace"
+  (writing the edited bootstrap back so the live storefront serves it) is
+  **FUTURE / LOCAL-ONLY today**. Any builder publish endpoint would be declared
+  under `apiEndpoints.builder` (runtime-declared) and is a backend build item,
+  not something the frontend currently calls.
+
+> **Requires backend decision:** the entire draft→publish write path
+> (endpoint, method, optimistic-concurrency / version check on save, and
+> whether draft state is server-persisted or stays localStorage-only).
+
+### 1.11 Fallback behavior (bootstrap fails to load)
+
+- `ConfigService` does **not** substitute a default document on failure — it
+  clears its cache and rethrows, so each subscribing consumer sees the error.
+- There is no global "bootstrap failed" full-screen error page. Instead,
+  individual engines degrade: `ThemeEngineService`/`BrandingEngineService`
+  subscribe with `take(1)` and simply do nothing extra on error (the app keeps
+  its compiled default styles); optional config getters fall back to hard-coded
+  defaults (`DEFAULT_CATALOG_CONFIG`, `DEFAULT_USER_EXPERIENCE_CONFIG`);
+  `WidgetManifestService` falls back to the static manifest URL on any bootstrap
+  error.
+- Feature-specific consumers that require bootstrap data render their own
+  generic empty/error states (the same `common.errorTitle` pattern described in
+  `docs/ERROR_CONTRACT.md`), not a bootstrap-specific one.
+
+> **Requires backend decision / frontend follow-up:** whether a hard bootstrap
+> failure should present a dedicated tenant-level error screen. Today the
+> failure is silent-ish (default theme, empty dynamic pages) rather than a
+> blocking error, which is a UX gap if the backend can actually return a fatal
+> bootstrap error.
+
+### 1.12 Failure responses
+
+The frontend does not parse a bootstrap-specific error body — a failed
+`GET /bootstrap` surfaces as a bare `HttpErrorResponse` handled per §1.11. For
+the standard error envelope every endpoint (including this one) should return
+on non-2xx, and the per-status semantics (401/403/404/409/422/429/500/503,
+plus `TENANT_DISABLED` and `MAINTENANCE_MODE`), see
+**`docs/ERROR_CONTRACT.md`** — that document owns the error envelope and this
+section does not redefine it. Two of its rows are especially relevant to
+bootstrap:
+
+- **`TENANT_DISABLED`** (HTTP 403, `error.code: "TENANT_DISABLED"`) — the
+  natural failure for `GET /bootstrap` against a known-but-inactive tenant.
+  `ERROR_CONTRACT.md` marks the frontend handling for this as "Requires backend
+  decision" (no code path handles it today).
+- **`MAINTENANCE_MODE`** (HTTP 503, `error.code: "MAINTENANCE_MODE"`) — if a
+  tenant is down for maintenance, bootstrap is where the frontend would first
+  hit it. Again, no maintenance concept exists frontend-side today.
+
+---
+
+## 2. Endpoint Documentation Framework
+
+This section defines the **general contract every endpoint in the system
+follows**, so the reader has the framework before the per-domain endpoint
+catalog (a separate section). Where the frontend does not define something,
+it is marked **"Requires backend decision"** rather than invented.
+
+### 2.1 Standard success response envelope
+
+**There is no `ApiResponse<T>` / `{ success, data, error }` envelope in this
+codebase.** Every live caller types its `HttpClient` call to the **bare payload
+type** and consumes the raw JSON directly:
+
+- `ApiService.getItem()` → `HttpClient.get<Item>(...)` (the item object itself).
+- `ApiService.getCategories()` → `get<Category[]>` (bare array).
+- `ApiBootstrapProvider` → `get<BootstrapConfig>` (bare object).
+- `TelegramSessionApiService` → `get<Record<string, unknown>>` then normalizes.
+
+The generic `ApiResponse<T>` shape in the org coding-standards is **not** used
+here — do not assume an envelope. Success responses are the raw resource
+(object, array, or `{ items, total }` for lists — see §2.2).
+
+> **Requires backend decision:** whether to *introduce* a success envelope
+> going forward. If adopted it would be a breaking change to every existing
+> live caller listed in §2.6 and BACKEND-AUDIT §4, each of which currently
+> expects the bare payload. Recommendation: keep bare payloads for the existing
+> live endpoints; only new endpoints could opt into an envelope, and even then
+> the frontend has no envelope-unwrapping layer today (one would be new work).
+
+### 2.2 Standard pagination contract
+
+Two distinct pagination shapes already exist in the frontend; a backend should
+align to these rather than invent a third:
+
+**A) Offset/count style (marketplace list + search endpoints)** — used by the
+live `ApiService`:
+
+- Request query params: **`count`** (page size, default 50) and **`skip`**
+  (offset, default 0). Applied on `GET /category/{id}`, `GET /searchitems`,
+  `GET /items/randomitems`.
+- Response for `searchItems`: `{ items: Item[], total: number }`. Other list
+  endpoints (`getCategoryItems`, `getRandomItems`) return a **bare array** with
+  no total.
+
+**B) Page/pageSize style (admin lists, storefront engagement lists, media)** —
+used by facade/gateway list results:
+
+- Request: `{ page: number, pageSize: number }` (plus filters — §2.4). See
+  `AdminOrderListFilters`, `EngagementListQuery`, `MediaListParams`.
+- Response: `{ items: T[], total: number, page: number, pageSize: number }`.
+  Canonical shapes: `EngagementListResult<T>`
+  (`core/products/models/product-engagement.model.ts:55`), `AdminOrdersListResult`
+  (`features/admin/orders/models/admin-order.model.ts:63`), `MediaListResult`
+  (`{ items, total }` only). The UI derives `totalPages = ceil(total /
+  pageSize)` client-side (e.g. `pagination.component.ts`, admin list pages).
+
+Notes / open items:
+
+- The two styles use different param names (`count`/`skip` vs `page`/`pageSize`)
+  — a backend serving both storefront and admin must support both, or a
+  reconciliation decision is needed.
+- **No cursor/keyset pagination anywhere.** The only `cursor` matches in source
+  are CSS `cursor:` properties. There is no `nextCursor`/`hasMore` on the wire
+  (`catalog-state.model.ts` has a client-derived `hasMore` for infinite-scroll,
+  computed as `skip + pageSize < total`, not a backend field).
+
+> **Requires backend decision:** exact page-size **limits/maximums** (the
+> frontend sends 50 as a default `count` but enforces no server-side cap),
+> whether to standardize on offset vs page-number, and whether large lists
+> should move to cursor pagination (nothing in the frontend implies or requires
+> cursors today).
+
+### 2.3 Standard sorting contract
+
+Sorting is **enumerated in the bootstrap `catalog` config**, not free-form:
+
+- `CatalogConfig.availableSorts` / `CatalogConfig.defaultSort` (see §1.3,
+  `catalog-config.model.ts`) enumerate the allowed values:
+  `relevance | latest | price_asc | price_desc | rating | popular | discount`.
+- The live wire param is `sort` on `GET /searchitems`
+  (`ApiService.searchItems`), whose accepted set is a subset:
+  `relevance | price_asc | price_desc | popular | rating` (the code's
+  `options.sort` union). `latest`/`discount` are catalog-config values without a
+  confirmed search-endpoint mapping.
+- Admin lists sort primarily via their filter objects / client-side; there is
+  no shared admin `sort` query-param convention on the wire yet (admin CRUD is
+  mock-only, BACKEND-AUDIT §14).
+
+> **Requires backend decision:** reconcile the catalog-config sort vocabulary
+> (7 values) with the search-endpoint `sort` vocabulary (5 values) — and define
+> the wire encoding for admin list sorting (field + direction) when those
+> endpoints are built.
+
+### 2.4 Standard filtering contract
+
+Filtering shapes already used by the frontend:
+
+- **Storefront search/catalog** — `GET /searchitems` accepts optional
+  `categoryIDs` (comma-joined ints), `minPrice`, `maxPrice`, `tag`, plus `sort`
+  (§2.3). `CatalogConfig.enabledFilters` declares which filter UIs a tenant
+  exposes (`price, availability, rating, brand, category, subcategory, discount,
+  new, color, size, attributes`).
+- **Admin lists** — each domain has a filters object, all following a
+  `{ search: string, <field>: 'all' | <enum>, page, pageSize }` shape. Examples:
+  - `AdminOrderListFilters` = `{ search, status: 'all'|AdminOrderStatus, page,
+    pageSize }`.
+  - `AdminMonitoringEventFilters` = `{ category: 'all'|AdminMonitoringCategory,
+    search }` (note: no page/pageSize on this one).
+  - `MediaListParams` = `{ page?, pageSize?, search?, folder?, tag?, kind?,
+    sort? }`.
+  The convention: a text `search` string plus enum facets where the sentinel
+  **`'all'`** means "no filter on this facet."
+
+> **Requires backend decision:** the wire encoding of these filters as query
+> params for the (not-yet-built) admin endpoints — the shapes above are
+> in-memory facade filter objects, not confirmed query-string contracts. Also
+> whether `'all'` is sent literally or omitted to mean unfiltered.
+
+### 2.5 Standard search contract
+
+- Live full-text search: `GET /searchitems?search=<q>&count=&skip=[&categoryIDs
+  &minPrice&maxPrice&tag&sort]` → `{ items: Item[], total: number }`
+  (`ApiService.searchItems`). The query param is **`search`**.
+- The `SearchFacade` (BACKEND-AUDIT §18) is a **client-side orchestration** over
+  `ProductFacade`/`CategoryFacade` — history, trending, autocomplete, and cache
+  are all localStorage/in-memory. There is **no dedicated search backend
+  endpoint** beyond `/searchitems`; autocomplete/suggestions are derived
+  client-side today.
+
+> **Requires backend decision:** whether server-side autocomplete/suggestion
+> and trending endpoints are wanted (nothing on the wire today), and the
+> min-query-length / debounce contract if so.
+
+### 2.6 Nullable-field convention
+
+The frontend does **not** ascribe distinct semantics to `null` vs `undefined`
+vs an omitted key on the wire — it treats all three as "absent" and applies
+defaults defensively:
+
+- Model interfaces mark optional fields with `?` (implying may be omitted);
+  a handful use explicit `T | null` (e.g. `AuthSession.userId: number | null`,
+  `AuthSession.username: string | null` where `null` specifically means "known
+  to be absent").
+- The tolerant normalizers (`ApiService.normalizeItem/normalizeCategory`,
+  `TelegramSessionApiService.normalizeWebSession`) coalesce `null`/`undefined`/
+  missing uniformly via `??` and default fallbacks — they never branch on
+  `null` vs `undefined`.
+- **Convention to follow:** the backend may omit an optional key or send `null`
+  interchangeably; both are handled. Explicit `null` is only meaningful where a
+  model types the field as `… | null` to signal "definitively no value" (auth
+  user id/username being the notable examples).
+
+### 2.7 JWT / authentication header format
+
+Two coexisting mechanisms; full spec in **`docs/AUTHENTICATION.md`** (this
+section only references it, does not redefine):
+
+- **Telegram session auth (LIVE)** — no `Authorization: Bearer`. Identity is a
+  **`WebSessionID`** header (auth session id, or a persisted anonymous 32-hex id
+  from `localStorage['web_session_id']`) attached to marketplace API requests by
+  `apiHeadersInterceptor`. Admin requests additionally carry an
+  **`AdminWebSessionID`** header (`adminAuthHeadersInterceptor`, gating URL
+  segments `/admin/`, `/backoffice/`, `/builder/`, `/media/`).
+- **Ed25519 admin auth (wired, backend absent)** — issues a JWT
+  `AuthTokenPair { token, refreshToken }`; the intended header is standard
+  `Authorization: Bearer <token>`, but its `authInterceptor` is **not
+  registered** today (AUTHENTICATION.md §2.6), so no request auto-attaches the
+  bearer token yet. `adminAuthHeadersInterceptor` *does* set `Authorization:
+  Bearer <token>` if an admin token happens to be stored, but nothing stores one
+  in the live flow.
+
+Refer to `docs/AUTHENTICATION.md` for token structure (`JwtClaims`), refresh,
+rotation, expiry, role hierarchy, and tenant-scoping open items.
+
+### 2.8 Live endpoint domains (real HTTP, already implemented)
+
+The following domains have **real `HttpClient` calls in code today** (not
+proposals). Documented per-endpoint below. (The Ed25519 admin-auth API is wired
+to real HTTP but the backend does not implement it yet — its full contract is
+in `docs/AUTHENTICATION.md` §2, not repeated here.)
+
+#### 2.8.1 Session auth API (LIVE)
+
+Base: `environment.authApiUrl` (= `https://api.dexarmarket.ru:445`). Source:
+`src/app/services/telegram-session-api.service.ts`. Narrative flow in
+`docs/AUTHENTICATION.md` §1.
+
+| Endpoint | Method | Auth | Body / Headers | Response |
+|---|---|---|---|---|
+| `/users/sessions` | POST | none | body `{ webSessionID }` (client-generated GUID) + header `WebSessionID: <same guid>` | `{ webSessionID, url }` — normalized to `WebSessionStart`; `url` = Telegram deep link |
+| `/users/sessions/{id}` | GET | none | — | Session object, field-tolerant → normalized `AuthSession` |
+| `/users/sessions/{id}` | DELETE | none | header `WebSessionID: <id>` | ignored (frontend clears local state regardless) |
+
+TypeScript interfaces (`src/app/models/auth.model.ts`):
+
+```ts
+export interface AuthSession {
+  sessionId: string;
+  userId: number | null;
+  username: string | null;
+  displayName: string;
+  active: boolean;
+  expires: string; // ISO 8601
+}
+
+export interface WebSessionStart {
+  webSessionID: string;
+  url: string;
+}
+```
+
+Example — create session:
+
+```http
+POST https://api.dexarmarket.ru:445/users/sessions
+WebSessionID: 3f1c2a0e-4e21-4d3a-9e77-1e8f6a2d9c11
+Content-Type: application/json
+
+{ "webSessionID": "3f1c2a0e-4e21-4d3a-9e77-1e8f6a2d9c11" }
+```
+
+```json
+{
+  "webSessionID": "3f1c2a0e-4e21-4d3a-9e77-1e8f6a2d9c11",
+  "url": "https://t.me/myAMLKYCBOT?start=3f1c2a0e-4e21-4d3a-9e77-1e8f6a2d9c11"
+}
+```
+
+Example — poll session (active):
+
+```http
+GET https://api.dexarmarket.ru:445/users/sessions/3f1c2a0e-4e21-4d3a-9e77-1e8f6a2d9c11
+```
+
+```json
+{
+  "webSessionID": "3f1c2a0e-4e21-4d3a-9e77-1e8f6a2d9c11",
+  "status": "active",
+  "user": { "id": 8823771, "username": "buyer_ivan", "firstName": "Ivan", "lastName": "P" },
+  "expiresAt": "2026-07-26T05:00:00Z"
+}
+```
+
+The frontend reads fields **field-tolerantly** (accepts many casings/aliases —
+see `normalizeWebSession`, and `docs/AUTHENTICATION.md` §1.3 for the full alias
+priority lists). A backend should send a real `expiresAt`/`expires` (else the
+frontend fabricates `now + 3600s`).
+
+#### 2.8.2 Marketplace / storefront API (LIVE)
+
+Base: `ApiConfigService.getBaseUrl()` (tenant-resolved; `/api` on localhost,
+else `https://{tenant}.api.dexarmarket.ru:445` / `https://api.dexarmarket.ru:445`).
+Source: `src/app/services/api.service.ts` (`ApiService`). Headers attached by
+`apiHeadersInterceptor`: `X-Region`, `X-Language` (RU/EN/AM), `Currency`
+(default RUB), `WebSessionID`. The primary product wire DTO is `Item`
+(`src/app/models/item.model.ts`), reconciled by the large tolerant
+`normalizeItem()` adapter (BACKEND-AUDIT §7 — treat it as the tolerance
+contract). This domain's full per-endpoint catalog belongs to the CRUD-domain
+section; summarized here as the framework anchor:
+
+| Endpoint | Method | Auth | Params / Body | Response |
+|---|---|---|---|---|
+| `/ping` | GET | session headers | — | `{ message }` |
+| `/category` | GET | session headers | — | `Category[]` (normalized) |
+| `/category/{id}` | GET | session headers | `count`, `skip` | `Item[]` |
+| `/items/{id}` | GET | session headers | — | `Item` |
+| `/searchitems` | GET | session headers | `search`, `count`, `skip`, `categoryIDs?`, `minPrice?`, `maxPrice?`, `tag?`, `sort?` | `{ items: Item[], total: number }` |
+| `/items/randomitems` | GET | session headers | `count`, `category?` | `Item[]` (featured/random) |
+| `/websession/{sessionId}` | POST | session headers | item array | cart echo |
+| `/items/{id}/callback` | POST | session headers | `{ rating, comment, sessionID, timestamp }` | `{ message }` (review) |
+| `/items/{id}/questiion` | POST | session headers | `{ question, sessionID, timestamp }` | `{ message }` (question — **literal typo `questiion` matches backend spec**) |
+| `/purchase-email` | POST | session headers | `{ email, phone?, telegramUserId, items[] }` | `{ message }` |
+
+#### 2.8.3 Cart / order / payment API (LIVE)
+
+Order/cart-payment endpoints on the **marketplace base**; QR/card status on the
+**payment base** `environment.qrApiUrl` (= `https://qr.vitanova.network/api`).
+Source: `src/app/services/api.service.ts`. DTOs are inline in that file.
+
+| Endpoint | Method | Base | Auth | Body | Response |
+|---|---|---|---|---|---|
+| `/cart` | POST | marketplace | session headers | `CartPaymentRequest` | `QrCreateResponse` |
+| `/orders` | POST | marketplace | session headers | `CreateOrderRequest` | `CreateOrderResponse` (fire-and-forget after payment) |
+| `/qr` | POST | `qrApiUrl` | headers `authorization-key`, `userid-value` | `QrCreateRequest` | `QrCreateResponse` |
+| `/qr/dynamic/{partnerId}/{qrId}` | GET | `qrApiUrl` | — | `QrDynamicStatusResponse` |
+| `/card/{partnerId}/{orderId}` | GET | `qrApiUrl` | — | `QrDynamicStatusResponse` |
+
+Const `partnerId` = `web-97ec-9c57-4dde-9037-3a68f7f83750`
+(`ApiService.cartPaymentPartnerId`). Key interfaces (copied from
+`api.service.ts`):
+
+```ts
+export interface CartPaymentRequest {
+  amount: number;
+  currency: 'RUB';
+  siteuserID: string;
+  siteorderID: string;
+  redirectUrl: string;
+  telegramUsername: string;
+  paymentMethod: 'qr' | 'card';
+  qrDescription?: string;
+  customerID?: string;
+  items: Array<{ itemID: number; price: number; name: string; quantity?: number; delivery?: DeliveryOption[] }>;
+}
+
+export interface CreateOrderRequest {
+  items: Array<{ productId: string; name: string; quantity: number; price: number }>;
+  customer: { name: string; email: string; phone: string };
+  payment?: { method: string; currency: string };
+  shipping?: { address: string; method: string; trackingNumber: string };
+}
+
+export interface CreateOrderResponse {
+  id: string;
+  orderNumber: string;
+  status: string;
+  total: number;
+  currency: string;
+}
+
+export interface QrCreateResponse {
+  qrId?: string; qrID?: string; nspkID?: string; nspkId?: string;
+  nspkurl?: string; orderID?: string; url?: string; bankUrl?: string;
+  status?: string; qrStatus?: string; qrExpirationDate?: string; qrTTL?: number;
+  payload?: string; Payload?: string; qrUrl?: string;
+  partnerqrID?: string | number; partnerID?: string | number;
+  partnerId?: string | number; PartnerID?: string | number;
+}
+
+export interface QrDynamicStatusResponse {
+  additionalInfo: string; paymentPurpose: string; amount: number; code: string;
+  createDate: string; currency: string; order: string; status: string;
+  qrId: string; transactionDate: string; transactionId: number; qrExpirationDate: string;
+}
+```
+
+The `QrCreateResponse` is deliberately alias-tolerant (many casings for id /
+url / partner fields) — the frontend resolves the effective id/link via
+`resolvePaymentQrId()` / `resolvePaymentLink()` / `resolveBankPaymentUrl()`. A
+backend can pick one canonical casing; the frontend will still read it.
+
+Example — create cart payment:
+
+```http
+POST https://api.dexarmarket.ru:445/cart
+WebSessionID: 3f1c2a0e-…
+Content-Type: application/json
+
+{
+  "amount": 4990,
+  "currency": "RUB",
+  "siteuserID": "8823771",
+  "siteorderID": "order-2026-0007",
+  "redirectUrl": "https://marketplace.local/checkout/done",
+  "telegramUsername": "buyer_ivan",
+  "paymentMethod": "qr",
+  "items": [{ "itemID": 101, "price": 4990, "name": "Wireless Keyboard", "quantity": 1 }]
+}
+```
+
+```json
+{ "qrId": "QR-77f0", "nspkurl": "https://qr.nspk.ru/AD10…", "status": "created", "qrExpirationDate": "2026-07-26T04:10:00Z" }
+```
+
+#### 2.8.4 Widget manifest (LIVE)
+
+Source: `src/app/widgets/registry/widget-manifest.service.ts`. URL comes from
+`bootstrap.widgetRegistry.manifestUrl`, falling back to
+`/assets/mock/bootstrap/widget-manifest.json`.
+
+| Endpoint | Method | Auth | Response |
+|---|---|---|---|
+| `<bootstrap.widgetRegistry.manifestUrl>` | GET | none | `WidgetManifestFile` |
+
+On any error it falls back to `of({ widgets: [] })` (never throws to the UI).
+Interface (`src/app/widgets/contracts/widget-manifest.contract.ts`):
+
+```ts
+export interface WidgetManifestFile {
+  widgets: WidgetManifestEntry[];
+}
+
+export interface WidgetManifestEntry {
+  type: string;
+  version: string;
+  componentKey: string;
+  supportedLayouts: WidgetLayoutSupport[];   // 'stack'|'grid'|'hero'|'carousel'|'split'
+  supportedDataSources: WidgetDataSourceName[]; // 'featured'|'latest'|'category'|'manual'|'related'|'future'|'root'|'parent'
+  settingsSchema: WidgetSettingsSchema;       // { type: 'object', properties, required? }
+  defaultSettings: Record<string, unknown>;
+  metadataSupport?: WidgetMetadataSupport;
+  enabled?: boolean;
+}
+```
+
+Example response:
+
+```json
+{
+  "widgets": [
+    {
+      "type": "hero",
+      "version": "1.0.0",
+      "componentKey": "HeroWidgetComponent",
+      "supportedLayouts": ["hero"],
+      "supportedDataSources": ["manual"],
+      "settingsSchema": { "type": "object", "properties": { "title": { "type": "string" } } },
+      "defaultSettings": { "title": "Welcome" },
+      "enabled": true
+    }
+  ]
+}
+```
+
+#### 2.8.5 Regions / location (LIVE)
+
+Source: `src/app/services/location.service.ts`.
+
+| Endpoint | Method | Base | Auth | Response |
+|---|---|---|---|---|
+| `/regions` | GET | marketplace | session headers | `Region[]` |
+
+On error, falls back **silently** to 6 hardcoded regions (moscow, spb, yerevan,
+minsk, almaty, tbilisi) — no user-visible error. The selected region's `id`
+feeds the `X-Region` header on subsequent marketplace calls. (An external
+geo-IP call `GET http://ip-api.com/json/...` is used for auto-detect — external,
+not a platform backend.) Interface (`src/app/models/location.model.ts`):
+
+```ts
+export interface Region {
+  id: string;
+  city: string;
+  country: string;
+  countryCode: string;
+  timezone?: string;
+}
+```
+
+Example response:
+
+```json
+[
+  { "id": "moscow", "city": "Москва", "country": "Россия", "countryCode": "RU", "timezone": "Europe/Moscow" },
+  { "id": "yerevan", "city": "Ереван", "country": "Армения", "countryCode": "AM", "timezone": "Asia/Yerevan" }
+]
+```
+
+### 2.9 Consolidated "Requires backend decision" items (this section)
+
+- Bootstrap: `X-Language`/`Accept-Language` handling on `GET /bootstrap` (§1.1).
+- Bootstrap: whether `schemaVersion` is enforced vs presence-only (§1.4).
+- Bootstrap: ETag / conditional-request strategy — none exists today (§1.8).
+- Bootstrap: the entire draft→publish write path + save-time version/concurrency
+  check — no write endpoint exists (§1.10).
+- Bootstrap: dedicated fatal-bootstrap-failure UX vs silent degradation (§1.11).
+- Framework: whether to introduce a success envelope (breaking for all live
+  callers) — none exists today (§2.1).
+- Framework: pagination page-size limits/max; offset vs page-number
+  standardization; cursor vs offset (nothing implies cursors) (§2.2).
+- Framework: reconcile catalog-config sort vocabulary (7) vs search-endpoint
+  `sort` vocabulary (5); wire encoding for admin list sorting (§2.3).
+- Framework: query-string encoding for admin list filters and the `'all'`
+  sentinel (§2.4).
+- Framework: server-side autocomplete/trending search endpoints + min-query
+  contract (§2.5).
+
+---
+
+## 3. CRUD Contracts
+
+Exhaustive per-domain, per-endpoint contract for every backend touch-point the
+Angular frontend expects. Derived from source on branch `B2B` and cross-checked
+against `docs/context/BACKEND-AUDIT.md` (the this-session audit — the ground
+truth for what code actually does), the prior `docs/BACKEND_API.md`, and the two
+sibling specs written this session:
+
+- **Auth / headers / JWT** — see `docs/AUTHENTICATION.md`. This section never
+  re-defines the auth header format; it references it.
+- **Error response envelope + per-status semantics** — see
+  `docs/ERROR_CONTRACT.md`. This section names *which* statuses apply per
+  endpoint and *why*, but the wire shape of the error body is owned by that doc.
+
+### 3.0 Conventions used in this section
+
+**Two API base URLs are in play** (`BACKEND-AUDIT.md` §2):
+
+- **Marketplace / tenant API** — `ApiConfigService.getBaseUrl()`
+  (`src/app/core/config/api-config.service.ts`). Localhost → `/api`; otherwise a
+  per-tenant origin (default `https://api.dexarmarket.ru:445`). Tenant isolation
+  is **by subdomain/base-URL only** — no `X-Tenant` header, no `/tenant/{id}`
+  prefix (`AUTHENTICATION.md` §10). All storefront reads and all admin CRUD go
+  here.
+- **Payment / QR API** — `environment.qrApiUrl` (`https://qr.vitanova.network/api`).
+  Only cart/order payment + status polling (§3.3).
+- **Session-auth API** — `environment.authApiUrl`. Login/session only, covered by
+  `docs/AUTHENTICATION.md`, not repeated here.
+
+**LIVE vs PROPOSED paths.** Only the storefront catalog/cart/engagement reads and
+the single `AdminCategoriesApiGateway` have **literal HTTP paths in code**. Every
+other admin CRUD path below is **PROPOSED** — no URL literal exists anywhere in
+the frontend for it (`BACKEND-AUDIT.md` §24: "No literal `/admin/*`, `/builder/*`,
+or per-admin-domain backoffice CRUD paths exist in code"). The admin gateways are
+in-memory `*LocalGateway` classes that never construct a URL. The proposals here
+follow the **one real precedent** in the codebase — `AdminCategoriesApiGateway`
+(`src/app/features/admin/categories/services/admin-categories-api.gateway.ts`),
+which uses:
+
+```
+GET    {base}/backoffice/categories            ?search&visibility&includeDeleted
+GET    {base}/backoffice/categories/{id}
+POST   {base}/backoffice/categories            (body = category minus server-owned fields)
+PUT    {base}/backoffice/categories/{id}
+DELETE {base}/backoffice/categories/{id}        (soft delete)
+POST   {base}/backoffice/categories/{id}/restore
+GET    {base}/backoffice/categories/slug-taken ?slug&excludingId
+```
+
+All other admin paths below are proposed by analogy to this shape (`{base}/backoffice/<domain>`).
+Builder/config domains (nav, footer, branding, languages, CMS, homepage, widgets)
+are proposed under `{base}/builder/...` because the bootstrap document declares a
+`apiEndpoints.builder` record for exactly this, but **no builder write call exists
+in code today** — the entire builder/CMS surface is LOCAL-ONLY (in-memory
+bootstrap + localStorage drafts), so those endpoints are marked **PROPOSED /
+FUTURE** throughout.
+
+**Headers (all requests).** Marketplace API requests carry `X-Region`,
+`X-Language` (`RU|EN|AM`), `Currency` (default `RUB`), and `WebSessionID`
+(`apiHeadersInterceptor`, `BACKEND-AUDIT.md` §3). Requests whose URL contains
+`/admin/`, `/backoffice/`, `/builder/`, or `/media/` **additionally** get
+`AdminWebSessionID` and, if an admin token is stored, `Authorization: Bearer
+<token>` (`adminAuthHeadersInterceptor`). These header names/values are owned by
+`AUTHENTICATION.md` — assume them on every admin endpoint below unless stated.
+
+**JWT requirement.** No endpoint in the app requires a verified JWT **today**.
+Mechanism A (Telegram session) authenticates admins with an opaque
+`AdminWebSessionID`, not a JWT; the Ed25519 JWT flow (Mechanism B) is fully wired
+but dormant (`AUTHENTICATION.md` §2). For every admin endpoint below, "JWT
+requirement" is therefore stated as: **Today: `AdminWebSessionID` session header
+(Mechanism A). Target: `Authorization: Bearer <Ed25519 JWT>` once Mechanism B is
+cut over.** Server-side authorization must be enforced regardless of any
+client-side guard (`AUTHENTICATION.md` §11.6).
+
+**Required permission / role.** The frontend's only permission model is the
+coarse `ROLE_PERMISSIONS` table (`AUTHENTICATION.md` §9.1): `backoffice.read`,
+`backoffice.write`, `builder.read`, `builder.write`, `users.manage`,
+`settings.manage`. The frontend does **not** enforce per-domain permissions on
+admin CRUD today (the live `adminAuthGuard` only checks "is there an admin
+session at all"). Where a specific permission is the obvious fit it is named as
+**Proposed**; any finer per-role assignment is **Requires backend decision**
+(`AUTHENTICATION.md` §9.1 already flags fine-grained permissions as out of scope).
+
+**Error responses.** Unless a domain-specific note says otherwise, every endpoint
+below can return the envelope from `ERROR_CONTRACT.md` with these statuses:
+`401 UNAUTHENTICATED` (no/expired session), `403 FORBIDDEN` (wrong role/tenant),
+`500 INTERNAL_ERROR`, `503 SERVICE_UNAVAILABLE`/`MAINTENANCE_MODE`. Per-endpoint
+notes below add `404`, `409`, `422`, `429` only where they are meaningful. **The
+frontend does not parse the error body today** (`ERROR_CONTRACT.md` "Finding") —
+admin list pages collapse every non-2xx into one generic "retry" state
+(`ERROR_CONTRACT.md` "Generic list-page error UI"). So all per-status handling
+below is the *contract the backend should honor*, not behavior the current UI
+distinguishes.
+
+**Validation rules.** Admin create/edit forms
+(`admin-product-form.component.ts`, `admin-category-form.component.ts`) use **no
+Angular reactive `Validators`** — confirmed by source search (zero
+`Validators.*` matches). Form state is built by factories
+(`admin-products-form.factory.ts`, `admin-categories-form.factory.ts`) that seed
+empty defaults (e.g. `slug: ''`). Therefore **the frontend enforces essentially
+no field validation** on admin CRUD; every validation rule below beyond "the
+field exists in the model / is non-nullable in TS" is **Requires backend
+decision**. The one real client-side validation convention lives in the builder
+(`ProjectValidator` → `ProjectEditorFacade.fieldError()`), which is client-only
+and localStorage-scoped, not backend-fed.
+
+**Pagination.** The admin list models that paginate use a uniform shape:
+`filters { …, page: number, pageSize: number }` in, `{ items[], total, page,
+pageSize }` out (products, orders, transactions, reviews). Categories, users,
+monitoring, customers, analytics return **plain arrays with no pagination** —
+noted per domain.
+
+---
+
+### 3.1 Products
+
+Two distinct surfaces: **storefront catalog read** (LIVE) and **admin CRUD**
+(MOCK-ONLY, no seam — `BACKEND-AUDIT.md` §14).
+
+#### 3.1.a Storefront catalog read — LIVE
+
+Backed by `ApiService` (`src/app/services/api.service.ts`) via
+`ApiProductDataProvider` → `PRODUCT_DATA_PROVIDER` → `ProductFacade`. The wire
+DTO is `Item` (`src/app/models/item.model.ts`); `ApiService.normalizeItem()` is
+the tolerance contract (the single largest inline mapper — a backend engineer
+should treat it as authoritative for accepted field name variants; see
+`BACKEND-AUDIT.md` §7).
+
+| # | Method | Path (LIVE literal) | Purpose | Success |
+|---|---|---|---|---|
+| P1 | GET | `{base}/items/{itemID}` | Single product | `200` single `Item` (raw wire shape) |
+| P2 | GET | `{base}/category/{categoryID}?count&skip` | Products in a category | `200` `Item[]` |
+| P3 | GET | `{base}/searchitems?search&count&skip[&categoryIDs&minPrice&maxPrice&tag&sort]` | Search | `200` `{ items: Item[], total: number }` |
+| P4 | GET | `{base}/items/randomitems?count[&category]` | Featured/random | `200` `Item[]` |
+
+- **Headers/JWT:** marketplace headers (§3.0). No JWT; anonymous `WebSessionID`
+  is sufficient. Public read.
+- **Query params (P2/P3/P4):** `count` (default 50), `skip` (default 0, offset
+  pagination). P3 search: `search` (string, required), `categoryIDs`
+  (comma-joined numeric ids), `minPrice`, `maxPrice` (numbers), `tag` (string),
+  `sort` ∈ `relevance | price_asc | price_desc | popular | rating`. Signature:
+  `ApiService.searchItems()` lines 551-590.
+- **Pagination/sorting/filtering:** offset-based (`count`/`skip`); sort + price
+  + category + tag filters only on P3. P2 has no sort/filter params. Response P3
+  is the only one returning a `total` for page math.
+- **Error responses:** `404` when `itemID` doesn't exist (P1) — but note the
+  frontend does **not** distinguish 404 from any other error today
+  (`ERROR_CONTRACT.md` §404); a deleted product and a 500 render the same generic
+  empty-state. `500/503` generic. Calls retry x2 with exponential backoff
+  (`ApiService.retryConfig`).
+- **Validation:** none (read).
+- **Example P3 request:** `GET {base}/searchitems?search=phone&count=24&skip=0&categoryIDs=3,7&minPrice=1000&sort=price_asc`
+- **Example P3 response:**
+  ```json
+  { "items": [ { "id": "1024", "name": "Phone X", "price": 62560, "currency": "RUB", "imgs": ["https://…/x.webp"], "remaining": 12 } ], "total": 87 }
+  ```
+
+**`Item` variants/options (part of P1 payload, not separate endpoints).**
+`normalizeItem` accepts `variantOptions[]` (`{ key, label, labels?, options: [{
+value, label?, labels?, available? }] }`) and `specificationGroups[]`. The admin
+side (§3.1.b) models variants as a flat priced list (`AdminProductVariant`). There
+is **no dedicated variants/options CRUD endpoint** — variants are created/updated
+as part of the product create/update body. Flagged: variant shape differs between
+storefront (`variantOptions` grouped) and admin (`variants` flat priced rows) —
+reconciliation is **Requires backend decision** (adapter lives in
+`admin-product-form.factory.ts variantsToBackendRows/variantsFromBackendRows`).
+
+#### 3.1.b Admin products CRUD — PROPOSED (MOCK-ONLY today, no DI seam)
+
+Contract: `AdminProductsGateway`
+(`src/app/features/admin/products/services/admin-products-gateway.interface.ts`).
+Impl today: `AdminProductsLocalGateway` (in-memory + localStorage), injected
+**concretely** by `AdminProductsFacade` — no token, so a backend requires
+introducing a DI seam first (`BACKEND-AUDIT.md` §14, key finding). DTO:
+`AdminProduct` (`src/app/features/admin/products/models/admin-product.model.ts`,
+41-field interface incl. `media`, `variants`, `variantAttributes`, `specifications`,
+`attributes`, `translations`, `seo`, `badges`, flags, `reviews`, `questions`).
+
+| # | Method | Path (PROPOSED) | Gateway method | Success |
+|---|---|---|---|---|
+| AP1 | GET | `{base}/backoffice/products?search&categoryId&visibility&stock&includeArchived&sort&page&pageSize` | `loadProducts(filters)` | `200 AdminProductsListResult` |
+| AP2 | GET | `{base}/backoffice/products/{id}` | `loadProduct(id)` | `200 AdminProduct` / `404` |
+| AP3 | GET | `{base}/backoffice/products/categories` | `loadCategories()` | `200 AdminProductCategoryOption[]` (`{id,title}`) |
+| AP4 | POST | `{base}/backoffice/products` | `createProduct(product)` | `201 AdminProduct` |
+| AP5 | PUT | `{base}/backoffice/products/{id}` | `updateProduct(product)` | `200 AdminProduct` |
+| AP6 | DELETE | `{base}/backoffice/products/{id}` | `deleteProduct(id)` | `204` |
+| AP7 | POST | `{base}/backoffice/products/{id}/duplicate` | `duplicateProduct(id)` | `201 AdminProduct` / `404` |
+| AP8 | POST | `{base}/backoffice/products/{id}/archive` | `archiveProduct(id)` | `204` |
+| AP9 | POST | `{base}/backoffice/products/{id}/restore` | `restoreProduct(id)` | `200 AdminProduct` / `404` |
+
+- **Headers/JWT:** admin auth (§3.0). Today `AdminWebSessionID`; target Bearer JWT.
+- **Permission (Proposed):** read (AP1-AP3) → `backoffice.read`; writes
+  (AP4-AP9) → `backoffice.write`. Finer than that = Requires backend decision.
+- **AP1 query params** (from `AdminProductListFilters`): `search` (string),
+  `categoryId` (string|null), `visibility` ∈ `all|visible|hidden`, `stock` ∈
+  `all|in_stock|low_stock|out_of_stock`, `includeArchived` (bool), `sort` ∈
+  `title|price|priority|stock|updated`, `page` (number), `pageSize` (number).
+  This is the full pagination + sort + filter + search surface — no other
+  sort keys exist. Response `AdminProductsListResult { items, total, page, pageSize }`.
+- **AP4/AP5 request body:** an `AdminProduct`. By the category precedent
+  (`AdminCategoriesApiGateway.createCategory` strips `id, itemsCount, deletedAt,
+  createdAt, updatedAt`), the create body should **omit server-owned fields**
+  (`id`, `createdAt`, `updatedAt`; also `reviews`/`questions` which are derived).
+  Update sends the full object with `id` in the path. **Requires backend
+  decision:** exact server-owned field list for products (the frontend local
+  gateway does not enforce one).
+- **Validation:** none client-side (no `Validators`). Model non-nullable fields
+  (`name`, `slug`, `sku`, `categoryId`, `price`, `currency`, `quantity`) are the
+  only implicit "required" signal. Uniqueness of `slug`/`sku`, price ≥ 0, etc.
+  are all **Requires backend decision** (no `isSlugTaken` equivalent exists for
+  products, unlike categories). Recommended `422 VALIDATION_FAILED` with
+  `details[].field` for `sku`/`slug`/`price`.
+- **Error responses:** `404` (AP2/AP5-AP9 unknown id), `409 CONFLICT`
+  (duplicate slug/sku on AP4/AP5 — Requires backend decision, no proactive
+  pre-check exists), `422` (field validation), plus the common set.
+- **Example AP4 request (trimmed):**
+  ```json
+  { "name": "Phone X", "slug": "phone-x", "sku": "PHN-X-001", "barcode": "", "brand": "Acme", "categoryId": "3", "visible": true, "archived": false, "priority": 0, "price": 62560, "discount": 0, "currency": "RUB", "quantity": 100, "stockStatus": "in_stock", "media": { "images": [], "gallery": [], "videos": [] }, "specifications": [], "attributes": [], "variantAttributes": [], "variants": [], "relatedProductIds": [], "translations": {}, "seo": { "metaTitle": "", "metaDescription": "", "keywords": "" }, "badges": [] }
+  ```
+- **Example AP1 response:**
+  ```json
+  { "items": [ { "id": "p_1024", "name": "Phone X", "slug": "phone-x", "sku": "PHN-X-001", "categoryId": "3", "price": 62560, "currency": "RUB", "quantity": 100, "stockStatus": "in_stock", "visible": true, "archived": false } ], "total": 213, "page": 1, "pageSize": 20 }
+  ```
+
+---
+
+### 3.2 Categories
+
+Three surfaces: storefront read (LIVE, legacy + clean stack), and admin CRUD
+(the **only** admin domain with a real HTTP impl).
+
+#### 3.2.a Storefront category read — LIVE
+
+| # | Method | Path (LIVE literal) | Backed by | Success |
+|---|---|---|---|---|
+| C1 | GET | `{base}/category` | `ApiService.getCategories()` (legacy) and `ApiCategoryRepository` (clean stack, `CATEGORY_REPOSITORY`, retry x2) | `200` array of category wire objects |
+
+- Two parallel stacks read the same endpoint (`BACKEND-AUDIT.md` §8). Legacy
+  wire shape: `Category`/`Subcategory` (`src/app/models/category.model.ts`) via
+  `normalizeCategory()`. Clean wire DTO: `CategoryDto`/`CategoryNameDto`
+  (`src/app/core/categories/dto/category.dto.ts`) via `CategoryMapper`. Both
+  tolerate `names[]` (multi-lang, incl. the `valuue` typo variant), nested
+  `subcategories[]`, `img`↔`icon`, string↔numeric ids.
+- **Headers/JWT:** marketplace headers, no JWT, public.
+- **Response `CategoryDto` fields:** `categoryID?`, `parentID?`, `name?`,
+  `icon?`, `img?`, `priority?`, `visible?`, `categoriesCount?`, `itemCount?`,
+  `names?: [{ language, value|valuue }]`, `subcategories?: CategoryDto[]`.
+- **Error responses:** `500/503` → falls through to empty categories (clean
+  stack retries twice first). No 404 (collection endpoint).
+- **Example response:**
+  ```json
+  [ { "categoryID": 3, "parentID": 0, "name": "Phones", "icon": "https://…/phones.svg", "priority": 10, "visible": true, "itemCount": 213, "names": [ { "language": "RU", "value": "Телефоны" }, { "language": "EN", "value": "Phones" } ], "subcategories": [] } ]
+  ```
+- **Note (`BACKEND-AUDIT.md` §8):** two different `Category` TS types exist —
+  flag for backend/naming reconciliation.
+
+#### 3.2.b Admin categories CRUD — LIVE (real HTTP gateway exists)
+
+Contract: `AdminCategoriesGateway`. **Real impl:** `AdminCategoriesApiGateway`
+(literal paths below — the canonical precedent for all other admin domains).
+Mock impl: `AdminCategoriesLocalGateway`. Bound via `ADMIN_CATEGORIES_GATEWAY`
+token (MOCK-SWAPPABLE — this domain *can* be rebound to the real gateway today).
+DTO: `AdminCategory` (`src/app/features/admin/categories/models/admin-category.model.ts`).
+
+| # | Method | Path (LIVE literal) | Gateway method | Success |
+|---|---|---|---|---|
+| AC1 | GET | `{base}/backoffice/categories?search&visibility&includeDeleted` | `loadCategories(filters)` | `200 AdminCategory[]` |
+| AC2 | GET | `{base}/backoffice/categories/{id}` | `loadCategory(id)` | `200 AdminCategory` / `null` on error |
+| AC3 | POST | `{base}/backoffice/categories` | `createCategory(cat)` | `201 AdminCategory` |
+| AC4 | PUT | `{base}/backoffice/categories/{id}` | `updateCategory(cat)` | `200 AdminCategory` |
+| AC5 | DELETE | `{base}/backoffice/categories/{id}` | `deleteCategory(id)` | `204` (**soft** delete) |
+| AC6 | POST | `{base}/backoffice/categories/{id}/restore` | `restoreCategory(id)` | `200 AdminCategory` / `null` |
+| AC7 | GET | `{base}/backoffice/categories/slug-taken?slug&excludingId` | `isSlugTaken(slug,excludingId)` | `200 { taken: boolean }` |
+
+- **Headers/JWT:** admin auth (§3.0).
+- **Permission (Proposed):** AC1/AC2/AC7 → `backoffice.read`; AC3-AC6 →
+  `backoffice.write`.
+- **AC1 query params** (`AdminCategoryListFilters`): `search` (string),
+  `visibility` ∈ `all|visible|hidden`, `includeDeleted` (bool sent as string).
+  **No pagination** — returns a plain array. No sort param.
+- **AC3 request body:** `AdminCategory` **minus** `id, itemsCount, deletedAt,
+  createdAt, updatedAt` (server-owned — stripped by the real gateway, line 38).
+  AC4 sends the full object, `id` in path.
+- **AC7:** proactive slug-uniqueness pre-check the frontend calls *before*
+  submit (`excludingId` omitted on create, set to the editing id on update). This
+  is the only proactive conflict check in the whole admin surface. On network
+  error it returns `false` (best-effort, TOCTOU-prone — `ERROR_CONTRACT.md` §409).
+- **Validation:** slug uniqueness via AC7; everything else none client-side.
+  `title`, `slug` are non-nullable in the model. Recommended `409 CONFLICT` on
+  AC3/AC4 slug collision as a race backstop (`ERROR_CONTRACT.md` §409), and
+  `422` for field errors.
+- **Error responses:** AC2/AC6 swallow errors → `null` (so a `404` there renders
+  as "not found"/empty, not an error screen). AC5 hard `404` if unknown. `409`
+  slug conflict. Common set otherwise.
+- **Example AC3 request:**
+  ```json
+  { "parentId": null, "title": "Phones", "slug": "phones", "description": "", "icon": "", "imageUrl": "", "imageAlt": "", "order": 0, "visible": true, "status": "published", "translations": {}, "seo": { "metaTitle": "", "metaDescription": "", "keywords": "" }, "attributes": [] }
+  ```
+- **Example AC7 response:** `{ "taken": true }`
+- **Note:** categories have **no hard delete** — only soft delete + restore
+  (gateway doc comment). `deletedAt` timestamps the soft delete.
+
+---
+
+### 3.3 Orders
+
+Two surfaces: **checkout order creation** (LIVE, storefront) and **admin order
+management** (MOCK-ONLY, no seam). These are separate models — the storefront
+`CreateOrderRequest`/`CreateOrderResponse` (inline in `api.service.ts`) is not the
+admin `AdminOrder`.
+
+#### 3.3.a Cart → payment → order creation — LIVE
+
+Cart contents are **LOCAL-ONLY** (`CartService`, localStorage key
+`marketplace_cart` + Telegram CloudStorage — no cart backend). Checkout produces
+these live calls (`BACKEND-AUDIT.md` §10). Payment DTOs are inline in
+`src/app/services/api.service.ts`.
+
+| # | Method | Path | Base | Request → Response |
+|---|---|---|---|---|
+| O1 | POST | `/cart` | marketplace | `CartPaymentRequest` → `QrCreateResponse` (creates the QR/card payment) |
+| O2 | POST | `/qr` | qrApiUrl (headers `authorization-key`, `userid-value`) | `QrCreateRequest` → `QrCreateResponse` |
+| O3 | GET | `/qr/dynamic/{partnerId}/{qrId}` | qrApiUrl | → `QrDynamicStatusResponse` (poll) |
+| O4 | GET | `/card/{partnerId}/{orderId}` | qrApiUrl | → `QrDynamicStatusResponse` (poll) |
+| O5 | POST | `/orders` | marketplace | `CreateOrderRequest` → `CreateOrderResponse` (records paid cart; **fire-and-forget** after payment) |
+| O6 | POST | `/purchase-email` | marketplace | email/phone + items → `{ message }` (receipt) |
+| O7 | POST | `/websession/{sessionId}` | marketplace | item array → any (server-side cart mirror) |
+
+- `partnerId` const = `web-97ec-9c57-4dde-9037-3a68f7f83750`.
+- **Headers/JWT:** marketplace headers (O1/O5/O6/O7); O2-O4 use the payment API
+  with `authorization-key`/`userid-value`. No JWT; customer session via
+  `WebSessionID`.
+- **`CartPaymentRequest` (O1):** `{ amount, currency:'RUB', siteuserID,
+  siteorderID, redirectUrl, telegramUsername, paymentMethod:'qr'|'card',
+  qrDescription?, customerID?, items:[{ itemID, price, name, quantity?,
+  delivery? }] }`.
+- **`CreateOrderRequest` (O5):** `{ items:[{ productId, name, quantity, price }],
+  customer:{ name, email, phone }, payment?:{ method, currency }, shipping?:{
+  address, method, trackingNumber } }`.
+- **`CreateOrderResponse` (O5):** `{ id, orderNumber, status, total, currency }`.
+- **`QrCreateResponse`** is a very tolerant union (`api.service.ts` 21-41) —
+  resolvers pick the first present of `qrId/qrID/nspkID/…`. A backend can emit
+  any of the documented aliases.
+- **Error responses:** O5 is fire-and-forget — a failure must **never** block the
+  payment-confirmed flow (source comment, line 635). `401` on a customer-facing
+  `/cart`/`/orders` has **no unified re-auth UX** today (`ERROR_CONTRACT.md` §401,
+  Requires backend decision). Payment status polling handles its own timeouts.
+- **Validation:** none client-side. Amounts/quantities ≥ 0, valid email/phone =
+  Requires backend decision.
+- **Example O5 request:**
+  ```json
+  { "items": [ { "productId": "1024", "name": "Phone X", "quantity": 1, "price": 62560 } ], "customer": { "name": "Ivan", "email": "ivan@example.com", "phone": "+79990000000" }, "payment": { "method": "qr", "currency": "RUB" } }
+  ```
+- **Example O5 response:** `{ "id": "ord_88", "orderNumber": "R-000088", "status": "pending", "total": 62560, "currency": "RUB" }`
+
+#### 3.3.b Admin orders management — PROPOSED (MOCK-ONLY, no seam)
+
+Contract: `AdminOrdersGateway`. Impl: `AdminOrdersLocalGateway` (injected
+concretely by `AdminOrdersFacade`, and reused by `AdminCustomersFacade` and
+`AdminAnalyticsFacade`). DTO: `AdminOrder`
+(`src/app/features/admin/orders/models/admin-order.model.ts`).
+
+| # | Method | Path (PROPOSED) | Gateway method | Success |
+|---|---|---|---|---|
+| AO1 | GET | `{base}/backoffice/orders?search&status&page&pageSize` | `loadOrders(filters)` | `200 AdminOrdersListResult` |
+| AO2 | GET | `{base}/backoffice/orders/{id}` | `loadOrder(id)` | `200 AdminOrder` / `404` |
+| AO3 | PATCH | `{base}/backoffice/orders/{id}/status` | `updateStatus(id,status)` | `200 AdminOrder` |
+| AO4 | POST | `{base}/backoffice/orders/{id}/refund` | `requestRefund(id)` | `200 AdminOrder` |
+| AO5 | POST | `{base}/backoffice/orders/{id}/notes` | `addNote(id,note,internal)` | `200 AdminOrder` |
+| AO6 | POST | `{base}/backoffice/orders/{id}/archive` | `archiveOrder(id)` | `200 AdminOrder` |
+| AO7 | POST | `{base}/backoffice/orders/{id}/restore` | `restoreOrder(id)` | `200 AdminOrder` |
+| AO8 | DELETE | `{base}/backoffice/orders/{id}` | `deleteOrder(id)` | `204` |
+
+- **Headers/JWT:** admin auth (§3.0).
+- **Permission (Proposed):** AO1/AO2 → `backoffice.read`; AO3-AO8 →
+  `backoffice.write`.
+- **AO1 query params** (`AdminOrderListFilters`): `search`, `status` ∈
+  `all|pending|processing|shipped|delivered|cancelled|refunded`, `page`,
+  `pageSize`. Response `AdminOrdersListResult { items, total, page, pageSize }`.
+  No sort param.
+- **AO3 body:** `{ status: AdminOrderStatus }` where status ∈ the 6-value union
+  above. **State-transition rules** (which transitions are legal, e.g.
+  `delivered → pending`?) are **Requires backend decision** — the frontend
+  enforces none. `payment.status` (`unpaid|paid|refund_requested|refunded`) is a
+  separate axis; AO4 (`requestRefund`) is what moves it to `refund_requested`.
+- **AO5 body:** `{ note: string, internal: boolean }` — `internal:true` writes
+  `internalNotes`, else `notes` (both plain strings on `AdminOrder`). Appends a
+  timeline entry.
+- **`AdminOrder` timeline:** `timeline: [{ status, timestamp, eventKey:
+  'created'|'statusChanged'|'refundRequested' }]` — server should append on each
+  mutation.
+- **Validation:** none client-side. Legal status transitions, refund
+  eligibility = Requires backend decision.
+- **Error responses:** `404` (unknown id), `409` (illegal transition — proposed),
+  common set.
+- **Example AO3 request:** `PATCH …/orders/ord_88/status` body `{ "status": "shipped" }`
+- **Example AO2 response (trimmed):**
+  ```json
+  { "id": "ord_88", "orderNumber": "R-000088", "status": "shipped", "customer": { "name": "Ivan", "email": "ivan@example.com", "phone": "+79990000000" }, "payment": { "method": "qr", "status": "paid", "amount": 62560, "currency": "RUB" }, "shipping": { "address": "…", "method": "courier", "trackingNumber": "TRK1" }, "items": [ { "productId": "1024", "name": "Phone X", "quantity": 1, "price": 62560 } ], "total": 62560, "currency": "RUB", "notes": "", "internalNotes": "", "timeline": [ { "status": "pending", "timestamp": "2026-07-20T10:00:00Z", "eventKey": "created" } ], "archived": false, "createdAt": "2026-07-20T10:00:00Z", "updatedAt": "2026-07-21T09:00:00Z" }
+  ```
+
+---
+
+### 3.4 Customers — PROPOSED (derived, no gateway of its own)
+
+Per `BACKEND-AUDIT.md` §14 and the model comment
+(`src/app/features/admin/customers/models/admin-customer.model.ts`): a customer is
+**not a stored entity** — `AdminCustomersFacade` derives customers by grouping
+`AdminOrder` records by `customer.email` (it injects `AdminOrdersLocalGateway`).
+Every `AdminCustomer` field is a real aggregate over that customer's orders, never
+fabricated.
+
+**Frontend implication:** there is **no customer CRUD in the frontend at all** —
+no create/update/delete, only a derived list/detail. A backend can satisfy this
+either by (a) exposing a real customers endpoint returning the aggregate shape, or
+(b) letting the frontend keep deriving from orders. This is **Requires backend
+decision** (whether customers become a first-class backend resource).
+
+| # | Method | Path (PROPOSED) | Purpose | Success |
+|---|---|---|---|---|
+| CU1 | GET | `{base}/backoffice/customers` | List (derived aggregate) | `200 AdminCustomer[]` |
+| CU2 | GET | `{base}/backoffice/customers/{email}` | Detail (aggregate + orders) | `200 AdminCustomer` / `404` |
+
+- **Key = `email`** (customers are keyed by email, not an id).
+- **`AdminCustomer`:** `{ email, name, phone, orderCount, totalSpent, currency,
+  firstOrderAt, lastOrderAt, addresses[], orders: AdminOrder[] }`.
+- **Headers/JWT:** admin auth (§3.0). Permission (Proposed): `backoffice.read`.
+- **Pagination/sort/filter:** none in the model (plain array). Derivation is
+  entirely client-side today.
+- **Validation:** n/a (read-only, derived).
+- **Error responses:** common read set; `404` if a real customers endpoint is
+  built and the email is unknown.
+- **Example CU1 response (trimmed):**
+  ```json
+  [ { "email": "ivan@example.com", "name": "Ivan", "phone": "+79990000000", "orderCount": 3, "totalSpent": 187680, "currency": "RUB", "firstOrderAt": "2026-01-10T…", "lastOrderAt": "2026-07-20T…", "addresses": ["…"], "orders": [] } ]
+  ```
+
+---
+
+### 3.5 Users — PROPOSED (MOCK-ONLY, no seam)
+
+Contract: `AdminUsersGateway`
+(`src/app/features/admin/users/services/admin-users-gateway.interface.ts`). Impl:
+`AdminUsersLocalGateway` (injected concretely by `AdminUsersFacade`). DTOs in
+`admin-user.model.ts`: `AdminUser`, `AdminRole`, `AdminInvitation`, `AdminSession`,
+`AdminUserAuditEntry`.
+
+| # | Method | Path (PROPOSED) | Gateway method | Success |
+|---|---|---|---|---|
+| U1 | GET | `{base}/backoffice/users` | `loadUsers()` | `200 AdminUser[]` |
+| U2 | GET | `{base}/backoffice/roles` | `loadRoles()` | `200 AdminRole[]` |
+| U3 | GET | `{base}/backoffice/invitations` | `loadInvitations()` | `200 AdminInvitation[]` |
+| U4 | GET | `{base}/backoffice/users/{userId}/sessions` | `loadSessions(userId)` | `200 AdminSession[]` |
+| U5 | GET | `{base}/backoffice/users/{userId}/audit` | `loadAudit(userId)` | `200 AdminUserAuditEntry[]` |
+| U6 | PATCH | `{base}/backoffice/users/{userId}/role` | `setUserRole(userId,roleId)` | `200 AdminUser` |
+| U7 | PATCH | `{base}/backoffice/users/{userId}/status` | `setUserStatus(userId,status)` | `200 AdminUser` |
+| U8 | POST | `{base}/backoffice/invitations` | `inviteUser(email,roleId,scope)` | `201 AdminInvitation` |
+| U9 | DELETE | `{base}/backoffice/invitations/{id}` | `revokeInvitation(id)` | `204` |
+| U10 | DELETE | `{base}/backoffice/sessions/{sessionId}` | `revokeSession(sessionId)` | `204` |
+
+- **Headers/JWT:** admin auth (§3.0).
+- **Permission (Proposed):** all user/role/invitation/session management →
+  `users.manage` (the one permission specifically about this domain — see
+  `AUTHENTICATION.md` §9.1). Read-only U1-U5 could be `backoffice.read` — Requires
+  backend decision.
+- **U6 body:** `{ roleId: string }`. **U7 body:** `{ status: AdminUserStatus }`
+  where status ∈ `active|invited|suspended`. **U8 body:** `{ email, roleId,
+  scope }` where scope ∈ `marketplace|office`.
+- **`AdminRole`** here is `{ id, name, permissions: string[], builtIn: boolean }`
+  — **a different type from the auth `AdminRole` string-union** used by the JWT
+  `role` claim (`Owner|Administrator|Editor|Support|ReadOnly`,
+  `src/app/core/auth/models/permission.model.ts`). **This is the flagged
+  duplicate** (`BACKEND-AUDIT.md` §14, `AUTHENTICATION.md` §9). Reconciliation
+  needed: treat the auth string-union as the JWT/role-claim contract; treat this
+  interface as an admin-users-management row. Recommend renaming the latter (e.g.
+  `AdminUserRoleRecord`). **Requires backend decision / naming reconciliation.**
+- **Roles CRUD:** the gateway exposes only `loadRoles()` (read). There is **no
+  create/update/delete role** endpoint in the frontend — role definitions are
+  read-only from the frontend's perspective. Whether roles are backend-editable =
+  Requires backend decision.
+- **Sessions/audit:** `revokeSession` (U10) exists as a mock method; whether an
+  Owner can remotely kill another admin's live session, and how that propagates to
+  the already-logged-in client, is **Requires backend decision**
+  (`AUTHENTICATION.md` §8 — no push/poll mechanism exists client-side).
+- **Validation:** none client-side. Email format, role existence, self-demotion
+  guards = Requires backend decision.
+- **Error responses:** `404` (unknown user/session/invitation), `409` (e.g.
+  inviting an already-registered email — proposed), `422` (bad email/role),
+  common set.
+- **Example U8 request:** `{ "email": "new.admin@example.com", "roleId": "role_editor", "scope": "office" }`
+- **Example U1 response (trimmed):**
+  ```json
+  [ { "id": "u_1", "name": "Alice", "telegramUsername": "@alice", "email": "alice@example.com", "scope": "office", "roleId": "role_owner", "status": "active", "lastLoginAt": "2026-07-24T…", "createdAt": "2026-01-01T…" } ]
+  ```
+
+---
+
+### 3.6 Roles
+
+Covered structurally under Users (§3.5, endpoint U2 `loadRoles`). Summary of the
+reconciliation the backend must make (this is the audit's flagged item):
+
+- **`AdminRole` #1** — string union `'Owner'|'Administrator'|'Editor'|'Support'
+  |'ReadOnly'` (`src/app/core/auth/models/permission.model.ts`). Used by the JWT
+  `role` claim and `PermissionService`. Ordered high→low by convention only. Maps
+  to permissions via `ROLE_PERMISSIONS` (`AUTHENTICATION.md` §9.1). **This is the
+  role contract for authorization.**
+- **`AdminRole` #2** — interface `{ id, name, permissions: string[], builtIn }`
+  (`src/app/features/admin/users/models/admin-user.model.ts`). A management row for
+  the users screen. `AdminUser.roleId` references `AdminRole.id` here (a
+  string id like `role_owner`), **not** the string-union value.
+- **The two do not reference each other.** A backend role table must decide
+  whether `AdminRole.id` (#2) resolves to one of the five #1 union values (i.e.
+  `builtIn` roles map onto the permission model) and whether custom
+  (`builtIn:false`) roles with arbitrary `permissions[]` are allowed. **Requires
+  backend decision** — the frontend does not resolve this collision.
+- **No role CRUD endpoint** exists in the frontend beyond read (`loadRoles`).
+  Custom-role create/edit/delete = Requires backend decision.
+
+---
+
+### 3.7 Media — PROPOSED (MOCK-SWAPPABLE via abstract-class token)
+
+Contract: abstract class `MediaRepository` (`src/app/core/media/media-repository.ts`).
+Bound in `app.config.ts` → `MockMediaRepository` (`useClass`). MOCK-SWAPPABLE (a
+real impl drops in via the same class token — no new seam needed). DTO:
+`MediaAsset` (`src/app/core/media/models/media-asset.model.ts`).
+
+**Scope note (per task):** this section covers the **CRUD list/delete/metadata**
+endpoints only. Upload *mechanics* (multipart, presigned URLs, chunking) are
+deferred to a sibling "Uploads" section of the master doc — here `upload` is
+listed for completeness but its transport is out of scope.
+
+| # | Method | Path (PROPOSED) | Repository method | Success |
+|---|---|---|---|---|
+| M1 | GET | `{base}/media?page&pageSize&search&folder&tag&kind&sort` | `list(params)` | `200 MediaListResult { items, total }` |
+| M2 | POST | `{base}/media` (multipart — see Uploads section) | `upload(file,options)` | `201 MediaAsset` |
+| M3 | DELETE | `{base}/media/{id}` | `remove(id)` | `204` |
+| M4 | PATCH | `{base}/media/{id}` | `update(id,patch)` | `200 MediaAsset` |
+| M5 | GET | `{base}/media/folders` | `listFolders()` | `200 string[]` |
+
+- **Headers/JWT:** the `adminAuthHeadersInterceptor` already gates `/media/`
+  paths (§3.0, anticipatory) — admin auth applies. Permission (Proposed):
+  `backoffice.read` (M1/M5), `backoffice.write` (M2/M3/M4).
+- **M1 query params** (`MediaListParams`): `page?`, `pageSize?`, `search?`,
+  `folder?`, `tag?`, `kind?` ∈ `image|svg|pdf|other`, `sort?` ∈
+  `recent|name|size`. Response `{ items: MediaAsset[], total }` (offset paginated).
+- **M4 patch body** — restricted to metadata: `Partial<Pick<MediaAsset, 'altText'
+  | 'tags' | 'folder' | 'caption' | 'description' | 'decorative'>>`. The
+  repository signature **forbids** patching `url/filename/mimeType/size/width/
+  height` — a backend should reject those on PATCH.
+- **`MediaAsset`:** `{ id, url, thumbnailUrl?, filename, mimeType, size, width?,
+  height?, altText?: Record<locale,string>, caption?, description?, decorative?,
+  tags?, folder?, createdAt }`.
+- **Validation:** none client-side. Allowed mime types / max size = Requires
+  backend decision (also relevant to the Uploads section).
+- **Error responses:** `404` (M3/M4 unknown id), `422` (invalid patch field),
+  common set. `MediaUsageService` exists client-side to warn on in-use assets —
+  whether delete is blocked when an asset is referenced is Requires backend
+  decision.
+- **Example M4 request:** `PATCH …/media/asset_9` body `{ "altText": { "en": "Product hero", "ru": "…" }, "tags": ["hero"], "decorative": false }`
+- **Example M1 response (trimmed):**
+  ```json
+  { "items": [ { "id": "asset_9", "url": "https://…/hero.webp", "filename": "hero.webp", "mimeType": "image/webp", "size": 48213, "width": 1200, "height": 630, "folder": "products", "createdAt": "2026-07-01T…" } ], "total": 342 }
+  ```
+
+---
+
+### 3.8 CMS — Static pages — PROPOSED / FUTURE (LOCAL-ONLY today)
+
+**Status: LOCAL-ONLY.** `ContentManagementFacade`
+(`src/app/features/content-management/facade/content-management.facade.ts`) →
+`ContentPageService` operates entirely on the **already-loaded
+`BootstrapConfig.staticPages`** — there are **no dedicated CMS backend calls**
+(`BACKEND-AUDIT.md` §16). Editing writes to in-memory bootstrap + localStorage
+drafts; "publishing" = writing bootstrap back, for which **no client HTTP call
+exists**. So every endpoint below is **PROPOSED / FUTURE**.
+
+Backend-shaped model: `StaticPageConfig` / `StaticPagesConfig` /
+`ResolvedStaticPage` (`src/app/shared/models/config/static-page.model.ts`). Editor
+view model: `ContentPage` (`src/app/features/content-management/models/content-page.model.ts`);
+`ContentPageService` is the adapter (`toBootstrapRecord`/`serializePages`).
+
+| # | Method | Path (PROPOSED / FUTURE) | Purpose | Success |
+|---|---|---|---|---|
+| CM1 | GET | `{base}/builder/static-pages` | List pages | `200 StaticPagesConfig` |
+| CM2 | GET | `{base}/builder/static-pages/{id}` | Single page | `200 StaticPageConfig` / `404` |
+| CM3 | POST | `{base}/builder/static-pages` | Create page | `201 StaticPageConfig` |
+| CM4 | PUT | `{base}/builder/static-pages/{id}` | Update page | `200 StaticPageConfig` |
+| CM5 | DELETE | `{base}/builder/static-pages/{id}` | Delete page | `204` |
+
+- **Reality check:** today the frontend gets these pages **inside `GET /bootstrap`**
+  and never calls CM1-CM5. If the backend keeps CMS inside bootstrap, these
+  endpoints may never exist — the alternative is a builder-publish endpoint that
+  writes the whole bootstrap (see §3.15). **Requires backend decision:**
+  per-page CMS endpoints vs. whole-bootstrap publish.
+- **Headers/JWT:** admin/builder auth (§3.0). Permission (Proposed):
+  `builder.read` (CM1/CM2), `builder.write` (CM3-CM5).
+- **`StaticPageConfig` key fields:** `{ id, slug, title: string|Localized,
+  showInFooter?, showInHeader?, showInSitemap?, icon?, order?, requiresAuthentication?,
+  translations?: Record<locale, { title?, html?, seo? }>, html?: string|Localized,
+  seo?: StaticPageSeoConfig, visible?, enabled?, status?: 'draft'|'published',
+  heroImage?, gallery?, updatedAt? }`. Two lifecycle switches: `enabled` (master
+  on/off) and per-page `status` (`draft` never resolves on storefront even if the
+  bootstrap is published).
+- **Validation:** the client-side `ContentPageService.validatePages()` +
+  `ProjectValidator` convention exists (`ProjectValidationIssue { code, message,
+  section, fieldKey, severity }`) and is the shape `ERROR_CONTRACT.md` §422
+  recommends aligning backend `details[]` to. Actual required fields (slug
+  uniqueness, non-empty title) = Requires backend decision.
+- **Error responses:** `404` (CM2/CM4/CM5), `409` (duplicate slug — proposed),
+  `422` (validation), common set. None handled specially by the UI today.
+- **Example CM4 request (trimmed):**
+  ```json
+  { "id": "about", "slug": "about-us", "title": { "en": "About us", "ru": "О нас" }, "showInFooter": true, "status": "published", "enabled": true, "html": { "en": "<h1>About</h1>" }, "seo": { "title": { "en": "About us" }, "robots": "index,follow" } }
+  ```
+
+---
+
+### 3.9 Homepage — PROPOSED / FUTURE (LOCAL-ONLY)
+
+**Status: LOCAL-ONLY** (project-editor, `BACKEND-AUDIT.md` §17). The homepage is a
+**composition of `SectionConfig` → `WidgetConfig`** stored inside
+`BootstrapConfig` (`layout`/`pages`). Edited via `ProjectEditorFacade` +
+`homepage-section.component.ts` / `homepage-overview.component.ts` against
+in-memory bootstrap; persisted only to localStorage drafts. No HTTP save/publish
+call exists.
+
+Models: `SectionConfig` (`src/app/shared/models/config/section.model.ts`) —
+`{ id, type, order, layout?: { strategy: 'stack'|'grid'|'hero'|'carousel'|'split',
+columns?, gap?, align? }, visibility?, widgets: WidgetConfig[], visible? }`.
+
+| # | Method | Path (PROPOSED / FUTURE) | Purpose | Success |
+|---|---|---|---|---|
+| HP1 | GET | `{base}/builder/homepage` | Load section/widget composition | `200 SectionConfig[]` |
+| HP2 | PUT | `{base}/builder/homepage` | Replace composition (reorder, add/remove sections & widgets) | `200 SectionConfig[]` |
+
+- **Why a single PUT, not granular CRUD:** the editor mutates an in-memory tree
+  and saves it whole (undo/redo over `History<BootstrapConfig>`); there is no
+  per-section/per-widget network operation in the frontend. A whole-composition
+  PUT matches how the client actually works. Granular section/widget endpoints
+  would be new backend design. **Requires backend decision.**
+- **Headers/JWT:** builder auth (§3.0). Permission (Proposed): `builder.read`
+  (HP1), `builder.write` (HP2).
+- **Section ordering** is by the numeric `order` field; widgets carry their own
+  `order` within a section.
+- **Validation:** `ProjectValidator` (client-side, localStorage-scoped). Section
+  `type` allow-list, widget `type` must exist in the widget manifest (§3.10) =
+  Requires backend decision.
+- **Error responses:** `422` (invalid section/widget type or malformed tree),
+  common set.
+- **Example HP2 request (trimmed):**
+  ```json
+  [ { "id": "hero", "type": "hero", "order": 0, "layout": { "strategy": "hero" }, "visible": true, "widgets": [ { "id": "w1", "type": "hero-banner", "version": "1.0.0", "order": 0, "props": { "title": "Sale" } } ] } ]
+  ```
+
+---
+
+### 3.10 Widgets — PROPOSED / FUTURE (LOCAL-ONLY) + widget manifest (LIVE)
+
+Two things named "widgets": the **manifest** (LIVE) and the **widget instances**
+inside sections (LOCAL-ONLY, edited via project-editor `widgets-section.component.ts`).
+
+#### 3.10.a Widget manifest — LIVE
+
+`WidgetManifestService` (`src/app/widgets/registry/widget-manifest.service.ts`):
+
+| # | Method | Path (LIVE) | Success |
+|---|---|---|---|
+| W1 | GET | `bootstrap.widgetRegistry.manifestUrl` (fallback `/assets/mock/bootstrap/widget-manifest.json`) | `200 WidgetManifestFile` |
+
+- Read-only registry of available widget types + their settings schema
+  (`WidgetManifestEntry/File`, `WidgetSettingsSchema` — `src/app/widgets/contracts/widget-manifest.contract.ts`).
+- **Headers/JWT:** the manifest URL is bootstrap-driven; public read.
+- **Validation/errors:** on failure falls back to the static asset. No mutation.
+
+#### 3.10.b Widget instances CRUD — PROPOSED / FUTURE
+
+Widget instances (`WidgetConfig`, `src/app/shared/models/config/widget.model.ts`)
+live inside `SectionConfig.widgets[]` and are created/updated/removed/reordered
+purely in-memory via `ProjectEditorFacade` (localStorage drafts). There is **no
+per-widget backend call** — they are saved as part of the homepage composition
+(§3.9 HP2). So there is **no separate widget CRUD endpoint** unless the backend
+chooses granular editing (Requires backend decision). If it does:
+
+| # | Method | Path (PROPOSED / FUTURE) | Purpose |
+|---|---|---|---|
+| W2 | POST | `{base}/builder/sections/{sectionId}/widgets` | Add widget |
+| W3 | PUT | `{base}/builder/sections/{sectionId}/widgets/{widgetId}` | Update widget |
+| W4 | DELETE | `{base}/builder/sections/{sectionId}/widgets/{widgetId}` | Remove widget |
+
+- **`WidgetConfig`:** `{ id, type, version, title?, subtitle?, order?, padding?,
+  visibility?: { desktop?, tablet?, mobile? }, animation?, style?: Record<string,
+  string>, permissions?: { requireAuthenticated?, roles?, permissions? }, props:
+  Record<string, unknown>, actions?, featureFlag?, visible? }`.
+- **Permission (Proposed):** `builder.write`. **Validation:** widget `type` must
+  exist in the manifest (W1); `props` shape validated against
+  `WidgetSettingsSchema`. Both client-side/manifest-driven; backend enforcement =
+  Requires backend decision.
+- **Recommendation:** treat §3.9 HP2 (whole-composition PUT) as canonical and
+  W2-W4 as optional granular sugar the frontend does not need today.
+
+---
+
+### 3.11 Navigation — PROPOSED / FUTURE (LOCAL-ONLY via builder)
+
+**Status: LOCAL-ONLY.** Header/footer nav is `BootstrapConfig.navigation`
+(`src/app/shared/models/config/navigation.model.ts`), edited via
+`ProjectEditorFacade` + `navigation-section.component.ts`. Facade methods
+(all in-memory + localStorage; `project-editor.facade.ts`): `addNavLink`,
+`addStaticPageNavLink`, `removeNavLink`, `updateNavLink`, `updateNavLinkLabel`,
+`reorderNavLink` — all take `target: 'header' | 'footer'`. No HTTP call exists.
+
+Model: `NavigationConfig { header: NavigationItemConfig[], footer:
+NavigationItemConfig[] | FooterNavigationGroupConfig[], sidebar? }`.
+`NavigationItemConfig { id, labelKey?, label?: string|Localized, route?, type?,
+key?, icon?, order?, visible?, visibleWhenFlags?, children? }`.
+
+| # | Method | Path (PROPOSED / FUTURE) | Purpose | Success |
+|---|---|---|---|---|
+| N1 | GET | `{base}/builder/navigation` | Load nav config | `200 NavigationConfig` |
+| N2 | PUT | `{base}/builder/navigation` | Replace nav config (add/remove/update/reorder items) | `200 NavigationConfig` |
+
+- **Whole-config PUT** matches the editor (it mutates the nav tree in memory and
+  saves whole). Granular per-item endpoints = Requires backend decision.
+- **Headers/JWT:** builder auth. Permission (Proposed): `builder.read` (N1),
+  `builder.write` (N2).
+- **Ordering:** `reorderNavLink(target, id, direction: -1|1)` moves an item; the
+  numeric `order` field is authoritative on the wire.
+- **Localized labels:** `updateNavLinkLabel(target, id, value, locale?)` writes
+  into `label` as a `{ [locale]: string }` map.
+- **Validation:** none client-side beyond the builder validator. Route validity,
+  no orphan `children` = Requires backend decision.
+- **Errors:** `422` (malformed tree), common set.
+- **Example N2 request (trimmed):**
+  ```json
+  { "header": [ { "id": "n1", "label": { "en": "Catalog", "ru": "Каталог" }, "route": "/catalog", "order": 0, "visible": true } ], "footer": [] }
+  ```
+
+---
+
+### 3.12 Footer — PROPOSED / FUTURE (LOCAL-ONLY via builder)
+
+**Status: LOCAL-ONLY.** `BootstrapConfig.footer` (`FooterConfig`,
+`src/app/shared/models/config/footer-config.model.ts`), edited via
+`footer-section.component.ts` + `ProjectEditorFacade`. No HTTP call.
+
+`FooterConfig { logoUrl?, paymentIcons?: [{ src, alt, width?, height? }],
+copyrightText?: string|Localized, columns?: [{ id, title, links: [{ id, label,
+pageKey?, url? }] }], socialLinks?: [{ id, label, url, icon? }], legalPageKeys?
+(deprecated), staticPageKeys? (deprecated) }`.
+
+| # | Method | Path (PROPOSED / FUTURE) | Purpose | Success |
+|---|---|---|---|---|
+| F1 | GET | `{base}/builder/footer` | Load footer config | `200 FooterConfig` |
+| F2 | PUT | `{base}/builder/footer` | Replace footer (payment icons, columns/legal links, copyright, socials) | `200 FooterConfig` |
+
+- **Headers/JWT:** builder auth. Permission (Proposed): `builder.read` (F1),
+  `builder.write` (F2).
+- **Link resolution:** `FooterLinkConfig.pageKey` (preferred, references a CMS
+  page id — stays correct if the page route changes) vs. `url` (raw external).
+  `legalPageKeys`/`staticPageKeys` are **deprecated**, superseded by `columns` —
+  a backend should accept them for back-compat but write `columns`.
+- **Validation:** none client-side. Payment-icon URL validity, non-empty column
+  titles = Requires backend decision.
+- **Errors:** `422`, common set.
+- **Example F2 request (trimmed):**
+  ```json
+  { "logoUrl": "https://…/logo.svg", "paymentIcons": [ { "src": "https://…/visa.svg", "alt": "Visa", "width": 40, "height": 24 } ], "copyrightText": { "en": "© 2026 Acme" }, "columns": [ { "id": "legal", "title": "Legal", "links": [ { "id": "l1", "label": "Terms", "pageKey": "terms" } ] } ], "socialLinks": [] }
+  ```
+
+---
+
+### 3.13 Branding / Theme — PROPOSED / FUTURE (LOCAL-ONLY via builder)
+
+**Status: LOCAL-ONLY.** `BootstrapConfig.branding` (`BrandingConfig`,
+`src/app/shared/models/config/branding.model.ts`) and `BootstrapConfig.theme`
+(`theme.model.ts`), edited via `branding-section.component.ts` /
+`theme-section.component.ts` / `brand-overview.component.ts`. No HTTP call.
+
+`BrandingConfig { brandName, legalName, slogan?, logoUrl, logoCompactUrl?,
+faviconUrl, appIconUrl?, socialImageUrl?, galleryUrls?, supportEmail?,
+supportPhone? }`.
+
+| # | Method | Path (PROPOSED / FUTURE) | Purpose | Success |
+|---|---|---|---|---|
+| B1 | GET | `{base}/builder/branding` | Load branding + theme | `200 { branding: BrandingConfig, theme: ThemeConfig }` |
+| B2 | PUT | `{base}/builder/branding` | Update branding | `200 BrandingConfig` |
+| B3 | PUT | `{base}/builder/theme` | Update theme (colors, tokens) | `200 ThemeConfig` |
+
+- **Headers/JWT:** builder auth. Permission (Proposed): `builder.read` (B1),
+  `builder.write` (B2/B3). Could be `settings.manage` if branding is treated as a
+  tenant-settings concern — Requires backend decision.
+- **Theme model** (`src/app/shared/models/config/theme.model.ts`, not re-listed
+  here) carries color tokens; the editor computes contrast client-side
+  (`sections/brand/contrast.util.ts`). Contrast/accessibility is enforced
+  client-side only.
+- **Validation:** none backend-driven. `brandName`, `logoUrl`, `faviconUrl`
+  non-optional in the model; valid email for `supportEmail` = Requires backend
+  decision.
+- **Errors:** `422`, common set.
+- **Example B2 request (trimmed):**
+  ```json
+  { "brandName": "Acme", "legalName": "Acme LLC", "logoUrl": "https://…/logo.svg", "faviconUrl": "https://…/favicon.ico", "supportEmail": "help@acme.com" }
+  ```
+
+---
+
+### 3.14 Languages — PROPOSED / FUTURE (LOCAL-ONLY via builder)
+
+**Status: LOCAL-ONLY.** Locale management is `BootstrapConfig.localization` +
+`BootstrapConfig.tenant.supportedLocales/defaultLocale`, edited via
+`languages-section.component.ts` + `ProjectEditorFacade` methods `addLocale`,
+`removeLocale`, `setDefaultLocale` — all mutate in-memory bootstrap only. No HTTP.
+
+`LocalizationConfig { defaultLocale, supportedLocales: string[], currencyByLocale:
+Record<locale,currency>, dictionaries: [{ locale, dictionaryUrl, version }] }`.
+
+| # | Method | Path (PROPOSED / FUTURE) | Purpose | Success |
+|---|---|---|---|---|
+| L1 | GET | `{base}/builder/languages` | Load locale config | `200 LocalizationConfig` |
+| L2 | POST | `{base}/builder/languages` | Add a supported locale | `201 LocalizationConfig` |
+| L3 | DELETE | `{base}/builder/languages/{code}` | Remove a locale | `200 LocalizationConfig` |
+| L4 | PUT | `{base}/builder/languages/default` | Set default locale | `200 LocalizationConfig` |
+
+- **Headers/JWT:** builder auth. Permission (Proposed): `builder.write` for
+  L2-L4, `builder.read` for L1. Could be `settings.manage` — Requires backend
+  decision.
+- **Client-side rules that a backend should mirror:** locale code is lowercased
+  and trimmed on add; adding an already-present locale is rejected client-side
+  with `builder.languageAlreadyAdded` (so **`409 CONFLICT`** on L2 duplicate is
+  the right backstop). L2 body: `{ code: string }` (a locale like `en`, `ru`,
+  `hy`). L4 body: `{ code: string }` — must be an already-supported locale.
+- **Removing a locale** shows a confirm dialog (destructive: strips that locale's
+  content). Whether removing the *default* locale is allowed = Requires backend
+  decision (the UI lets you set a new default first).
+- **Validation:** non-empty lowercased code; membership check for default. Valid
+  BCP-47 code = Requires backend decision.
+- **Errors:** `409` (duplicate add), `422` (invalid code / removing last locale),
+  common set.
+- **Example L2 request:** `{ "code": "hy" }`
+
+---
+
+### 3.15 Marketplace Settings — PROPOSED / FUTURE
+
+There is **no dedicated "settings" admin gateway or page** beyond the builder
+sections already covered (§3.8-3.14) and `BootstrapConfig`'s remaining sub-configs
+(`featureFlags`, `features`, `seo`, `catalog`, `header`, `layout`,
+`productPage`, `userExperience`, `company`, `apiEndpoints`, `permissions`). All of
+these are **served inside `GET /bootstrap`** and edited (where editable) via the
+project-editor in-memory (LOCAL-ONLY). The only permission that names settings is
+`settings.manage` (Owner-only, `AUTHENTICATION.md` §9.1).
+
+The unifying gap: **there is no client-side "publish/save bootstrap" HTTP call
+anywhere** (`BACKEND-AUDIT.md` §17, §25.5). Everything in §3.8-3.15 is persisted
+only to localStorage drafts + in-memory bootstrap. A real backend needs **one of**:
+
+| # | Method | Path (PROPOSED / FUTURE) | Purpose | Success |
+|---|---|---|---|---|
+| S1 | GET | `{base}/bootstrap` | Load full config (**LIVE** — this one exists) | `200 BootstrapConfig` |
+| S2 | PUT | `{base}/builder/bootstrap` (or `/builder/publish`) | Persist the edited bootstrap (publish) | `200 BootstrapConfig` |
+| S3 | GET | `{base}/builder/settings` | General tenant settings (feature flags, catalog, SEO) | `200` (subset of BootstrapConfig) |
+| S4 | PUT | `{base}/builder/settings` | Update general settings | `200` |
+
+- **S1 is the only LIVE endpoint here** (`ApiBootstrapProvider`, `GET /bootstrap`).
+- **S2 is the single most important FUTURE decision:** a whole-bootstrap publish
+  endpoint vs. the per-section builder endpoints proposed in §3.8-3.14. The
+  frontend has an `apiEndpoints.builder` record slot for exactly this but no code
+  that calls it. **Requires backend decision:** whole-document publish vs.
+  granular section writes (and optimistic-concurrency / versioning via
+  `BootstrapConfig.schemaVersion`/`generatedAt`).
+- **Headers/JWT:** builder/settings auth. Permission (Proposed): `settings.manage`
+  (S2/S4), `builder.read`/`settings` read for S1/S3.
+- **Validation:** `ProjectValidator` runs client-side before a (currently local)
+  publish. Backend-side schema validation of the whole `BootstrapConfig` =
+  Requires backend decision.
+- **Errors:** `422` (invalid config), `409` (concurrent edit — proposed, if
+  versioning adopted), common set.
+
+---
+
+### 3.16 Transactions — PROPOSED (MOCK-ONLY, no seam)
+
+Contract: `AdminTransactionsGateway`
+(`src/app/features/admin/transactions/services/admin-transactions-gateway.interface.ts`).
+Impl: `AdminTransactionsLocalGateway` (injected concretely by
+`AdminTransactionsFacade`). DTO: `AdminTransaction`
+(`src/app/features/admin/transactions/models/admin-transaction.model.ts`).
+
+| # | Method | Path (PROPOSED) | Gateway method | Success |
+|---|---|---|---|---|
+| T1 | GET | `{base}/backoffice/transactions?search&status&type&page&pageSize` | `loadTransactions(filters)` | `200 AdminTransactionsListResult` |
+| T2 | POST | `{base}/backoffice/transactions/{id}/retry` | `retryFailed(id)` | `200 AdminTransaction` |
+| T3 | PATCH | `{base}/backoffice/transactions/{id}/fraud-flag` | `setFraudFlag(id,flagged)` | `200 AdminTransaction` |
+
+- **Headers/JWT:** admin auth (§3.0). Permission (Proposed): `backoffice.read`
+  (T1), `backoffice.write` (T2/T3).
+- **T1 query params** (`AdminTransactionListFilters`): `search`, `status` ∈
+  `all|pending|success|failed|retried`, `type` ∈ `all|payment|refund|qr_payment`,
+  `page`, `pageSize`. Response `AdminTransactionsListResult { items, total, page,
+  pageSize }`. No sort param.
+- **T2:** only meaningful for `status:'failed'` transactions (method name
+  `retryFailed`); a backend should reject retry on non-failed (proposed `409`).
+- **T3 body:** `{ flagged: boolean }`.
+- **`AdminTransaction`:** `{ id, orderId, orderNumber, type, method, status,
+  amount, currency, fraudFlag, audit: [{ action, actor, timestamp }], createdAt,
+  updatedAt }`. Transactions link to orders via `orderId` — how they relate to the
+  live payment records (§3.3.a QR/card) is **Requires backend decision** (the
+  live payment API and the admin transactions model are currently unconnected).
+- **Validation:** none client-side.
+- **Errors:** `404` (unknown id), `409` (retry on non-failed — proposed), common
+  set.
+- **Example T3 request:** `PATCH …/transactions/tx_5/fraud-flag` body `{ "flagged": true }`
+
+---
+
+### 3.17 Reviews — storefront submission (LIVE) + admin moderation (MOCK-ONLY)
+
+#### 3.17.a Storefront review/question submission — LIVE
+
+Via `ApiService` (`ProductDataProvider.submitReview/submitQuestion`). Reviews and
+questions are **read** by deriving them from the `GET /items/{id}` payload — there
+are **no dedicated list endpoints** (`BACKEND-AUDIT.md` §11). Writes:
+
+| # | Method | Path (LIVE literal) | Request | Success |
+|---|---|---|---|---|
+| R1 | POST | `{base}/items/{itemID}/callback` | `{ rating, comment, sessionID, timestamp }` | `200 { message }` |
+| R2 | POST | `{base}/items/{itemID}/questiion` | `{ question, sessionID, timestamp }` | `200 { message }` |
+
+- **Note the literal typo `questiion`** (R2) — matches the backend spec, must be
+  preserved (`api.service.ts` line 617).
+- **Headers/JWT:** marketplace headers; customer `WebSessionID` identifies the
+  reviewer. No JWT.
+- **Models:** `SubmitReviewInput`/`SubmitQuestionInput`
+  (`src/app/core/products/models/product-engagement.model.ts`). `rating` is
+  1-5 stars (`RatingStars`).
+- **Validation:** none client-side. Rating range 1-5, non-empty comment, one
+  review per customer/product = Requires backend decision.
+- **Errors:** `404` (unknown item), `422` (bad rating), `429` (spam throttle —
+  proposed, nothing client-side), common set.
+- **Example R1 request:** `{ "rating": 5, "comment": "Great", "sessionID": "…", "timestamp": "2026-07-25T12:00:00Z" }`
+
+#### 3.17.b Admin review moderation — PROPOSED (MOCK-ONLY, no seam)
+
+Contract: `AdminModerationGateway`
+(`src/app/features/admin/moderation/services/admin-moderation-gateway.interface.ts`).
+Impl: `AdminModerationLocalGateway` (injected concretely by
+`AdminModerationFacade`; reused by `AdminAnalyticsFacade`). DTO: `AdminReview`
+(`src/app/features/admin/moderation/models/admin-review.model.ts`).
+
+| # | Method | Path (PROPOSED) | Gateway method | Success |
+|---|---|---|---|---|
+| MR1 | GET | `{base}/backoffice/moderation/reviews?search&status&rating&page&pageSize` | `loadReviews(filters)` | `200 AdminReviewsListResult` |
+| MR2 | GET | `{base}/backoffice/moderation/reviews/{id}` | `loadReview(id)` | `200 AdminReview` / `404` |
+| MR3 | PATCH | `{base}/backoffice/moderation/reviews/{id}/status` | `setReviewStatus(id,status,note)` | `200 AdminReview` |
+| MR4 | PATCH | `{base}/backoffice/moderation/reviews/{id}/visible` | `setReviewVisible(id,visible)` | `200 AdminReview` |
+| MR5 | PATCH | `{base}/backoffice/moderation/reviews/{id}/pinned` | `setReviewPinned(id,pinned)` | `200 AdminReview` |
+| MR6 | PATCH | `{base}/backoffice/moderation/reviews/{id}/featured` | `setReviewFeatured(id,featured)` | `200 AdminReview` |
+| MR7 | POST | `{base}/backoffice/moderation/reviews/{id}/notes` | `addModeratorNote(id,note)` | `200 AdminReview` |
+| MR8 | DELETE | `{base}/backoffice/moderation/reviews/{id}` | `deleteReview(id)` | `204` |
+
+- **Headers/JWT:** admin auth (§3.0). Permission (Proposed): `backoffice.read`
+  (MR1/MR2), `backoffice.write` (MR3-MR8).
+- **MR1 query params** (`AdminReviewListFilters`): `search`, `status` ∈
+  `all|pending|approved|rejected|spam`, `rating` ∈ `all` or a number 1-5, `page`,
+  `pageSize`. Response `AdminReviewsListResult { items, total, page, pageSize }`.
+- **MR3 (approve/reject) body:** `{ status: AdminReviewStatus, note: string }`
+  where status ∈ `pending|approved|rejected|spam`. This is the approve/reject
+  action — approving = `status:'approved'`, rejecting = `'rejected'`, marking spam
+  = `'spam'`. The `note` is a moderator reason, appended to the review timeline.
+- **`AdminReview`:** `{ id, productId, productName, customerName, customerEmail,
+  rating, text, photos[], status, visible, pinned, featured, reportCount,
+  moderatorNotes, timeline: [{ eventKey: 'submitted'|'statusChanged'|'restored'|
+  'hidden', actor: 'admin'|'customer', status?, note, timestamp }], createdAt,
+  updatedAt }`. Server appends timeline entries on each mutation.
+- **Relation to storefront reviews (§3.17.a):** the admin `AdminReview` and the
+  storefront `Review` (`product-engagement.model.ts`) are different types over the
+  same underlying data. How a `POST /items/{id}/callback` submission surfaces in
+  the moderation queue = Requires backend decision (they are unconnected today).
+- **Validation:** none client-side.
+- **Errors:** `404` (unknown id), common set.
+- **Example MR3 request:** `{ "status": "approved", "note": "Looks legit" }`
+
+---
+
+### 3.18 Reports — PROPOSED (MOCK-ONLY, no seam)
+
+Part of `AdminModerationGateway` (same gateway/facade as reviews §3.17.b). DTO:
+`AdminReport` (`src/app/features/admin/moderation/models/admin-report.model.ts`).
+
+| # | Method | Path (PROPOSED) | Gateway method | Success |
+|---|---|---|---|---|
+| RP1 | GET | `{base}/backoffice/moderation/reports` | `loadReports()` | `200 AdminReport[]` |
+| RP2 | PATCH | `{base}/backoffice/moderation/reports/{id}/status` | `setReportStatus(id,status)` | `200 AdminReport` |
+
+- **Headers/JWT:** admin auth (§3.0). Permission (Proposed): `backoffice.read`
+  (RP1), `backoffice.write` (RP2).
+- **RP1:** returns a **plain array, no pagination/filter params** (`loadReports()`
+  takes no arguments).
+- **RP2 body:** `{ status: AdminReportStatus }` where status ∈
+  `open|resolved|dismissed`.
+- **`AdminReport`:** `{ id, targetType: 'product'|'review'|'customer'|'category'
+  |'unknown', targetId, targetLabel, reason, reporterEmail, status, createdAt }`.
+  A report points at another entity via `targetType`+`targetId`.
+- **No report *creation* endpoint in the frontend** — reports are read + status
+  changed only. Who/what creates reports (customer-facing "report this" flow) =
+  Requires backend decision (no such storefront submission exists in code).
+- **Validation:** none client-side. **Errors:** `404` (RP2 unknown id), common set.
+- **Example RP2 request:** `{ "status": "resolved" }`
+
+---
+
+### 3.19 Monitoring — PROPOSED, READ-ONLY (MOCK-ONLY, no seam)
+
+Contract: `AdminMonitoringGateway`
+(`src/app/features/admin/monitoring/services/admin-monitoring-gateway.interface.ts`).
+Impl: `AdminMonitoringLocalGateway` (injected concretely by
+`AdminMonitoringFacade`). **Read-only** — the gateway has no mutation methods
+(`BACKEND-AUDIT.md` §14). DTOs in `admin-monitoring.model.ts`.
+
+| # | Method | Path (PROPOSED) | Gateway method | Success |
+|---|---|---|---|---|
+| MO1 | GET | `{base}/backoffice/monitoring/events?category&search` | `loadEvents(filters)` | `200 AdminMonitoringEvent[]` |
+| MO2 | GET | `{base}/backoffice/monitoring/queues` | `loadQueues()` | `200 AdminQueue[]` |
+| MO3 | GET | `{base}/backoffice/monitoring/webhooks` | `loadWebhooks()` | `200 AdminWebhookDelivery[]` |
+
+- **Headers/JWT:** admin auth (§3.0). Permission (Proposed): `backoffice.read`.
+- **MO1 query params** (`AdminMonitoringEventFilters`): `category` ∈
+  `all|audit|security|login|failed_login|api|error|warning`, `search`. **No
+  pagination** (plain array) — a backend feeding a real event stream would likely
+  need to add paging/time-range params; **Requires backend decision** on
+  windowing.
+- **Models:** `AdminMonitoringEvent { id, category, level: 'info'|'warning'
+  |'error', message, technicalDetail?, actor, timestamp }`; `AdminQueue { name,
+  depth, status: 'healthy'|'degraded'|'down' }`; `AdminWebhookDelivery { id,
+  endpoint, event, status: 'delivered'|'failed'|'pending', timestamp }`.
+- **Webhooks here are read-only observability** (delivery log), **not** webhook
+  configuration CRUD — there is no create/update/delete webhook endpoint in the
+  frontend. Webhook *management* = Requires backend decision (out of current scope).
+- **Validation/errors:** read-only; common read error set.
+- **Example MO2 response:** `[ { "name": "orders", "depth": 3, "status": "healthy" } ]`
+
+---
+
+### 3.20 Analytics — PROPOSED, DERIVED / NO REAL DATA SOURCE (MOCK-ONLY)
+
+Per `BACKEND-AUDIT.md` §14: `AdminAnalyticsFacade` has **no gateway of its own** —
+it derives everything by reusing orders/products/moderation local gateways +
+`ADMIN_CATEGORIES_GATEWAY` + `AdminDashboardFacade`. Several analytics values are
+**honestly `null` because no data source exists** (e.g. `conversionRate`,
+`retentionPercent` — model comments: "null = unknown - no visitor/traffic tracking
+exists yet. Never fabricated"). DTOs in `admin-analytics.model.ts`.
+
+| # | Method | Path (PROPOSED) | Purpose | Success |
+|---|---|---|---|---|
+| AN1 | GET | `{base}/backoffice/analytics/summary?range` | KPI summary | `200 AdminAnalyticsSummary` |
+| AN2 | GET | `{base}/backoffice/analytics/products?range` | Product analytics | `200 AdminProductAnalytics` |
+| AN3 | GET | `{base}/backoffice/analytics/customers?range` | Customer analytics | `200 AdminCustomerAnalytics` |
+| AN4 | GET | `{base}/backoffice/analytics/series?range&metric` | Time series | `200 AdminAnalyticsSeriesPoint[]` |
+
+- **Headers/JWT:** admin auth (§3.0). Permission (Proposed): `backoffice.read`.
+- **`range` query param** ∈ `7 | 30 | 90` (`AdminAnalyticsDateRange`) — the only
+  filter the frontend models.
+- **`AdminAnalyticsSummary`:** `{ revenueTotal, currency, ordersCount,
+  avgOrderValue, productsCount, categoriesCount, customersCount, conversionRate:
+  number | null }`. **`conversionRate` MUST be `null` when unknown** — a backend
+  must not fabricate it absent real visitor/traffic tracking. Same for
+  `AdminCustomerAnalytics.retentionPercent`.
+- **What has no backend data source at all (mark accordingly):** conversion rate,
+  retention, and anything needing visitor/traffic/pageview data — there is **no
+  traffic analytics ingestion anywhere in the frontend**. Building real analytics
+  (beyond order/product aggregates) is **Requires backend decision** end to end.
+- **Validation/errors:** read-only; common read set. A backend that can't compute
+  a metric should return `null`, not omit or fake it.
+- **Example AN1 response:**
+  ```json
+  { "revenueTotal": 4820000, "currency": "RUB", "ordersCount": 213, "avgOrderValue": 22629, "productsCount": 512, "categoriesCount": 24, "customersCount": 178, "conversionRate": null }
+  ```
+
+**Dashboard metrics (adjacent).** `AdminDashboardMetricsGateway.loadMetrics()`
+(`ADMIN_DASHBOARD_METRICS_GATEWAY`, MOCK-SWAPPABLE token) returns
+`AdminDashboardMetrics { categoriesCount, productsCount }` — the one other
+token-bound admin gateway. Proposed: `GET {base}/backoffice/dashboard/metrics` →
+`200 { categoriesCount, productsCount }`, permission `backoffice.read`.
+
+---
+
+### 3.21 Cross-cutting "Requires backend decision" register (this section)
+
+Consolidated so the master doc can dedupe against the auth/error registers:
+
+1. **DI seam prerequisite** — orders, products, users, transactions, monitoring,
+   moderation (+ derived customers/analytics) inject their `*LocalGateway`
+   concretely; a backend requires introducing a DI token first (`BACKEND-AUDIT.md`
+   §14). Only categories + dashboard-metrics are token-bound today.
+2. **All admin CRUD paths are PROPOSED** — only `/backoffice/categories*` and the
+   storefront catalog/cart/engagement paths are literal. Adopt the
+   `/backoffice/<domain>` convention (or reject it).
+3. **Server-owned field lists** on create/update for products/orders/etc. (only
+   categories defines one, by stripping `id/itemsCount/deletedAt/createdAt/updatedAt`).
+4. **Field validation + error wording** — the frontend enforces essentially none
+   on admin CRUD (no reactive `Validators`); all `422` field rules and messages are
+   backend-owned.
+5. **Product slug/sku uniqueness** — no proactive check exists (unlike categories'
+   `isSlugTaken`); decide `409` behavior.
+6. **Order status-transition legality** and refund eligibility rules.
+7. **Customers as a first-class resource** vs. derived-from-orders aggregate.
+8. **`AdminRole` duplication** — auth string-union vs. users-management interface
+   (naming reconciliation; role CRUD / custom roles).
+9. **Remote session revocation propagation** (`revokeSession`) to a logged-in
+   client (`AUTHENTICATION.md` §8 — no push/poll exists).
+10. **Media**: allowed mime/size; whether in-use assets are delete-blocked.
+11. **CMS/homepage/widgets/nav/footer/branding/languages/settings are LOCAL-ONLY**
+    — the single biggest decision is **whole-bootstrap publish (S2) vs. granular
+    builder endpoints** (§3.15). No builder write call exists in code today.
+12. **Languages**: duplicate-add `409`, removing the default/last locale, BCP-47
+    validation.
+13. **Transactions ↔ live payment records** are unconnected models; how they link.
+14. **Reviews**: storefront `Review` vs. admin `AdminReview` linkage; how a
+    submitted review enters the moderation queue.
+15. **Reports**: no creation flow exists — who creates reports.
+16. **Monitoring**: event windowing/pagination for a real stream; webhook
+    *management* (vs. read-only delivery log) is out of scope.
+17. **Analytics**: `conversionRate`/`retentionPercent` must stay `null` when
+    unknown; no traffic/visitor data source exists anywhere — real analytics is a
+    from-scratch backend build.
+18. **Variants/options** shape reconciliation between storefront `variantOptions`
+    (grouped) and admin `variants` (flat priced rows); no dedicated variants
+    endpoint (created within the product body).
+
+---
+
+_All paths repo-relative to `F:\dx\remote\marketplaces\`. Storefront/category
+literals and the `AdminCategoriesApiGateway` paths are verified in source; every
+other endpoint is PROPOSED per the conventions in §3.0._
+
+---
+
+## 4. Authentication
+
+Standalone, backend-implementable authentication contract for the marketplace
+platform (Angular frontend, branch `B2B`). Derived directly from source —
+`src/app/core/auth/**`, `src/app/core/admin-auth/**`,
+`src/app/services/{auth,telegram-session-api}.service.ts`,
+`src/app/components/telegram-login/**`, `src/app/guards/language.guard.ts`,
+`src/app/app.routes.ts`, `src/app/app.config.ts`,
+`src/app/core/config/tenant-resolver.service.ts` — plus
+`docs/context/BACKEND-AUDIT.md` (this-session audit) and the prior
+`docs/AUTH.md`. Where the frontend does not already imply a behavior, this
+document says **"Requires backend decision"** rather than inventing one.
+
+Two authentication mechanisms coexist in the codebase today, at different
+maturity levels:
+
+| Mechanism | Used by | Status |
+|---|---|---|
+| Telegram QR / deep-link session auth | Storefront customers **and** admin/backoffice (same API) | **LIVE** — real endpoints, in production use |
+| Ed25519 challenge/response admin auth | Admin/backoffice (intended replacement) | **Frontend fully wired, backend endpoints do not exist yet** (404s today) |
+
+Both are documented in full below. Nothing here should be read as "the
+platform has JWTs today" — it does not, except inside the not-yet-live
+Ed25519 flow.
+
+---
+
+### Table of contents
+
+1. [Mechanism A — Telegram QR / session login (LIVE)](#1-mechanism-a--telegram-qr--session-login-live)
+2. [Mechanism B — Ed25519 challenge/response admin auth (NOT LIVE)](#2-mechanism-b--ed25519-challengeresponse-admin-auth-not-live)
+3. [JWT structure](#3-jwt-structure)
+4. [Refresh token](#4-refresh-token)
+5. [Token expiration handling](#5-token-expiration-handling)
+6. [Token rotation](#6-token-rotation)
+7. [Logout](#7-logout)
+8. [Session invalidation](#8-session-invalidation)
+9. [Role hierarchy](#9-role-hierarchy)
+10. [Tenant isolation](#10-tenant-isolation)
+11. [Permission model / route guards](#11-permission-model--route-guards)
+12. [Open items — "Requires backend decision"](#12-open-items--requires-backend-decision)
+
+---
+
+### 1. Mechanism A — Telegram QR / session login (LIVE)
+
+Single source for **both** customer and admin login:
+`TelegramSessionApiService` (`src/app/services/telegram-session-api.service.ts`).
+There is no separate admin backend endpoint — the same three calls back the
+customer `AuthService` (`src/app/services/auth.service.ts`) and the admin
+`AdminAuthService` (`src/app/core/admin-auth/admin-auth.service.ts`). Only the
+**storage** differs (cookie name, in-memory signal), so an admin QR scan
+never authenticates the customer session or vice versa.
+
+#### 1.1 Endpoints (base = `environment.authApiUrl`, e.g. `https://api.dexarmarket.ru:445`)
+
+| Method | Path | Request | Response |
+|---|---|---|---|
+| POST | `/users/sessions` | body `{ webSessionID }` (client-generated GUID), header `WebSessionID: <same guid>` | `{ webSessionID, url }` — `url` is the Telegram bot deep link |
+| GET | `/users/sessions/{id}` | — | Session object, heavily field-tolerant (see §1.3) |
+| DELETE | `/users/sessions/{id}` | header `WebSessionID: <id>` | ignored/discarded |
+
+#### 1.2 Frontend-driven flow
+
+The frontend, not the backend, generates the session id. Sequence:
+
+1. User opens login (storefront "Sign in" or admin `/admin-login` gate).
+2. Frontend generates a random GUID client-side (`generateGuid()`,
+   `src/app/shared/util/guid.util.ts`) — this **is** the `webSessionID`, sent
+   to the backend, not received from it.
+3. `POST {authApiUrl}/users/sessions` with `{ webSessionID }` body and
+   `WebSessionID` header set to the same value. Backend response's own id
+   field is preferred if present (see `extractSessionId` — checks
+   `webSessionID/WebSessionID/webSessionId/sessionID/SessionID/sessionId/id/ID`
+   in that order), else the frontend's generated GUID is used as fallback.
+4. Frontend builds two login links from the returned id:
+   - Web: `https://t.me/{bot}?start={webSessionID}` (`getBotLoginUrl`)
+   - App deep link: `tg://resolve?domain={bot}&start={webSessionID}`
+     (`getBotAppLoginUrl`)
+   - `bot` = `environment.telegramBot` (`'myAMLKYCBOT'` in current env config;
+     code fallback `'DexarSupport_bot'` if the env key is absent).
+5. Frontend renders both as a QR code (external image generator
+   `https://api.qrserver.com/v1/create-qr-code/...` — not a backend of this
+   platform, purely a QR bitmap renderer for the `url`) plus the app deep
+   link for mobile. This is orchestrated by `QrLoginEngine`
+   (`src/app/shared/qr-login/qr-login.engine.ts`) shared identically by both
+   customer and admin modes via `TelegramLoginComponent`
+   (`src/app/components/telegram-login/telegram-login.component.ts`,
+   `[mode]="'customer' | 'admin'"`).
+6. User scans the QR (or taps the deep link on mobile) and completes the
+   Telegram bot interaction out-of-band. The **backend** is expected to mark
+   that `webSessionID` as active/logged-in once the Telegram bot confirms the
+   user, associating a Telegram user identity with it.
+7. Frontend polls `GET /users/sessions/{id}` (`checkSessionOnce`, driven by
+   `QrLoginEngine`'s polling loop) until the session normalizes to `active:
+   true`, or the user cancels/times out.
+8. On an active session, the frontend calls `activateSession()` internally
+   (sets in-memory signal, stores the id per §1.4, schedules a re-check —
+   see §5) and redirects: customer → wherever the login was triggered from;
+   admin → `/{lang}/backoffice/dashboard` (hardcoded in
+   `telegram-login.component.ts`).
+
+#### 1.3 Session response normalization (backend field tolerance)
+
+`TelegramSessionApiService.normalizeWebSession()` is deliberately
+tolerant of multiple backend field-naming conventions (evidence the backend
+contract was never fully pinned down). A backend implementation can emit any
+of these; the frontend reads the **first key found** in this priority order:
+
+- **Active/status**: `status`, `Status`, `active`, `Active`, `loggedIn`,
+  `LoggedIn`, `isLoggedIn`, `IsLoggedIn`, `authenticated`, `Authenticated`.
+  Value is considered "active" if boolean `true`/`1`, or (case-insensitive)
+  one of `true, 1, active, authenticated, confirmed, success, logged_in`.
+- **User object**: nested under `user`/`User`/`telegramUser`/`TelegramUser`,
+  else the top-level response object itself is used as the user record.
+- **Username**: `username`/`Username` (user object first, then top-level).
+- **First/last name**: `firstName`/`first_name`/`FirstName`/`First_name`,
+  `lastName`/`last_name`/`LastName`/`Last_name` — joined with a space if both
+  present.
+- **Display name**: explicit `displayName`/`DisplayName`/`name`/`Name` (user
+  object or top-level) wins; else falls back to `username`; else falls back
+  to the joined full name; else literal `'Telegram User'`.
+- **Telegram user id**: `userId`/`telegramUserId`/`telegramUserID`/
+  `TelegramUserID`/`id`/`ID` (user object), else `userId`/`telegramUserId`/
+  `telegramUserID`/`TelegramUserID`/`userID`/`UserID`/`UserId` (top-level).
+- **Session id**: same priority list as `extractSessionId` above.
+- **Expiry**: `expiresAt`/`ExpiresAt`/`expires`/`Expires` (ISO 8601 string);
+  if absent, the frontend fabricates `now + 3600s` client-side — **the
+  backend should always send a real `expiresAt`/`expires`** so the frontend's
+  refresh-scheduling (§5) reflects the true session lifetime rather than a
+  guessed one.
+
+Normalized shape consumed by the frontend (`AuthSession`,
+`src/app/models/auth.model.ts`):
+
+```ts
+interface AuthSession {
+  sessionId: string;
+  userId: number | null;
+  username: string | null;
+  displayName: string;
+  active: boolean;
+  expires: string; // ISO 8601
+}
+```
+
+#### 1.4 Storage (customer vs admin — kept fully separate)
+
+| | Customer (`AuthService`) | Admin (`AdminAuthService`) |
+|---|---|---|
+| Cookie name | `webSessionID` | `adminSessionID` |
+| Cookie attrs | `Max-Age=3600; Path=/; SameSite=Lax` (+`Secure` over HTTPS) | `Max-Age=3600; Path=/; SameSite=Strict` (+`Secure` over HTTPS) |
+| In-memory state | `sessionSignal`, `statusSignal` (`unknown\|checking\|authenticated\|expired\|unauthenticated`) | Same shape, separate signals |
+| Extra storage | — | Reserved JWT-pair slots `localStorage['adminToken']` / `localStorage['adminRefreshToken']` — **unused today**, see §12 |
+
+Both send a `WebSessionID` header on every marketplace API request via
+`apiHeadersInterceptor` (see `docs/context/BACKEND-AUDIT.md` §3) — this is
+the anonymous-or-authenticated session identity the backend correlates
+requests against; there is no `Authorization: Bearer` header in this
+mechanism.
+
+#### 1.5 Session re-check / soft refresh (not a token refresh)
+
+Both `AuthService` and `AdminAuthService` self-schedule a re-check of
+`GET /users/sessions/{id}` 60 seconds before `expires`, minimum 30s out
+(`scheduleSessionRefresh`). This is **not** a refresh-token exchange — it
+just re-polls the same session-status endpoint and re-activates if still
+active, or clears local state if not. There is no rotation of the
+`webSessionID` itself in this mechanism.
+
+#### 1.6 Admin dev bypass (non-production only)
+
+`AdminAuthService.devBypassLogin()` fabricates a local session
+(`sessionId: 'dev-bypass-{timestamp}'`, `active: true`, 1-hour expiry) and
+activates it directly, skipping the QR flow entirely. Guarded by
+`environment.production` at runtime (not just build-time) — the checked
+condition is inside the function body, so it is dead code in a production
+build.
+
+#### 1.7 Sequence diagram — storefront/admin Telegram-QR login
+
+```mermaid
+sequenceDiagram
+    participant User as User (browser)
+    participant FE as Frontend (AuthService / AdminAuthService)
+    participant BE as Backend (authApiUrl)
+    participant TG as Telegram bot
+
+    User->>FE: Open login (customer checkout, or /admin-login gate)
+    FE->>FE: generate webSessionID (client GUID)
+    FE->>BE: POST /users/sessions { webSessionID } (header WebSessionID)
+    BE-->>FE: 200 { webSessionID, ... }
+    FE->>FE: build QR + tg:// deep link from webSessionID
+    FE-->>User: render QR code / "Open in Telegram" button
+    User->>TG: scan QR / tap deep link, confirm in bot
+    TG->>BE: (out of band) associate webSessionID with Telegram user
+    loop poll every N seconds
+        FE->>BE: GET /users/sessions/{webSessionID}
+        BE-->>FE: session (active:false while pending)
+    end
+    BE-->>FE: session (active:true, user fields, expires)
+    FE->>FE: activateSession(): store cookie, set signals,<br/>schedule re-check at expires-60s
+    alt mode = admin
+        FE-->>User: redirect to /{lang}/backoffice/dashboard
+    else mode = customer
+        FE-->>User: close dialog, resume prior action (e.g. checkout)
+    end
+```
+
+---
+
+### 2. Mechanism B — Ed25519 challenge/response admin auth (NOT LIVE)
+
+**Status: frontend fully implemented and wired to real `HttpClient` calls;
+the backend does not implement these endpoints yet — calls 404/error today.**
+No route currently requires this flow (`ed25519AuthGuard` is not referenced
+by any route in `app.routes.ts`; the live admin gate is still
+`adminAuthGuard` / Telegram QR, §1). This is the target contract for closing
+the security gap in §1: today the Telegram session API has no concept of
+"admin," so the backend cannot distinguish an admin login attempt from a
+customer one at the moment of login. Ed25519 closes that by requiring proof
+of possession of a specific, pre-registered private key before any session
+is issued.
+
+#### 2.1 Key generation (device-local, once per device)
+
+`Ed25519KeypairService` (`src/app/core/auth/services/ed25519-keypair.service.ts`):
+
+- `getOrCreateKeyPair()`: generates a **non-extractable** Ed25519 keypair via
+  `crypto.subtle.generateKey({ name: 'Ed25519' }, false, ['sign', 'verify'])`
+  (real WebCrypto Ed25519 — RFC 8032, not a placeholder), persists the raw
+  `CryptoKey` handles in IndexedDB (`admin-auth-ed25519` DB, object store
+  `keypair`, single record `id: 'device-keypair'`).
+- The private key is never exported, serialized, or transmitted — by
+  construction (`extractable: false`), not by convention or policy.
+- `sign(message)`: signs a UTF-8-encoded string with `crypto.subtle.sign
+  ('Ed25519', privateKey, ...)`, returns a base64-encoded signature.
+- `clear()`: deletes the IndexedDB record ("forget this device"). A new
+  keypair generated after this requires re-registration with the backend
+  (§2.2) before it can complete a login.
+- **Public key registration is explicitly out of scope for the frontend.**
+  An Owner/Administrator must associate a new device's `publicKeyBase64`
+  with an admin account through some out-of-band mechanism (backend admin
+  tool, one-time enrollment link, etc.) — not prescribed here (see §12).
+
+#### 2.2 Login flow, step by step
+
+Orchestrated by `AuthService.login()` (`src/app/core/auth/services/auth.service.ts`,
+distinct from the customer/admin `AuthService` in §1 despite the identical
+class name — different module, `core/auth/` vs `services/`):
+
+1. `GET {authApiUrl}/api/admin/auth/challenge` → `AuthChallenge { nonce,
+   issuedAt, expiresAt }` (all ISO 8601 except `nonce`, an opaque string).
+2. `Ed25519KeypairService.getOrCreateKeyPair()` (generates on first use).
+3. `Ed25519KeypairService.sign(nonce)` — signs the **raw nonce string
+   exactly as received**, no additional framing/prefix/hashing applied
+   client-side.
+4. `POST {authApiUrl}/api/admin/auth/verify` with body
+   `VerifySignatureRequest { publicKey, signature, nonce }` (`publicKey` =
+   base64 raw Ed25519 public key, `signature` = base64 signature over the
+   nonce, `nonce` = the same value echoed back).
+5. Backend must: re-derive the exact signed message from the nonce it
+   issued, verify the signature against its own `publicKey → admin account`
+   mapping, confirm the nonce hasn't expired or been used before, and only
+   then issue tokens.
+6. On success: `200 AuthTokenPair { token, refreshToken }`.
+   `SessionService.activate(tokens)` decodes the JWT (§3), stores both
+   tokens (§4), and schedules the next refresh (§5).
+7. On failure: `401`/`403` → `AuthService` maps it through
+   `authErrorCodeFromStatus()` to `invalid-signature` (or a more specific
+   code — see §2.5) and the UI routes to
+   `/admin-login/error/invalid-signature`.
+
+#### 2.3 API contracts (all under `{environment.authApiUrl}/api/admin/auth`)
+
+| Method | Path | Request body | Response | Notes |
+|---|---|---|---|---|
+| GET | `/challenge` | — | `200 AuthChallenge` | `{ nonce, issuedAt, expiresAt }` |
+| POST | `/verify` | `VerifySignatureRequest { publicKey, signature, nonce }` | `200 AuthTokenPair` \| `401` \| `403` | Issues `{ token, refreshToken }` |
+| POST | `/refresh` | `RefreshTokenRequest { refreshToken }` | `200 AuthTokenPair` \| `401` | Rotation expected — see §6 |
+| POST | `/logout` | `{ refreshToken }` | `204` (frontend clears local state regardless of response code/body) | Should revoke server-side |
+
+Types: `src/app/core/auth/models/auth-api.model.ts`. HTTP client:
+`src/app/core/auth/services/auth-api.service.ts` (`AuthApiService`) — thin
+wrapper, no retries, no fabricated mock responses.
+
+#### 2.4 Sequence diagram — admin login with Ed25519 signing
+
+```mermaid
+sequenceDiagram
+    participant Admin as Admin (browser)
+    participant FE as Frontend (AuthService, core/auth)
+    participant Key as Ed25519KeypairService (WebCrypto + IndexedDB)
+    participant BE as Backend
+
+    Admin->>FE: Click "Sign in"
+    FE->>BE: GET /api/admin/auth/challenge
+    BE-->>FE: 200 { nonce, issuedAt, expiresAt }
+    FE->>Key: getOrCreateKeyPair() (generate on first use, non-extractable)
+    Key-->>FE: { publicKeyBase64 }
+    FE->>Key: sign(nonce)
+    Key-->>FE: signature (base64)
+    FE->>BE: POST /api/admin/auth/verify { publicKey, signature, nonce }
+    alt signature valid & publicKey is a provisioned admin key & nonce fresh/unused
+        BE-->>FE: 200 { token, refreshToken }
+        FE->>FE: SessionService.activate(tokens):<br/>decode JWT claims, persist, schedule refresh
+        FE-->>Admin: redirect to /backoffice
+    else invalid signature / unknown key / expired or reused nonce
+        BE-->>FE: 401 / 403
+        FE-->>Admin: redirect to /admin-login/error/invalid-signature
+    end
+```
+
+#### 2.5 Error screens
+
+Single component `AuthErrorPageComponent` at route `/admin-login/error/:code`
+renders all five, keyed by route param. `authErrorCodeFromStatus()`
+(`src/app/core/auth/models/auth-error.model.ts`) maps HTTP status → code:
+`401→unauthorized`, `403→forbidden`, `0→backend-unavailable`,
+`5xx→backend-unavailable`, else `unauthorized`.
+
+| Code | Trigger | User action offered |
+|---|---|---|
+| `session-expired` | Refresh token rejected/expired | Sign in again |
+| `invalid-signature` | `verify` returns 401/403 during login, or any client-side failure in the challenge→sign→verify chain that isn't a clearer HTTP-derived code | Try again |
+| `unauthorized` | Route guard sees no active session | Sign in |
+| `forbidden` | `permissionGuard` denies (authenticated but insufficient role) | Back to dashboard |
+| `backend-unavailable` | Network error / 5xx / status 0 | Retry |
+
+#### 2.6 Interceptor status — NOT registered
+
+`src/app/core/auth/interceptors/auth.interceptor.ts` exists (adds
+`Authorization: Bearer` + reactive 401-refresh-and-retry, see §5) but **is
+not included** in `app.config.ts`'s `withInterceptors([...])` list today.
+Confirmed in `app.config.ts`:
+
+```
+withInterceptors([mockDataInterceptor, apiBaseUrlInterceptor,
+  apiHeadersInterceptor, adminAuthHeadersInterceptor, cacheInterceptor])
+```
+
+`authInterceptor` is absent. Until it is registered, no request in the app
+automatically attaches the Ed25519-flow JWT as a bearer token — this
+confirms the mechanism is fully dormant, not partially live.
+
+#### 2.7 Module map
+
+```
+src/app/core/auth/
+├── auth.routes.ts                        # /admin-login, /admin-login/error/:code
+├── models/
+│   ├── auth-api.model.ts                 # AuthChallenge, VerifySignatureRequest, AuthTokenPair, JwtClaims
+│   ├── auth-error.model.ts               # AuthErrorCode, authErrorCodeFromStatus()
+│   └── permission.model.ts               # AdminRole, Permission, ROLE_PERMISSIONS
+├── services/
+│   ├── ed25519-keypair.service.ts        # WebCrypto keygen/sign, IndexedDB persistence
+│   ├── auth-api.service.ts               # HttpClient calls to the 4 endpoints in §2.3
+│   ├── jwt.service.ts                    # decode-only JWT parsing
+│   ├── session.service.ts                # token/claims state, persistence, refresh scheduling
+│   ├── permission.service.ts             # role -> permission set
+│   ├── auth.service.ts                   # orchestrates challenge -> sign -> verify -> refresh -> logout
+│   └── auth-facade.service.ts            # public surface for components
+├── interceptors/
+│   └── auth.interceptor.ts               # Authorization: Bearer + 401 refresh-and-retry (NOT registered, §2.6)
+├── guards/
+│   ├── ed25519-auth.guard.ts             # requires SessionService.isAuthenticated() (not referenced by any route)
+│   └── permission.guard.ts               # permissionGuard(permission) factory
+└── pages/
+    ├── admin-login-page.component.*      # sign-in UI
+    └── auth-error-page.component.*       # parameterized error screen (§2.5)
+```
+
+`AuthFacade` (`src/app/core/auth/services/auth-facade.service.ts`) is the
+only thing components/pages should depend on; `AuthService`/
+`SessionService`/`PermissionService` are internal collaborators.
+
+---
+
+### 3. JWT structure
+
+Only defined for Mechanism B (Ed25519 flow) — Mechanism A (§1) issues no JWT,
+only an opaque session id. Expected claims
+(`src/app/core/auth/models/auth-api.model.ts::JwtClaims`):
+
+```ts
+interface JwtClaims {
+  sub: string;        // admin account id
+  role: AdminRole;     // 'Owner' | 'Administrator' | 'Editor' | 'Support' | 'ReadOnly'
+  iat: number;         // seconds since epoch (standard `iat`)
+  exp: number;         // seconds since epoch (standard `exp`)
+  publicKey: string;   // the Ed25519 public key this token was issued for
+}
+```
+
+`JwtService.decode()` (`src/app/core/auth/services/jwt.service.ts`) does
+**decode-only** parsing (base64url payload → JSON), and validates only the
+minimal shape: `sub` is a string, `role` is a string, `exp` is a number — if
+any of these three checks fail, decoding returns `null` and the caller
+(`SessionService`) discards the session as malformed.
+
+The frontend never verifies the JWT signature — it has no trusted key to
+check it against; that is exclusively the backend's job on every
+subsequent admin request. A decoded-but-unverified claim is UX (role-gated
+menus, expiry countdowns) — never proof of authorization to any client-side
+check.
+
+---
+
+### 4. Refresh token
+
+Defined only for Mechanism B. `AuthTokenPair { token, refreshToken }` is
+returned by both `/verify` and `/refresh`. Storage
+(`SessionService`, `src/app/core/auth/services/session.service.ts`):
+
+- `localStorage['ed25519AdminToken']` — access token (JWT)
+- `localStorage['ed25519AdminRefreshToken']` — refresh token (opaque to the
+  frontend; never decoded, only round-tripped)
+
+Both are written together in `activate()` and cleared together in `clear()`.
+There is no separate expiry tracked for the refresh token client-side —
+the frontend only reacts to a `401` from `/refresh` (see §5/§6).
+
+Separately, `AdminAuthService` (Mechanism A, Telegram) reserves
+`localStorage['adminToken']` / `localStorage['adminRefreshToken']` with
+`getAdminToken()`/`setAdminTokens()`/`clearAdminTokens()` methods —
+**written by no code path today** ("reserved for once the backend issues
+admin access/refresh tokens... unused until then," per the source comment).
+These are a distinct, currently-dead pair of storage keys from the Ed25519
+ones above; do not conflate them.
+
+---
+
+### 5. Token expiration handling
+
+#### 5.1 Mechanism A (Telegram session) — expiry via re-poll
+
+See §1.5. `expires` from the session payload drives a `setTimeout` at
+`max(expiresMs - now - 60_000, 30_000)` that re-calls `GET /users/sessions/
+{id}`; if the backend now reports inactive, local state is cleared to
+`unauthenticated`. There is no interceptor-level reactive handling for this
+mechanism — a 401/expired session surfaces only through the next explicit
+`checkSessionOnce()` poll or session re-check timer, not a per-request
+retry.
+
+#### 5.2 Mechanism B (Ed25519/JWT) — proactive + reactive
+
+`SessionService.scheduleRefresh(claims)`: computes
+`refreshInMs = max(claims.exp*1000 - now - 60_000, 5_000)` and sets a timer.
+When it fires, `AuthService.refresh()` runs automatically
+(`session.onRefreshDue(callback)` wiring, set up once in `AuthService`'s
+constructor to avoid a circular DI dependency between the two services).
+
+`SessionService.restore()` (intended to run once at app bootstrap, from an
+`APP_INITIALIZER` calling `AuthFacade.restoreSession()` — **not yet wired
+into the bootstrap process today**, see §12): reads persisted tokens,
+decodes claims, and either resumes with a scheduled refresh or marks
+`expired` immediately without any network call, so a stale session is
+caught before any component/guard runs.
+
+`authInterceptor` (present in source, not registered — §2.6) is documented
+as: catch a 401 on any admin-gated request → attempt one `refresh()` →
+retry the original request once on success → route to `session-expired` on
+failure. Does not retry more than once; a second 401 after an
+apparently-successful refresh is treated as a server-side problem, not a
+transient race.
+
+#### 5.3 Sequence diagram — token expiration / refresh (Ed25519 flow)
+
+```mermaid
+sequenceDiagram
+    participant FE as Frontend (SessionService)
+    participant IC as authInterceptor (not yet registered, §2.6)
+    participant BE as Backend
+
+    Note over FE: Timer fires ~60s before JWT exp
+    FE->>BE: POST /api/admin/auth/refresh { refreshToken }
+    alt refresh token still valid
+        BE-->>FE: 200 { token, refreshToken }
+        FE->>FE: activate(tokens) - reschedules next refresh
+    else refresh token expired/revoked
+        BE-->>FE: 401
+        FE->>FE: SessionService.markExpired()
+        FE-->>FE: route to /admin-login/error/session-expired
+    end
+
+    Note over IC: Reactive path - any 401 on an admin request<br/>(inactive until authInterceptor is registered)
+    IC->>BE: Admin API request (expired token)
+    BE-->>IC: 401
+    IC->>BE: POST /api/admin/auth/refresh (single retry)
+    alt refresh succeeds
+        BE-->>IC: 200 tokens
+        IC->>BE: retry original request with new token
+    else refresh fails
+        IC-->>FE: propagate error, route to session-expired
+    end
+```
+
+---
+
+### 6. Token rotation
+
+**Mechanism A**: no token to rotate — the `webSessionID` itself is stable
+for the life of the session; expiry is handled by re-polling status (§5.1),
+not by issuing a new id.
+
+**Mechanism B**: rotation is *expected* by the frontend but not verifiable
+until the backend exists. Per the source comment in `AuthApiService` and the
+security notes in the prior `docs/AUTH.md`:
+
+- Every `POST /refresh` response is expected to include a **new**
+  `refreshToken`; the backend should invalidate the one just used
+  (single-use refresh tokens).
+- The frontend always stores whatever pair it receives from `/verify` or
+  `/refresh` and never reuses an old refresh token after a successful
+  rotation — there is no client-side retry logic that would resend a stale
+  refresh token.
+- **Requires backend decision**: refresh-token reuse detection / revocation
+  cascade (e.g. if a rotated-out refresh token is presented again, should the
+  backend revoke the entire token family as a compromise signal?). Nothing
+  in the frontend implies or depends on this — it is a pure backend policy
+  choice.
+
+---
+
+### 7. Logout
+
+**Mechanism A** (`AdminAuthService.logout()` / `AuthService.logout()` in
+`src/app/services/auth.service.ts`): `DELETE /users/sessions/{id}` with
+`WebSessionID` header, then unconditionally clears local state (cookie,
+signals, timers) regardless of the HTTP result.
+
+**Mechanism B** (`AuthService.logout()` in `src/app/core/auth/services/`):
+clears `SessionService` state **immediately and unconditionally** (before
+the network call resolves), then best-effort calls
+`POST /api/admin/auth/logout { refreshToken }` if a refresh token was
+present; any error from that call is swallowed (`catchError(() =>
+throwError(() => null))`). If no refresh token exists locally, no network
+call is made at all. **Backend implication**: the frontend cannot be relied
+upon to reliably deliver the logout call (network failure, tab closed
+mid-request, etc.) — server-side session/token expiry must not depend on a
+client-issued logout ever arriving. `AuthFacade.logout()` additionally
+always navigates to `/admin-login` (default) via `finalize()`, regardless of
+API outcome.
+
+#### 7.1 Sequence diagram — logout (both mechanisms)
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant FE as Frontend
+    participant BE as Backend
+
+    User->>FE: Click "Log out"
+    FE->>FE: Clear local session state immediately<br/>(cookie / tokens / signals / timers)
+    alt Mechanism A (Telegram session)
+        FE->>BE: DELETE /users/sessions/{id} (header WebSessionID)
+        BE-->>FE: any response (ignored)
+    else Mechanism B (Ed25519/JWT) - only if a refresh token existed
+        FE->>BE: POST /api/admin/auth/logout { refreshToken }
+        BE-->>FE: 204 (or error, swallowed)
+    end
+    FE-->>User: redirect to login page
+```
+
+---
+
+### 8. Session invalidation
+
+Client-side triggers that clear local auth state, both mechanisms:
+
+- Explicit logout (§7).
+- Session status re-check (Mechanism A) returning `active: false` (§1.5).
+- JWT decode failure on restore (Mechanism B) — a malformed/unparsable
+  stored token is treated as no session at all (`SessionService.restore()`
+  calls `clear()`).
+- Refresh failure (Mechanism B) — any error from `/refresh` calls
+  `SessionService.markExpired()`.
+- `AdminAuthService.clearAuthState()` also clears the reserved
+  `adminToken`/`adminRefreshToken` keys (§4) even though nothing currently
+  writes them, for forward-compatibility once Mechanism A gains a token
+  pair.
+
+**Requires backend decision**: server-side session/token revocation
+propagation — e.g., can an Owner revoke another admin's active session
+remotely (relevant given `AdminUsersGateway.revokeSession` already exists as
+a **mock-only** admin-users gateway method per
+`docs/context/BACKEND-AUDIT.md` §14)? If so, the frontend has no push
+mechanism (no websocket, no polling of "is my token still valid" beyond the
+scheduled refresh) to learn about a remote revocation before its next
+refresh/request attempt — a session could remain "authenticated" client-side
+for up to the refresh interval after a backend-side revocation. If real-time
+revocation is required, that is new frontend work, not something already
+implied by existing code.
+
+---
+
+### 9. Role hierarchy
+
+**Discrepancy flagged by the backend audit — `AdminRole` is defined twice
+with different meanings. Reconciliation needed before backend
+implementation:**
+
+1. `src/app/core/auth/models/permission.model.ts` — a **string union** used
+   by the Ed25519/JWT flow's `role` claim and `PermissionService`:
+   ```ts
+   type AdminRole = 'Owner' | 'Administrator' | 'Editor' | 'Support' | 'ReadOnly';
+   ```
+   Ordered highest-to-lowest privilege by convention (not enforced in code —
+   `PermissionService` does not rely on ordering, only exact role → permission
+   set lookup).
+
+2. `src/app/features/admin/users/models/admin-user.model.ts` — an
+   **interface** describing an admin-users-management row (`{ id, name, ...
+   }`), unrelated in shape to #1 and used only by the mock admin-users
+   gateway/facade (`AdminUsersGateway`, MOCK-ONLY, no backend seam per the
+   audit).
+
+These two `AdminRole` symbols do not currently reference each other and are
+imported from different modules by different features. A backend
+implementer should treat #1 (the permission-model union) as the JWT/role
+claim contract for auth purposes, and flag #2 for a naming rename (e.g.
+`AdminUserRoleRecord`) rather than assuming they describe the same concept.
+This document does not resolve the collision — it is called out so a human
+reconciles it before building the backend role table.
+
+#### 9.1 Permission-to-role mapping (from `ROLE_PERMISSIONS`)
+
+| Role | Permissions |
+|---|---|
+| `Owner` | `backoffice.read`, `backoffice.write`, `builder.read`, `builder.write`, `users.manage`, `settings.manage` |
+| `Administrator` | `backoffice.read`, `backoffice.write`, `builder.read`, `builder.write`, `users.manage` |
+| `Editor` | `backoffice.read`, `backoffice.write`, `builder.read`, `builder.write` |
+| `Support` | `backoffice.read` |
+| `ReadOnly` | `backoffice.read`, `builder.read` |
+
+This is deliberately coarse and mirrors the bootstrap-level
+`PermissionsConfig` shape (`src/app/shared/models/config/permissions.model.ts`).
+Finer-grained, per-domain permissions (e.g. "can edit prices but not delete
+products") do not exist anywhere client-side and stay server-side —
+**Requires backend decision** if finer granularity is ever needed.
+
+---
+
+### 10. Tenant isolation
+
+`TenantResolverService` (`src/app/core/config/tenant-resolver.service.ts`)
+resolves tenant by **subdomain**, not by header or path prefix:
+
+```ts
+getTenantKey(): string {
+  if (isLocalhost()) return environment.fallbackTenantKey ?? 'default';
+  const segments = hostname.split('.').filter(Boolean);
+  if (segments.length === 0) return environment.fallbackTenantKey ?? 'default';
+  if (segments[0] === 'www' && segments.length > 1) return segments[1];
+  return segments[0];
+}
+```
+
+- `isLocalhost()` matches `localhost`, `127.0.0.1`, `::1`.
+- On a real host, the tenant key is the **first DNS label**, skipping a
+  leading `www`. E.g. `dexarmarket.api.dexarmarket.ru` → tenant key
+  `dexarmarket`; `www.acme.com` → `acme`.
+- This tenant key feeds `ApiConfigService.getBaseUrl()`
+  (`src/app/core/config/api-config.service.ts`, documented in
+  `docs/context/BACKEND-AUDIT.md` §2) to pick the marketplace API base URL:
+  localhost → `environment.localhostApiUrl` (`/api`); else
+  `environment.tenantApiBaseUrls[tenantKey]`; else
+  `environment.tenantApiTemplate` with `{tenant}` substituted; else
+  (gated by `allowBootstrapApiOverride`, off by default) a value read out of
+  the already-loaded bootstrap document
+  (`bootstrap.apiEndpoints.website.baseUrl` /
+  `bootstrap.tenant.apiBaseUrl`).
+- **No `X-Tenant` header or `/tenant/{id}/...` path prefix is sent by the
+  frontend anywhere** — tenant isolation for the marketplace API is achieved
+  purely by **which base URL/subdomain the request is sent to**, not by a
+  request attribute the backend reads per-call. Auth (both mechanisms) does
+  **not** carry any tenant identifier in its request bodies or headers
+  either — `POST /users/sessions`, `/api/admin/auth/challenge`, etc. are all
+  called against `environment.authApiUrl`, a single fixed origin, with no
+  per-tenant variation in the auth-flow code today.
+- **Requires backend decision**: if auth (session creation, Ed25519
+  challenge/verify) must be tenant-scoped (e.g. an admin's Ed25519 public key
+  should only authorize them for one tenant's backoffice), the frontend
+  currently has no mechanism to communicate which tenant a login attempt is
+  for beyond whatever the backend can infer from the request's origin/
+  Referer header — nothing in the auth payloads carries a tenant id
+  explicitly. This would be new frontend work if required.
+
+---
+
+### 11. Permission model / route guards
+
+#### 11.1 `adminAuthGuard` (live, Mechanism A) — `src/app/core/admin-auth/admin-auth.guard.ts`
+
+```ts
+export const adminAuthGuard: CanActivateFn = () => {
+  const adminAuth = inject(AdminAuthService);
+  if (adminAuth.isAuthenticated()) return true;
+  adminAuth.requestLogin();
+  return false;
+};
+```
+
+Checks only `AdminAuthService.isAuthenticated()` (Telegram session status
+`=== 'authenticated'`) — no role/permission check at all. Applied to
+`/edit`, `/edit/:section`, and `/backoffice` (and its children) in
+`app.routes.ts`. This guard **cannot** distinguish admin roles from each
+other — it is purely "is there an active admin Telegram session," which is
+the exact gap Mechanism B is meant to close.
+
+#### 11.2 `ed25519AuthGuard` (dormant, Mechanism B) — `src/app/core/auth/guards/ed25519-auth.guard.ts`
+
+Requires `SessionService.isAuthenticated()` (JWT status `=== 'authenticated'`).
+Not referenced by any route in `app.routes.ts` today — confirmed by source
+search. Exists purely as the cutover target (see §2's "not live" status).
+
+#### 11.3 `permissionGuard(permission)` — `src/app/core/auth/guards/permission.guard.ts`
+
+Factory guard that checks `PermissionService.has(permission)` against the
+Mechanism B role → permission table (§9.1). Also unused by any live route
+until Mechanism B is cut over, but ready to gate specific admin sub-routes
+by permission once it is (e.g. `permissionGuard('users.manage')` on a users
+page).
+
+#### 11.4 `languageGuard` — `src/app/guards/language.guard.ts`
+
+Not an authentication guard, but gates every localized route (`:lang`
+segment wraps the entire route tree in `app.routes.ts`). Behavior:
+
+- If `:lang` param is a known, enabled language: preload its translation
+  pack (`TranslateService.preloadLanguage`), set it as current
+  (`LanguageService.setLanguage`), allow navigation.
+- If known but **disabled**: redirect to the current default language,
+  preserving the rest of the path.
+- If unrecognized entirely: treat the URL as a legacy no-lang-prefix URL and
+  redirect to `/{defaultLang}{originalUrl}`, preserving query string/fragment
+  via `router.parseUrl` (not a hand-built `UrlTree`, to avoid double-encoding
+  the query string into the path segment).
+
+#### 11.5 `canDeactivate` guards (dirty-state guards, not auth)
+
+Also not authentication, but listed since the task asked for "what guards
+check": `projectEditorDirtyGuard`, `adminProductDirtyGuard`,
+`adminCategoryDirtyGuard` — all gate navigation *away* from an in-progress
+editor (builder section, product editor, category editor) to warn about
+unsaved changes. They read editor dirty-state signals, not auth state, and
+are unrelated to session/token validity.
+
+#### 11.6 What the frontend actually gates, summarized
+
+| Concern | Mechanism | Guard/service |
+|---|---|---|
+| "Is there an active admin session at all" | Telegram (A) | `adminAuthGuard` → `AdminAuthService.isAuthenticated()` |
+| "Is there an active admin JWT session" | Ed25519 (B), not live | `ed25519AuthGuard` → `SessionService.isAuthenticated()` |
+| "Does this role have permission X" | Ed25519 (B), not live | `permissionGuard(permission)` → `PermissionService.has()` |
+| "Is `:lang` valid/enabled" | n/a | `languageGuard` |
+| "Unsaved editor changes" | n/a | `*DirtyGuard` (project editor / product / category) |
+
+**Every one of these is a client-side UX gate only.** None of them are a
+substitute for server-side authorization — the backend must independently
+verify role/permission on every admin mutation regardless of what a route
+guard decided, per the security note already present in the prior
+`docs/AUTH.md` and repeated here: a passing client-side check is not proof
+of anything to the backend.
+
+---
+
+### 12. Open items — "Requires backend decision"
+
+Consolidated list of everything this document could not derive from
+existing frontend code and therefore does not prescribe:
+
+- **Public-key enrollment mechanism** (§2.1) — how an admin's Ed25519
+  `publicKeyBase64` gets associated with an account/role server-side (admin
+  tool? one-time enrollment link? manual DB entry?). Zero frontend code
+  exists for this by design.
+- **Refresh-token reuse/compromise detection** (§6) — whether presenting an
+  already-rotated-out refresh token should revoke the whole token family.
+  Not implied by any frontend behavior.
+- **Session/token revocation propagation** (§8) — whether/how a
+  remotely-revoked admin session (e.g. via the mock `AdminUsersGateway.
+  revokeSession`) is communicated to an already-logged-in client before its
+  next refresh cycle. No push/poll mechanism exists today.
+- **Tenant scoping of auth requests** (§10) — whether login/challenge/verify
+  need an explicit tenant identifier in the payload, versus relying on
+  request origin. Not present in any current auth payload.
+- **Relationship between the two mechanisms at cutover** — replace
+  `adminAuthGuard` with `ed25519AuthGuard` outright, or run both and let
+  role/tenant config decide? Explicitly called out in the prior
+  `docs/AUTH.md` as "a product decision, not made here," and nothing has
+  changed that.
+- **`AdminAuthService`'s reserved JWT-pair slots** (`adminToken`/
+  `adminRefreshToken`, §4) — whether Mechanism A is ever meant to gain its
+  own token pair (as the reserved-but-unused storage suggests) independent
+  of the Ed25519 migration, or whether that code is dead and should be
+  removed. Not resolved by current usage (nothing writes to it).
+- **`AdminRole` naming collision** (§9) — a reconciliation/rename decision
+  between `core/auth/models/permission.model.ts`'s string union and
+  `features/admin/users/models/admin-user.model.ts`'s interface; flagged,
+  not resolved, by this document.
+- **Fine-grained/per-domain permissions** (§9.1) — the current model is
+  intentionally coarse; whether a richer permission model is ever needed is
+  a backend/product decision.
+- **`APP_INITIALIZER` wiring for `AuthFacade.restoreSession()`** (§5.2) — the
+  code comment says this should be wired in before the Ed25519 flow goes
+  live, but it is not wired in today. This is frontend follow-up work, not a
+  backend decision, but is listed here because it changes what "session
+  restored on refresh" means in practice until it lands.
+
+---
+
+## 5. Security
+
+Every claim below is grounded in current source on branch `B2B`. Where the
+frontend implies nothing, the item is marked **Requires backend decision**.
+Auth and error contracts are owned by sibling docs — this section references
+`docs/AUTHENTICATION.md` and `docs/ERROR_CONTRACT.md` rather than restating
+them, and only covers the security-relevant angle.
+
+### 5.1 Origin
+
+The frontend calls a small, fixed set of origins, all declared in
+`src/environments/environment.ts` / `environment.production.ts`:
+
+| Origin | Source key | Used for |
+|---|---|---|
+| `https://api.dexarmarket.ru:445` | `tenantApiBaseUrls.default`, `authApiUrl`, and prod `apiUrl`/`localhostApiUrl` | marketplace API + session auth + Ed25519 admin auth |
+| `https://{tenant}.api.dexarmarket.ru:445` | `tenantApiTemplate` | per-tenant marketplace API (subdomain-substituted) |
+| `https://qr.vitanova.network/api` | `qrApiUrl` | payment / QR / card status |
+| `/api` (relative) | dev `apiUrl`/`localhostApiUrl` | localhost, proxied by nginx per tenant |
+| `https://api.qrserver.com/...` | literal in `ApiService` | QR **bitmap** image only (not a platform backend) |
+| `http://ip-api.com/json/...` | literal in `LocationService` | external geo-IP autodetect (no key, plaintext HTTP) |
+
+The tenant marketplace origin is chosen by **subdomain** (`TenantResolverService`,
+see `docs/AUTHENTICATION.md` §10) — there is no `X-Tenant` header or tenant
+path prefix. **Backend note:** the browser will make cross-origin requests to
+`api.dexarmarket.ru:445` and `qr.vitanova.network` from whatever host the SPA
+is served on (e.g. `dexarmarket.ru`), so those origins must return correct
+CORS headers (§5.2). `ip-api.com` is called over plaintext HTTP — a mixed-content
+and privacy concern flagged here; the frontend already tolerates its failure
+(falls back to 6 hardcoded regions).
+
+### 5.2 CORS
+
+**Bearer/header-only, never credentialed.** No `HttpClient` call in the
+codebase sets `withCredentials: true` (grep: zero matches in `src/`). Identity
+travels in **headers**, not cookies:
+
+- `WebSessionID` on every marketplace API request (`apiHeadersInterceptor`).
+- `AdminWebSessionID` + `Authorization: Bearer <token>` on `/admin/`,
+  `/backoffice/`, `/builder/`, `/media/` requests (`adminAuthHeadersInterceptor`).
+- `authorization-key` / `userid-value` on QR payment calls.
+
+The auth **cookies** (`webSessionID`, `adminSessionID`) are same-site,
+first-party, and are **not** sent cross-origin to the API — they exist only so
+the SPA can restore its own session locally. **Backend requirement:** the API
+must accept these requests as CORS with `Access-Control-Allow-Origin` set to
+the specific SPA origin(s) and `Access-Control-Allow-Headers` including
+`WebSessionID, AdminWebSessionID, Authorization, X-Region, X-Language, Currency`
+(and the QR API's `authorization-key, userid-value`). Because no request is
+credentialed, `Access-Control-Allow-Credentials` is **not** required and
+`Allow-Origin` may be specific per tenant.
+
+### 5.3 CSRF
+
+**Not applicable to the API surface, by construction.** All API authentication
+is bearer/header-based (§5.2) with **no cookie ever transmitted to the API**
+and `withCredentials` never set. A CSRF attack relies on the browser
+auto-attaching an ambient credential (cookie) to a forged cross-site request;
+since the API authenticates on a header the attacker's page cannot set
+cross-origin, a classic CSRF POST cannot forge an authenticated call. There is
+zero CSRF-token handling in the frontend (no XSRF interceptor, no
+`X-CSRF-Token`/`X-XSRF-TOKEN` reference anywhere in `src/`), and none is
+needed for the current design. **Backend note:** this guarantee holds only as
+long as the API does **not** start accepting a cookie as an auth credential —
+if a future endpoint authenticates via cookie, CSRF protection becomes
+mandatory. Requires backend decision only if that design change is made.
+
+### 5.4 JWT
+
+Cross-reference `docs/AUTHENTICATION.md` §3–§4. Security-relevant storage
+angle only:
+
+- **Live today (Telegram session, Mechanism A):** no JWT at all — an opaque
+  `webSessionID` in a cookie + in-memory signal. The reserved
+  `localStorage['adminToken']` / `adminRefreshToken` slots are **dead** (nothing
+  writes them).
+- **Ed25519 flow (Mechanism B, dormant):** access + refresh tokens live in
+  `localStorage` (`ed25519AdminToken`, `ed25519AdminRefreshToken`).
+  **XSS exposure implication:** `localStorage` is readable by any script in the
+  origin, so a single XSS foothold (see §5.8) exfiltrates the admin token pair
+  outright — there is no `HttpOnly` cookie protecting them. This is the
+  standard SPA trade-off and is acceptable **only** if the XSS surface (§5.8)
+  is genuinely closed server-side. **Requires backend decision:** whether admin
+  tokens should instead be delivered as `HttpOnly; Secure; SameSite` cookies
+  to remove the XSS-exfiltration path — the frontend currently assumes
+  `localStorage`, so this would be a coordinated frontend+backend change.
+
+### 5.5 Refresh
+
+Refresh tokens are protected client-side only as well as `localStorage`
+protects them — i.e. not from XSS (§5.4). The frontend never decodes the
+refresh token (round-tripped opaque), stores it beside the access token, and
+replaces the pair on every `/verify` and `/refresh` (`docs/AUTHENTICATION.md`
+§4, §6). Rotation is **expected** but only the backend can enforce it. There is
+no client-side reuse-detection. **Requires backend decision** (already flagged
+in `docs/AUTHENTICATION.md` §6): single-use refresh tokens + reuse/compromise
+revocation cascade — nothing in the frontend implies or depends on it.
+
+### 5.6 Rate limiting
+
+There is **no client-side rate-limit handling** (grep: no `429` / "rate limit"
+reference in `src/`; confirmed by `docs/ERROR_CONTRACT.md` §429). The frontend
+does, however, apply **debounce** on user-driven request bursts, which implies
+the natural request cadence a backend limiter should tolerate rather than block:
+
+- Search-as-you-type: `debounceTime(220)` in `SearchFacade`
+  (`src/app/features/search/facade/search.facade.ts:98`) — so a typing user
+  produces at most ~4–5 `GET /searchitems` calls/second, not one per keystroke.
+- Project-editor autosave: ~300 ms debounce before a draft commit
+  (localStorage only, not a backend call today).
+
+**Requires backend decision** on the rate-limit contract end to end (limits,
+`Retry-After` header vs `retryAfterSeconds` body field, and whether the
+frontend should auto-retry). Per `docs/ERROR_CONTRACT.md` §429, no retry
+interceptor exists — honoring 429 is net-new frontend work, not a config
+change.
+
+### 5.7 Replay protection
+
+The Ed25519 signing flow (`docs/AUTHENTICATION.md` §2) signs the **raw
+backend-issued nonce string exactly as received** — `Ed25519KeypairService.sign(nonce)`
+applies no client-side framing, prefix, hashing, timestamp, or
+counter (`src/app/core/auth/services/auth.service.ts` login flow;
+`ed25519-keypair.service.ts`). The `VerifySignatureRequest` body is
+`{ publicKey, signature, nonce }` and nothing else. Therefore **all** replay
+protection is the backend's responsibility via the nonce it issues:
+`AuthChallenge { nonce, issuedAt, expiresAt }`. **Backend requirement:** treat
+each nonce as single-use, bind it to the issuing client, reject it after
+`expiresAt`, and reject any reuse. The frontend contributes no independent
+freshness signal — there is no client timestamp or per-request nonce on any
+other call either (the Telegram session flow has no signing at all).
+
+### 5.8 XSS
+
+The frontend renders **backend/CMS-controlled HTML** in three places — this is
+the single most important input for what the backend must sanitize:
+
+| Location | File | Handling today |
+|---|---|---|
+| Storefront static page body (CMS content) | `src/app/pages/static-page/static-page.component.ts:104-106` | Runs `DomSanitizer.sanitize(SecurityContext.HTML, html)` **first**, then `bypassSecurityTrustHtml(sanitized)`. So it is Angular-sanitized before injection into `[innerHTML]`. |
+| Static-page **preview** (editor) | `src/app/features/content-management/components/static-page-preview/static-page-preview.component.ts:49` | `bypassSecurityTrustHtml(sanitized)` after a sanitize pass. |
+| Payment bank-frame URL | `src/app/pages/cart/cart.component.ts:475` | `bypassSecurityTrustResourceUrl(bankUrl)` — trusts a backend-supplied iframe URL. |
+
+The static-page path is the risky one: CMS body HTML originates from the
+bootstrap document (`BootstrapConfig.staticPages`, backend-served). It **is**
+run through Angular's sanitizer client-side, but Angular sanitization strips
+active content for the DOM context only — it is **not** a substitute for
+server-side sanitization/storage validation. **Backend requirement:** treat all
+CMS static-page HTML and any product-description HTML as untrusted on write,
+sanitize/allowlist server-side, and never assume the client sanitizer is the
+only defense. The `bypassSecurityTrustResourceUrl` on the bank payment frame
+means the backend-supplied payment URL must be strictly validated server-side
+(a malicious value renders in an iframe with `ResourceUrl` trust). Product
+descriptions are currently normalized to plain strings by
+`ApiService.normalizeItem` and are **not** rendered via `[innerHTML]` today, so
+they are lower-risk — but that holds only while descriptions stay plain-text.
+
+Note: the project-editor HTML editor (`marketplace-html-editor.component.ts`)
+uses `innerHTML` on a `contenteditable` surface for authoring; that is
+author-local editor state, not backend-rendered content, so it is out of the
+backend's sanitization scope.
+
+### 5.9 CSP
+
+**No CSP meta tag in `src/index.html`** (confirmed — only SEO/OG/Twitter/theme
+meta tags are present). CSP is delivered **at the web-server layer** via
+`nginx.conf`, and only on the primary tenant block:
+
+- `dexarmarket.ru` server block (`nginx.conf:41`) sets a full
+  `Content-Security-Policy`:
+  `default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' https://telegram.org; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com; img-src 'self' data: https:; connect-src 'self' https:; frame-src https://telegram.org;`
+  plus `X-Frame-Options: SAMEORIGIN`, `X-Content-Type-Options: nosniff`,
+  `X-XSS-Protection: 1; mode=block`, `Referrer-Policy: strict-origin-when-cross-origin`,
+  `Permissions-Policy: camera=(), microphone=(), geolocation=()`.
+- **The `lovero.store` block and the new-tenant template block set the other
+  security headers but omit the `Content-Security-Policy` header entirely** —
+  an inconsistency the backend/ops team should reconcile so every tenant gets
+  the same CSP.
+
+**Backend/ops observations:** the current CSP is permissive — `script-src`
+allows `'unsafe-inline'` and `'unsafe-eval'`, `connect-src 'self' https:`
+allows connections to any HTTPS origin, and `img-src` allows any `https:` and
+`data:`. This weakens the XSS defense-in-depth that would otherwise back up
+§5.8. **Requires backend decision:** whether to tighten the CSP (drop
+`unsafe-inline`/`unsafe-eval`, pin `connect-src` to the known API origins in
+§5.1) and whether to apply it uniformly across all tenant server blocks.
+
+### 5.10 Upload validation (client-side, in the media picker/library)
+
+The only upload path is `MockMediaRepository.upload()`
+(`src/app/core/media/mock-media-repository.service.ts`). Before storing, it
+runs `validateFile(file)`:
+
+- **Size:** rejects if `file.size > MAX_FILE_SIZE_BYTES` where
+  `MAX_FILE_SIZE_BYTES = 10 * 1024 * 1024` (**10 MB**, line 9).
+- **Type:** rejects if `file.type` is not in `ALLOWED_MIME_TYPES`
+  (line 12) — see §5.12 for the exact list.
+
+It then transforms before storage: raster images are downscaled to
+`MAX_IMAGE_DIMENSION = 2000` px on the longest edge at `COMPRESS_QUALITY = 0.85`
+(canvas re-encode to JPEG/PNG); GIFs pass through untouched; **SVGs are
+sanitized** (§5.11). Validation is keyed on `file.type` (the browser-reported
+MIME), which is trivially spoofable — see §5.11. The `<input type=file>` in the
+media picker does not set an `accept` attribute filtering the OS picker, so the
+MIME check is the only gate.
+
+### 5.11 Media validation (backend-side expectations)
+
+Because the client checks above run in the browser and can be bypassed
+(direct API call, forged `Content-Type`, renamed file), the backend must
+**re-validate everything independently**:
+
+- **Re-derive the real content type** from magic bytes / content sniffing, not
+  the client-declared MIME or filename extension. `assetKind()` client-side
+  keys purely off the declared MIME string.
+- **Re-enforce the size limit** server-side (10 MB is the frontend's number,
+  §5.10 / §5.12 — the backend may set its own, but must enforce one).
+- **Re-sanitize SVGs.** The frontend's `sanitizeSvg()` only strips `<script>`
+  elements and `on*="..."` inline event-handler attributes via regex
+  (lines 124-131). This is **naive** — it misses `<foreignObject>`,
+  `javascript:` URIs in `href`/`xlink:href`, CSS-based vectors, and namespaced
+  handlers. SVG is served with `image/svg+xml` and can execute script when
+  loaded as a document, so the backend must run a real SVG sanitizer/allowlist,
+  never trust the client's regex pass.
+- **Strip/normalize metadata** (EXIF, embedded payloads) on ingest.
+- **Serve uploaded assets from an isolated origin / with `Content-Disposition`
+  and `X-Content-Type-Options: nosniff`** so a malicious file can't be
+  interpreted as active content on the app origin.
+
+### 5.12 Maximum file sizes
+
+Exact client-enforced constant: **10 MB** —
+`MAX_FILE_SIZE_BYTES = 10 * 1024 * 1024`
+(`mock-media-repository.service.ts:9`). The user-facing error is
+`"File exceeds the 10MB limit."`. Related transform constants (not rejection
+limits): `MAX_IMAGE_DIMENSION = 2000` px, `COMPRESS_QUALITY = 0.85`. No
+per-account or aggregate storage quota is enforced client-side — see §7 Limits.
+
+### 5.13 Mime validation
+
+Exact client-accepted MIME allowlist
+(`ALLOWED_MIME_TYPES`, `mock-media-repository.service.ts:12`):
+
+```
+image/jpeg, image/png, image/webp, image/gif, image/svg+xml, application/pdf
+```
+
+These map to the `MediaAssetKind` union (`image` | `svg` | `pdf` | `other`)
+via `assetKind()`. The media picker's type filter exposes only
+`image / svg / pdf` to the user. No extension allowlist exists separately — the
+check is MIME-string only. The backend allowlist should mirror this set (and
+re-derive type from content, §5.11).
+
+### 5.14 Audit logging
+
+The admin **Monitoring** feature defines an event taxonomy the backend is
+expected to populate. `AdminMonitoringCategory`
+(`src/app/features/admin/monitoring/models/admin-monitoring.model.ts:1`) is:
+
+```
+'audit' | 'security' | 'login' | 'failed_login' | 'api' | 'error' | 'warning'
+```
+
+Each `AdminMonitoringEvent` carries `{ id, category, level (info|warning|error),
+message, technicalDetail?, actor, timestamp }`. The page filters events by these
+categories (`admin-monitoring-page.component.ts:26`). This is **MOCK-ONLY today**
+(no backend seam — see `docs/context/BACKEND-AUDIT.md` §14), but it defines the
+**event types the backend audit log must eventually emit** for the UI to be
+meaningful:
+
+- `audit` — admin actions taken (create/update/delete on any admin domain).
+- `security` — security-relevant events (permission changes, revocations).
+- `login` / `failed_login` — successful and failed authentication attempts,
+  with an `actor` identity.
+- `api` / `error` / `warning` — request-level diagnostics.
+
+Additionally, `AdminUserAuditEntry`
+(`src/app/features/admin/users/models/admin-user.model.ts:43`) implies a
+per-user audit trail of `roleChanged` / `statusChanged` events with `actor` and
+`timestamp`. **Backend requirement:** every admin mutation and auth event must
+be recorded with actor + timestamp so these two audit surfaces have real data;
+each event needs a stable `category`/`eventKey`, a human `message`, and an
+optional `technicalDetail`. **Requires backend decision:** retention window,
+whether failed-login events capture source IP/device (the `AdminSession` model
+carries `device`/`ip`, so the frontend already anticipates it), and the exact
+action→category mapping.
+
+### 5.15 Permission matrix (role × domain × actions)
+
+**Critical finding first:** the **live** admin gate does **no role check at
+all**. `adminAuthGuard` (`src/app/core/admin-auth/admin-auth.guard.ts`) only
+verifies `AdminAuthService.isAuthenticated()` — a binary "is there an active
+Telegram admin session." No admin component conditionally shows/hides actions
+by the current user's role (grep of `src/app/features/admin`: the `permission`/
+`role` matches are all about **managing other users as data** — role labels,
+the users-management `AdminRole` record, audit entries — never gating the
+current operator's own UI). So today, any authenticated admin can invoke every
+admin action the UI exposes; enforcement must be entirely server-side.
+
+The **intended** matrix comes from the dormant Ed25519 flow's `ROLE_PERMISSIONS`
+table (`src/app/core/auth/models/permission.model.ts`, mirrored in
+`docs/AUTHENTICATION.md` §9.1). Roles are the string union
+`Owner | Administrator | Editor | Support | ReadOnly`; permission domains are
+`backoffice`, `builder`, `users`, `settings`:
+
+| Role | backoffice.read | backoffice.write | builder.read | builder.write | users.manage | settings.manage |
+|---|:---:|:---:|:---:|:---:|:---:|:---:|
+| **Owner** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| **Administrator** | ✅ | ✅ | ✅ | ✅ | ✅ | — |
+| **Editor** | ✅ | ✅ | ✅ | ✅ | — | — |
+| **Support** | ✅ | — | — | — | — | — |
+| **ReadOnly** | ✅ | — | ✅ | — | — | — |
+
+Guards that would eventually enforce this (`ed25519AuthGuard`,
+`permissionGuard(permission)`) exist but are **not referenced by any route**
+today (`docs/AUTHENTICATION.md` §11). The mapping is deliberately coarse —
+there is no per-domain granularity (e.g. "edit prices but not delete products")
+anywhere client-side.
+
+**Backend requirements / decisions:**
+- The backend **must** independently authorize every admin mutation against the
+  authenticated role — a passing client guard is never proof of authorization.
+- **Requires backend decision:** finer-grained per-domain permissions if ever
+  needed (none implied client-side).
+- **Requires backend decision:** the `AdminRole` naming collision (auth string
+  union vs the users-management `AdminRole` interface with `{id, name,
+  permissions[], builtIn}`) — flagged in `docs/AUTHENTICATION.md` §9; the
+  users-management interface suggests custom/non-builtin roles with arbitrary
+  permission-string sets, which the coarse 5-role union does not model. Reconcile
+  before building the backend role table.
+
+---
+
+
+---
+
+## 6. Error Model
+
+Single unified error-response format the backend must return for every non-2xx
+response across all API surfaces (marketplace API, payment/QR API, session
+auth API, Ed25519 admin auth API, and any future admin/builder/backoffice
+APIs). Derived by cross-referencing every place the Angular frontend
+currently parses, catches, or reacts to an HTTP error — see
+`docs/context/BACKEND-AUDIT.md` for the full backend-surface audit this is
+based on.
+
+**Finding: the frontend does not currently parse any backend error envelope.**
+No `HttpInterceptor` in the pipeline (`src/app/app.config.ts` →
+`mockDataInterceptor, apiBaseUrlInterceptor, apiHeadersInterceptor,
+adminAuthHeadersInterceptor, cacheInterceptor`) inspects error responses —
+all five only touch outgoing requests or successful GET caching. Every
+consumer that reacts to failure does so on the RxJS/`HttpErrorResponse`
+level (`error.status`, `error.message`), never on a parsed JSON error body.
+The one exception is the Ed25519 admin-auth flow, which has a client-side
+`AuthErrorCode` union but (see §"Known frontend gap" below) currently derives
+it from **HTTP status only**, not from any body field. Because of this, the
+envelope below is a **clean proposal, not a reverse-engineered contract** —
+every shape decision is marked accordingly.
+
+### The envelope
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_FAILED",
+    "message": "One or more fields are invalid.",
+    "status": 422,
+    "requestId": "b3f1c2a0-4e21-4d3a-9e77-1e8f6a2d9c11",
+    "details": [
+      { "field": "sku", "code": "REQUIRED", "message": "SKU is required." }
+    ]
+  }
+}
+```
+
+**Requires backend decision: adopt this envelope.** The frontend has no
+existing opinion to preserve (no code reads `error.error.code` today), so
+this is a recommendation, chosen to be consistent with the shapes the
+frontend *does* already have opinions about:
+
+- Top-level `{ code, message, status }` mirrors the existing `AuthError`
+  interface (`src/app/core/auth/models/auth-error.model.ts:13-18`) almost
+  field-for-field — reusing that shape means the Ed25519 auth module can
+  parse the new envelope with only a `status` fallback removed, not a
+  rewrite.
+- `details[]` entries `{ field, code, message }` mirror the existing
+  client-side `ProjectValidationIssue` convention (`code, message, section,
+  fieldKey, severity` — `src/app/features/project-editor/services/
+  project-validator.service.ts:23-36`, consumed via `ProjectEditorFacade
+  .fieldError(fieldKey)`). No backend field-error shape exists to preserve
+  today (admin CRUD is 100% local/mock — see BACKEND-AUDIT.md §14), so this
+  is the closest existing frontend convention to align a real one to.
+- `requestId` is new (no frontend code reads it yet) — recommended so
+  support/ops can correlate a user-visible failure to server logs. If
+  adopted, the frontend would need a small addition to surface it in
+  error-state UI (not present today).
+
+Field notes:
+
+| Field | Required | Notes |
+|---|---|---|
+| `error.code` | yes | Stable, machine-readable, `UPPER_SNAKE_CASE`. Never localized. This is what the frontend should branch on, not `message`. |
+| `error.message` | yes | Human-readable fallback (English), safe to show only when the frontend has no i18n mapping for `code`. Never the sole signal for UI branching. |
+| `error.status` | yes | Must equal the HTTP status of the response (redundant with the transport layer, but the frontend's own `AuthError.status` already carries this, so keep parity). |
+| `error.requestId` | recommended | Opaque correlation id, echoed in logs. |
+| `error.details` | only for 422 | Array of field-level issues, see §422 below. |
+
+---
+
+### Status-by-status contract
+
+#### 401 — Unauthenticated / expired token
+
+```json
+{
+  "error": {
+    "code": "UNAUTHENTICATED",
+    "message": "Authentication is required to access this resource.",
+    "status": 401,
+    "requestId": "…"
+  }
+}
+```
+
+**Frontend reaction today:**
+- **Admin Ed25519 flow** (`AuthService.login()`/`refresh()` in
+  `src/app/core/auth/services/auth.service.ts`): any `HttpErrorResponse` with
+  status 401 is mapped via `authErrorCodeFromStatus()` → `AuthErrorCode
+  'unauthorized'`, surfaced by `AuthErrorPageComponent`
+  (`src/app/core/auth/pages/auth-error-page.component.ts`) with copy
+  "Unauthorized… Sign in" and a button that calls `router.navigateByUrl
+  ('/admin-login')`.
+- **Customer Telegram session auth** (`TelegramSessionApiService`,
+  `AuthService` customer-facing, `src/app/services/auth.service.ts`): no
+  code branches on a 401 status anywhere — session validity is instead
+  polled via `checkSessionOnce()` returning `AuthSession | null`. **Requires
+  backend decision**: whether/how a mid-session 401 on a customer-facing
+  marketplace call (e.g. `POST /cart`, `POST /orders`) should be surfaced —
+  today it would fall through to each caller's generic `catchError`/`error:`
+  handler (if any) with no unified "session expired, please re-auth" UX.
+- **Admin backoffice CRUD (products/orders/users/etc.)**: these facades
+  (`AdminUsersFacade`, `AdminOrdersFacade`, …) currently only ever talk to
+  local/mock gateways, so no real 401 has ever reached them. Their existing
+  generic `error` boolean signal + `common.errorTitle`/`common.errorDescription`
+  + retry button (see "Generic list-page error UI" below) is the pattern a
+  real 401 would fall into **unless** the facades are updated to branch on
+  status — they don't today.
+
+#### 403 — Forbidden (wrong role or tenant)
+
+```json
+{
+  "error": {
+    "code": "FORBIDDEN",
+    "message": "Your account does not have permission to perform this action.",
+    "status": 403,
+    "requestId": "…"
+  }
+}
+```
+
+**Frontend reaction today:** Ed25519 admin flow only. `authErrorCodeFromStatus(403)`
+→ `'forbidden'` → `AuthErrorPageComponent` copy "Forbidden… Back to
+dashboard", button `router.navigateByUrl('/backoffice')`. No tenant-scoping
+distinction exists in this code path — a 403 caused by wrong role and a 403
+caused by wrong tenant render identical copy today. **Requires backend
+decision**: if tenant-mismatch should be visually distinct from
+role-mismatch, it needs its own `error.code` (e.g. `TENANT_FORBIDDEN` vs
+`ROLE_FORBIDDEN`) since the frontend has no other signal to key off besides
+status today.
+
+#### 404 — Not found
+
+```json
+{
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "The requested item could not be found.",
+    "status": 404,
+    "requestId": "…"
+  }
+}
+```
+
+**Frontend reaction today:** No code path distinguishes 404 from any other
+failure. `catalog-container.component.ts` and
+`product-details-container.component.ts` both catch *any* load error and
+render the same generic `catalog.errorTitle`/`productDetails.errorTitle`
+empty-state (`en.ts:176,277`) — a real 404 (product deleted) and a 500
+(server crash) look identical to the user today. **Requires backend
+decision**: whether the frontend should be enhanced to show a distinct
+"this product no longer exists" message for 404 specifically (would need a
+status/code check added to those two containers — not present now).
+
+#### 409 — Conflict
+
+```json
+{
+  "error": {
+    "code": "CONFLICT",
+    "message": "A category with this slug already exists.",
+    "status": 409,
+    "requestId": "…"
+  }
+}
+```
+
+**Frontend reaction today:** no code catches or branches on 409 anywhere.
+The one related concept in the codebase is `AdminCategoriesGateway
+.isSlugTaken(slug, excludingId)` (BACKEND-AUDIT.md §14) — a **proactive**
+pre-check call the frontend makes *before* submitting, not a reaction to a
+409 conflict response. **Requires backend decision**: whether create/update
+endpoints should also return 409 on the same slug/uniqueness conflict as a
+race-condition backstop, and whether the frontend should add a 409 handler
+that surfaces `error.details` inline (there is no such handler today —
+`isSlugTaken` is the only existing conflict-avoidance mechanism, and it is
+best-effort/TOCTOU-prone).
+
+#### 422 — Validation failure
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_FAILED",
+    "message": "One or more fields are invalid.",
+    "status": 422,
+    "requestId": "…",
+    "details": [
+      { "field": "sku", "code": "REQUIRED", "message": "SKU is required." },
+      { "field": "price", "code": "OUT_OF_RANGE", "message": "Price must be greater than 0." }
+    ]
+  }
+}
+```
+
+**Frontend reaction today:** no admin form currently parses a backend
+validation-error body — all admin CRUD is local/mock (BACKEND-AUDIT.md §14),
+so there has never been a real 422 to react to. The frontend **does** have
+an established field-error UI convention worth preserving: `ProjectEditorFacade
+.fieldError(fieldKey): string | null`
+(`src/app/features/project-editor/facade/project-editor.facade.ts:371-374`)
+reads from `issuesByField` (a `Map<fieldKey, ProjectValidationIssue[]>`) and
+returns the first issue's `message`, for inline per-field template binding.
+That mechanism is entirely client-side validation today (`ProjectValidator`
+service), not backend-driven. **Requires backend decision**: adopting
+`details[].field` as the join key would let a future `fieldError()`-style
+adapter merge backend 422 errors into the same inline-error UI pattern
+without inventing a second one — but the adapter itself does not exist yet
+and would need to be built.
+
+#### 429 — Rate limited
+
+```json
+{
+  "error": {
+    "code": "RATE_LIMITED",
+    "message": "Too many requests. Please slow down.",
+    "status": 429,
+    "requestId": "…",
+    "retryAfterSeconds": 30
+  }
+}
+```
+
+**Frontend reaction today: none whatsoever.** No interceptor, facade, or
+component in the codebase references `429` or "rate limit" in any form (grepped
+across `src/`). **Requires backend decision** on every aspect:
+- Whether the backend sends a `Retry-After` HTTP header, a body field
+  (`retryAfterSeconds` above), or both.
+- Whether the frontend should retry automatically (with backoff) or only
+  show the user a "please wait Ns" message. Recommend: since no retry
+  interceptor exists today, add one is a new build item, not a config
+  change.
+
+#### 500 — Server error
+
+```json
+{
+  "error": {
+    "code": "INTERNAL_ERROR",
+    "message": "An unexpected error occurred. Please try again.",
+    "status": 500,
+    "requestId": "…"
+  }
+}
+```
+
+**Frontend reaction today:** falls into whichever generic catch-all a given
+caller has:
+- Ed25519 admin flow: `authErrorCodeFromStatus()` default branch → `status
+  >= 500 ? 'backend-unavailable' : 'unauthorized'` → same
+  "Backend unavailable… Retry" screen as a network-down 503 (see below) —
+  the frontend does not distinguish "server is up but this request 500'd"
+  from "server is completely unreachable."
+- Admin list pages (`AdminUsersFacade` and siblings): generic `error`
+  boolean signal set to `true` in the RxJS `error:` callback, rendering
+  `common.errorTitle`/`common.errorDescription` + a retry button that
+  re-invokes the same load call. No status differentiation.
+- Storefront catalog/product pages: same generic empty-state pattern as 404
+  above.
+- `LocationService.getRegions()`-equivalent: falls back silently to 6
+  hardcoded regions on *any* error (including 500), no user-visible error at
+  all (`src/app/services/location.service.ts`).
+
+#### 503 — Maintenance / unavailable
+
+```json
+{
+  "error": {
+    "code": "SERVICE_UNAVAILABLE",
+    "message": "The service is temporarily unavailable. Please try again shortly.",
+    "status": 503,
+    "requestId": "…"
+  }
+}
+```
+
+**Frontend reaction today:** Ed25519 admin flow only, via the same
+`status >= 500` branch as 500 above → `'backend-unavailable'` →
+`AuthErrorPageComponent` "Backend unavailable… Retry." No other code path
+reacts to 503 specifically today (marketplace API calls that 503 would just
+fall into each caller's generic error handling, same as 500 above).
+
+**Distinguishing signal from Maintenance mode (see next section):** use
+`error.code`, not the HTTP status. A plain infra 503 (database down,
+overload) should send `"code": "SERVICE_UNAVAILABLE"`; a deliberate
+maintenance window should send `"code": "MAINTENANCE_MODE"` (still with HTTP
+status 503, since it's a byte-identical "the service is not accepting
+requests" situation, but a different reason). This is the only way for the
+frontend to build a distinct maintenance-mode UX later, since status alone
+is not enough. `docs/MAINTENANCE_MODE.md` (sibling task, in progress) owns
+the UX/copy for the maintenance case — this document only fixes the wire
+signal it must key off (`error.code === "MAINTENANCE_MODE"`), so the two
+docs stay consistent without duplicating UX detail here.
+
+#### Maintenance mode
+
+Same HTTP status as above (503), distinguished purely by `error.code`:
+
+```json
+{
+  "error": {
+    "code": "MAINTENANCE_MODE",
+    "message": "This marketplace is temporarily down for maintenance.",
+    "status": 503,
+    "requestId": "…",
+    "maintenanceUntil": "2026-07-26T04:00:00Z"
+  }
+}
+```
+
+`maintenanceUntil` (ISO 8601, optional) lets the maintenance-mode UX (sibling
+doc) show an ETA if the backend has one. **Requires backend decision:**
+whether `maintenanceUntil` is populated reliably enough to promise in UI, or
+should be treated as advisory-only.
+
+**Frontend reaction today:** none — no maintenance-mode concept exists in
+the frontend at all currently (confirmed: no matches for "maintenance" in
+`src/`). This entire row is new; the sibling `docs/MAINTENANCE_MODE.md` task
+should treat it as building from scratch, not preserving anything.
+
+#### Tenant disabled
+
+```json
+{
+  "error": {
+    "code": "TENANT_DISABLED",
+    "message": "This marketplace is not currently active.",
+    "status": 403,
+    "requestId": "…"
+  }
+}
+```
+
+**Frontend reaction today: none.** Tenant resolution
+(`TenantResolverService`, `src/app/core/config/tenant-resolver.service.ts`)
+only ever resolves *which* tenant a request targets (via host/subdomain); no
+code path in the audited surface handles a backend telling the frontend
+"this tenant exists but is disabled." **Requires backend decision** end to
+end: status code (403 recommended, to reuse the existing `forbidden`
+auth-error screen plumbing, vs. a dedicated status), and whether this should
+route to a dedicated "tenant disabled" screen or reuse
+`AuthErrorPageComponent`'s `forbidden` copy (which currently says "Your
+account role does not have permission" — wrong wording for a
+tenant-disabled scenario, would need a new `AuthErrorCode` entry and copy if
+reused).
+
+#### Rate limit
+
+See **429** above — same contract, called out separately here only because
+the task list asked for it as its own row. No additional distinguishing
+signal needed beyond the 429 status + `RATE_LIMITED` code.
+
+#### Expired token
+
+```json
+{
+  "error": {
+    "code": "TOKEN_EXPIRED",
+    "message": "Your session has expired. Please sign in again.",
+    "status": 401,
+    "requestId": "…"
+  }
+}
+```
+
+**Frontend reaction today — known gap, read carefully:** `AuthService
+.refresh()` (`src/app/core/auth/services/auth.service.ts:65-76`) has a
+client-side `AuthErrorCode` value `'session-expired'` and passes it as
+`fallbackCode` into `handleAuthError()`. **However**, `toAuthErrorShape()`
+(lines 110-118) only uses `fallbackCode` when the caught error is **not** an
+`HttpErrorResponse` — for an actual HTTP error it always calls
+`authErrorCodeFromStatus(error.status)`, which maps 401 → `'unauthorized'`,
+never `'session-expired'`, regardless of `fallbackCode`. So today, a real
+backend 401 on `/refresh` renders the **generic "Unauthorized" screen**, not
+"Session expired" — the "Session expired" screen is only ever reached via
+the *no-refresh-token-present* client-side branch (line 67-70), never from a
+real HTTP response. **Requires backend decision + frontend fix**: for a
+distinct "your session expired, please sign in again" screen to actually
+render on a real backend 401, either (a) the backend returns a body
+`error.code: "TOKEN_EXPIRED"` and the frontend is updated to read it instead
+of relying solely on `authErrorCodeFromStatus(status)`, or (b) this
+distinction is accepted as unreachable today and left as future work. Flag
+this gap explicitly to whoever picks up the fix — it is a pre-existing bug,
+not something this contract can silently paper over.
+
+#### Invalid signature
+
+```json
+{
+  "error": {
+    "code": "INVALID_SIGNATURE",
+    "message": "The signed challenge could not be verified.",
+    "status": 401,
+    "requestId": "…"
+  }
+}
+```
+
+Ties to the Ed25519 admin-auth flow documented in `AUTHENTICATION.md`
+(sibling task, in progress) — keep the `code` value (`INVALID_SIGNATURE`)
+consistent with whatever that doc names the failure mode, since this
+contract only defines the wire shape and that doc owns the auth-flow
+narrative.
+
+**Frontend reaction today:** same gap as "Expired token" above.
+`AuthService.login()` passes `fallbackCode: 'invalid-signature'` into
+`handleAuthError()`, but `toAuthErrorShape()` discards it for any real
+`HttpErrorResponse` and maps a 401 from `/verify` to the generic
+`'unauthorized'` screen via `authErrorCodeFromStatus()`. The dedicated
+"Invalid signature… Try again" screen
+(`src/app/core/auth/pages/auth-error-page.component.ts:21-25`) exists in the
+copy table but is **currently unreachable from a real backend response** for
+the same reason as `session-expired` above. **Requires backend decision +
+frontend fix**: backend must send a body-level `error.code:
+"INVALID_SIGNATURE"` and the frontend's `toAuthErrorShape()` must be updated
+to prefer a body code over the status-only mapping, or this screen stays
+dead code reachable only via non-HTTP error paths.
+
+---
+
+### Generic list-page error UI (for reference)
+
+Every admin backoffice list page (`AdminUsersFacade`, `AdminOrdersFacade`,
+`AdminMonitoringFacade`, `AdminModerationFacade`, `AdminTransactionsFacade`,
+`AdminProductsFacade`, `AdminCategoriesFacade`, `AdminAnalyticsFacade`,
+`AdminCustomersFacade`, `AdminDashboardFacade`) follows the same shape,
+added by RC-02 (`e153a67 fix(backoffice): add error+retry states to Users,
+Monitoring, Analytics, Reports`):
+
+```ts
+readonly error = signal(false);
+// on load:
+error: () => { this.items.set([]); this.loading.set(false); this.error.set(true); }
+```
+
+```html
+@else if (facade.error()) {
+  <app-empty-state [title]="'common.errorTitle' | translate" [description]="'common.errorDescription' | translate">
+    <span slot="actions">
+      <app-button variant="primary" (click)="facade.loadAll()">{{ 'common.retry' | translate }}</app-button>
+    </span>
+  </app-empty-state>
+}
+```
+
+This is a **boolean** error flag — it does not branch on HTTP status or
+`error.code` today. Every status in this contract (401/403/404/409/422/429/
+500/503) would currently collapse into the same generic "Something went
+wrong / retry" UI on these pages **unless** the facades are individually
+updated to inspect `error.code`/`status` and branch — none do today. Wiring
+that up is out of scope for this document (it defines the wire contract);
+flagging it here so whoever wires real backends into these facades knows
+the current ceiling of frontend error UX is "generic retry," not
+per-status handling, except in the Ed25519 admin-auth module.
+
+---
+
+### Summary: "Requires backend decision" items
+
+- **Envelope adoption** — the `{ error: { code, message, status, requestId,
+  details? } }` shape itself; no frontend code parses any envelope today.
+- **401 on customer-facing marketplace calls** (`/cart`, `/orders`, etc.) —
+  no unified "session expired, please re-auth" UX exists for the customer
+  Telegram-session flow.
+- **403 tenant-mismatch vs role-mismatch** distinct copy/code.
+- **404 vs generic-error distinct UX** on catalog/product pages (currently
+  identical).
+- **409 conflict handling on submit** (today only a proactive
+  `isSlugTaken` pre-check exists; no reactive 409 handler).
+- **422 `details[]` → inline field-error adapter** for admin forms (the
+  client-side `fieldError()` convention exists but nothing feeds it from a
+  backend response yet).
+- **429 rate-limit contract end to end** — header vs body, retry-after
+  value, and whether the frontend auto-retries (nothing exists today).
+- **Maintenance-mode `maintenanceUntil` reliability** — advisory only, or
+  can the frontend promise an ETA.
+- **Tenant-disabled status code and screen** — reuse `forbidden` copy (wrong
+  wording today) vs. add a dedicated `AuthErrorCode`.
+- **Expired-token / invalid-signature body-code fix** — both are
+  **pre-existing frontend bugs**, not just missing decisions:
+  `toAuthErrorShape()` in `auth.service.ts` currently derives the error code
+  from HTTP status only and ignores the `fallbackCode` for real HTTP errors,
+  so the `'session-expired'` and `'invalid-signature'` screens are dead code
+  from any real backend response today. Fixing this requires both a backend
+  body `error.code` and a frontend change to prefer it.
+
+---
+
+## 7. Uploads
+
+Full media-upload lifecycle contract, derived from the actual media stack:
+`MediaRepository` (abstract token), `MockMediaRepository` (the only impl),
+`MediaLibraryFacade`, `MediaPickerComponent`, `MediaUsageService`, and the
+`MediaAsset` model. **Structural status:** media is MOCK-SWAPPABLE — bound via
+`{ provide: MediaRepository, useClass: MockMediaRepository }` in `app.config.ts`,
+so a real HTTP repository drops in behind the same abstract class with no UI
+change. **No real HTTP media backend exists yet**, and **no literal media
+endpoint path exists anywhere in code** — every path below is **PROPOSED** to
+satisfy the existing `MediaRepository` method shapes. The admin-auth interceptor
+already attaches `AdminWebSessionID` + `Authorization: Bearer` to any `/media/`
+URL (`docs/context/BACKEND-AUDIT.md` §3), so the backend can expect those headers.
+
+### 7.1 The `MediaAsset` contract (real interface)
+
+`src/app/core/media/models/media-asset.model.ts`:
+
+```ts
+export type MediaAssetKind = 'image' | 'svg' | 'pdf' | 'other';
+
+export interface MediaAsset {
+  id: string;
+  url: string;
+  thumbnailUrl?: string;
+  filename: string;
+  mimeType: string;
+  size: number;             // bytes
+  width?: number;
+  height?: number;
+  altText?: Record<string, string>;  // locale -> alt text
+  caption?: string;         // plain, non-localized
+  description?: string;
+  decorative?: boolean;     // suppresses missing-alt-text warning
+  tags?: string[];
+  folder?: string;
+  createdAt: string;        // ISO 8601
+}
+
+export interface MediaListResult { items: MediaAsset[]; total: number; }
+export interface MediaListParams {
+  page?: number; pageSize?: number; search?: string;
+  folder?: string; tag?: string; kind?: MediaAssetKind; sort?: MediaSort;
+}
+export type MediaSort = 'recent' | 'name' | 'size';
+export interface MediaUploadOptions { folder?: string; tags?: string[]; }
+```
+
+The abstract `MediaRepository` (the exact backend contract) is:
+
+```ts
+list(params?: MediaListParams): Promise<MediaListResult>;
+upload(file: File, options?: MediaUploadOptions): Promise<MediaAsset>;
+remove(id: string): Promise<void>;
+update(id, patch: Partial<Pick<MediaAsset,
+  'altText'|'tags'|'folder'|'caption'|'description'|'decorative'>>): Promise<MediaAsset>;
+listFolders(): Promise<string[]>;
+```
+
+### 7.2 Media upload
+
+- **Method / path (PROPOSED):** `POST /media` (or `/media/upload`).
+- **Content type:** `multipart/form-data` — the frontend holds a raw `File`
+  (`MediaLibraryFacade.upload(file, options)` → `repository.upload(file,
+  { folder, ...options })`). The natural wire form is a multipart body with the
+  binary file plus `folder` and `tags[]` fields from `MediaUploadOptions`.
+- **Headers:** `AdminWebSessionID` + `Authorization: Bearer <token>` (auto-added
+  for `/media/` by `adminAuthHeadersInterceptor`), plus multipart boundary.
+- **Request:** the file blob + optional `folder: string` and `tags: string[]`.
+  The current folder is injected by the facade when none is passed.
+- **Response:** a single fully-populated `MediaAsset` (§7.1). The backend
+  assigns `id`, canonical `url`, `thumbnailUrl`, `size` (post-processing),
+  `width`/`height`, and `createdAt`.
+- **Client pre-processing to be aware of:** the mock downscales images to
+  2000 px and re-encodes at quality 0.85 before "upload." A real backend
+  receives whatever the browser sends; it should **not** assume the client
+  compressed anything (§5.11) and must do its own validation and any canonical
+  resizing.
+- **Retry:** the facade keeps the last failed `File` and exposes
+  `retryUpload()` / `canRetry()`, and `cancelUpload()` uses an upload-token
+  guard to ignore a stale in-flight result. So the backend should make upload
+  **idempotent-safe** on retry (a retried upload after a client-perceived
+  failure may duplicate) — **Requires backend decision** on dedup strategy.
+
+### 7.3 Replace
+
+**No distinct "replace" operation exists.** `MediaRepository` has no `replace`
+method; `update()` only patches metadata (`altText, tags, folder, caption,
+description, decorative`), never the binary. Changing an asset's actual file =
+`remove(id)` + `upload(newFile)`, producing a **new `id` and new `url`**.
+**Backend implication:** references to the old asset URL (tracked by
+`MediaUsageService`, §7.5) are **not** auto-updated on replace — a true
+in-place replace that preserves `id`/`url` would be new frontend+backend work.
+**Requires backend decision** if in-place replace is wanted.
+
+### 7.4 Delete (single + bulk)
+
+- **Single:** `remove(id): Promise<void>` → **PROPOSED** `DELETE /media/{id}`.
+  `MediaLibraryFacade.remove(id)` also deselects and reloads.
+- **Bulk:** `MediaLibraryFacade.bulkDelete(ids[])` loops `repository.remove(id)`
+  **one call per id** (no batch endpoint) — so bulk delete today is N ×
+  `DELETE /media/{id}`. The confirm-dialog / selection flow (RC-02) gates this
+  in the UI; the backend just sees serial deletes. **Requires backend decision:**
+  whether to add a batch `DELETE /media` (body `{ ids: [] }`) to avoid N
+  round-trips — the facade would need a matching `bulkRemove` method (not
+  present today).
+- There is also `bulkMoveToFolder(ids, folder)` = N × `update(id, { folder })`.
+- **Hard vs soft delete: Requires backend decision** — the frontend calls
+  `remove` and expects the asset gone from `list()`; it has no restore/trash
+  concept for media (unlike admin orders/categories which do have
+  archive/restore).
+
+### 7.5 Metadata
+
+`MediaAsset` carries this metadata (all editable via `update()` except the
+system-assigned fields):
+
+| Field | Editable by frontend? | Notes |
+|---|---|---|
+| `altText: Record<string,string>` | yes | **Per-locale** alt text (locale key → string). |
+| `caption` | yes | Plain, non-localized. |
+| `description` | yes | Plain. |
+| `decorative: boolean` | yes | Suppresses the missing-alt warning. |
+| `tags: string[]` | yes | Free-form; drives the tag filter. |
+| `folder: string` | yes | Single folder; `listFolders()` derives the folder list. |
+| `width` / `height` | no (system) | Set from image dimensions at upload. |
+| `size` | no (system) | Bytes, post-processing. |
+| `mimeType` | no (system) | |
+| `filename` | no (system) | Original filename. |
+| `createdAt` | no (system) | ISO 8601 upload timestamp. |
+
+There is **no `uploader`/`updatedAt`/usage-count field** on `MediaAsset`.
+Usage is computed **client-side on demand** by `MediaUsageService.findUsages(bootstrap, url)`
+(`src/app/core/media/media-usage.service.ts`) — it walks the in-memory
+`BootstrapConfig` looking for the asset's `url` as a string value and reports
+where it is referenced (branding, theme, header, footer, static pages, etc.).
+So "usage tracking" is a read-time scan of the config, **not** a stored
+reverse-index. **Requires backend decision:** whether the backend should track
+uploader identity and a stored usage/reference count (the frontend does not
+require either today, but `metadata`-export and audit (§5.14) would benefit).
+**Metadata update endpoint (PROPOSED):** `PATCH /media/{id}` with the
+`update()` patch body, returning the updated `MediaAsset`.
+
+### 7.6 Image variants
+
+The frontend **does not use responsive image variants**. Zero `srcset`/`sizes`
+usage in Angular templates (the only `srcset`-ish hit is unrelated). Images are
+consumed as a **single `url`**, with an optional single `thumbnailUrl`. In the
+mock, `thumbnailUrl === url` (same object URL) — there is no distinct thumbnail
+rendition today. **Backend implication:** the contract is single-`url` +
+optional single-`thumbnailUrl`; the frontend will happily consume a
+backend-generated thumbnail if `thumbnailUrl` differs from `url`, but it never
+requests a specific size or a `srcset` set. Adding true responsive variants
+would be new frontend work.
+
+### 7.7 Thumbnail generation
+
+**Requires backend decision** on strategy — nothing in the frontend prescribes
+sizes or formats. But the frontend gives a concrete **display target** so the
+backend has a real number to aim at:
+
+- The media library / picker renders a **grid** whose cells are ~150 px wide
+  (`MediaPickerComponent.onGridKeydown` computes columns as
+  `clientWidth / 150`), page size **24** items.
+- A `thumbnailUrl` sized around **~150–300 px** (accounting for 2× DPI) would
+  serve the grid without shipping full-resolution originals.
+
+If the backend populates `thumbnailUrl` with such a rendition, the UI uses it
+automatically (falls back to `url` when absent). No other thumbnail sizes are
+consumed anywhere.
+
+### 7.8 Limits
+
+- **Per-file size:** 10 MB, client-enforced (§5.12) — the backend must
+  re-enforce (§5.11).
+- **MIME allowlist:** the 6 types in §5.13.
+- **Upload count / batch size:** no client cap — `bulkDelete`/`bulkMoveToFolder`
+  loop over arbitrary-length id arrays; single-file upload only (the picker's
+  `<input>` takes `files?.[0]`, so **one file per upload call**).
+- **Storage quota (per tenant / per account):** none client-side —
+  **Requires backend decision**.
+- **Pagination:** `pageSize` default **24** (`DEFAULT_PAGE_SIZE`/`PAGE_SIZE`);
+  `list()` returns `{ items, total }` so the backend must return an accurate
+  `total` for the pager.
+
+### 7.9 Future S3 compatibility
+
+The `MediaAsset`/`MediaRepository` contract is deliberately **storage-agnostic**
+and this is a **design constraint for the backend, not a frontend requirement**:
+the frontend only ever sees opaque `url` / `thumbnailUrl` strings and an opaque
+`id`. It never constructs storage paths, never assumes a host, and never signs
+or negotiates storage directly. Therefore the backend is free to back media
+with S3, a CDN, local disk, or anything else — including returning
+pre-signed/CDN URLs in `url`/`thumbnailUrl` — with **no frontend change**, as
+long as:
+
+- `upload()` still returns a complete `MediaAsset` synchronously with a usable
+  `url` (a direct-to-S3 pre-signed **upload** flow, where the client PUTs to S3
+  itself, is **not** what the current `repository.upload(file)` shape expects —
+  it passes the `File` to the repository and awaits the finished asset;
+  switching to browser-direct-to-S3 would be new frontend work). **Requires
+  backend decision** if a pre-signed direct-upload flow is desired.
+- Served asset URLs are treated as untrusted-origin content (§5.11) —
+  isolated origin, `nosniff`, correct `Content-Type`/`Content-Disposition`.
+
+---
+
+## 8. Real Backend Implementation Guide
+
+This section is the practical, top-to-bottom guide a backend engineer follows to replace the
+frontend's mock/local data layer with real endpoints. It is derived entirely from
+`docs/context/BACKEND-AUDIT.md` (the exhaustive source audit) — no business logic is invented
+beyond what the frontend gateway interfaces already fix. Where the frontend has no seam or no
+mapper today, that gap is stated explicitly rather than papered over.
+
+The core principle, already proven for Categories, is: **the gateway/provider _interface_ is the
+contract; a real implementation only has to satisfy that interface.** You never rewrite the
+interface, and — if the domain already has a DI-token seam — you never touch the facade or the
+UI. The only structural surprise, called out repeatedly below, is that **most admin domains do
+not have that seam yet** (audit §1, §14, §25 #1): their facade injects the concrete
+`Admin*LocalGateway` class directly, so a token must be introduced before a real gateway can be
+bound at all.
+
+### 8.1 Which frontend gateways must be replaced
+
+Every data boundary the audit found, with its swap status. "DI token status" is the single most
+important column — it tells you whether you can drop in a real class (`already token-bound`) or
+must first introduce a seam (`needs token added first`).
+
+| Gateway / provider interface | Current mock/local impl file | DI token status | Real impl class to write | Consuming facade(s) |
+|---|---|---|---|---|
+| `ConfigProvider` | `core/bootstrap/providers/mock-bootstrap.provider.ts` | already token-bound (`CONFIG_PROVIDER`) | **already exists & LIVE** — `ApiBootstrapProvider` (`GET /bootstrap`) | UiRuntime, WebsiteRuntime, ProjectEditor, ContentManagement, Diagnostics (via `ConfigService`) |
+| `ProductDataProvider` | none bound (mock via `mockDataInterceptor` only) | already token-bound (`PRODUCT_DATA_PROVIDER`) | **already exists & LIVE** — `ApiProductDataProvider` | `ProductFacade` |
+| `CategoryRepository` | none bound (mock via interceptor) | already token-bound (`CATEGORY_REPOSITORY`) | **already exists & LIVE** — `ApiCategoryRepository` (`GET /category`) | `CategoryFacade` |
+| `BackofficeDataProvider` | `core/backoffice/providers/mock-backoffice-data.provider.ts` | already token-bound (`BACKOFFICE_DATA_PROVIDER`) | **already exists & LIVE** — `ApiBackofficeDataProvider` (`/api/backoffice/*`) | storefront cards |
+| `AdminCategoriesGateway` | `features/admin/categories/services/admin-categories-local.gateway.ts` | already token-bound (`ADMIN_CATEGORIES_GATEWAY`) | **already exists & LIVE** — `AdminCategoriesApiGateway` | `AdminCategoriesFacade`, `AdminAnalyticsFacade` |
+| `AdminDashboardMetricsGateway` | `features/admin/dashboard/services/admin-dashboard-metrics.local.gateway.ts` | already token-bound (`ADMIN_DASHBOARD_METRICS_GATEWAY`) | `AdminDashboardMetricsApiGateway` (new) | `AdminDashboardFacade` |
+| `MediaRepository` (abstract class) | `core/media/mock-media-repository.service.ts` | already token-bound (abstract-class token in `app.config.ts`) | `ApiMediaRepository` (new) | `MediaLibraryFacade` |
+| `UserExperienceRepository` | `core/user-experience/repositories/local-user-experience.repository.ts` | already token-bound (`USER_EXPERIENCE_REPOSITORY`) | `AuthenticatedUserExperienceRepository` (new; see §8.3 note on redesign) | `UserExperienceFacade` |
+| `AdminOrdersGateway` | `features/admin/orders/services/admin-orders-local.gateway.ts` | **needs token added first** | `AdminOrdersApiGateway` (new) | `AdminOrdersFacade`, `AdminCustomersFacade`, `AdminAnalyticsFacade` |
+| `AdminProductsGateway` | `features/admin/products/services/admin-products-local.gateway.ts` | **needs token added first** | `AdminProductsApiGateway` (new) | `AdminProductsFacade`, `AdminAnalyticsFacade` |
+| `AdminUsersGateway` | `features/admin/users/services/admin-users-local.gateway.ts` | **needs token added first** | `AdminUsersApiGateway` (new) | `AdminUsersFacade` |
+| `AdminTransactionsGateway` | `features/admin/transactions/services/admin-transactions-local.gateway.ts` | **needs token added first** | `AdminTransactionsApiGateway` (new) | `AdminTransactionsFacade` |
+| `AdminMonitoringGateway` | `features/admin/monitoring/services/admin-monitoring-local.gateway.ts` | **needs token added first** | `AdminMonitoringApiGateway` (new) | `AdminMonitoringFacade` |
+| `AdminModerationGateway` | `features/admin/moderation/services/admin-moderation-local.gateway.ts` | **needs token added first** | `AdminModerationApiGateway` (new) | `AdminModerationFacade`, `AdminAnalyticsFacade` |
+| (Customers) | reuses `AdminOrdersLocalGateway` (derived) | **needs token added first** (inherits Orders seam) | none of its own — derive from `AdminOrdersApiGateway`, or add a `/customers` source | `AdminCustomersFacade` |
+| (Analytics) | reuses orders/products/moderation local + `ADMIN_CATEGORIES_GATEWAY` + `AdminDashboardFacade` | partial (categories/dashboard token-bound; rest not) | no aggregation endpoint exists — see §8.3 | `AdminAnalyticsFacade` |
+| Auth session (`TelegramSessionApiService`) | mock via `mockDataInterceptor` | n/a (concrete service, LIVE) | **already exists & LIVE** — no swap; implement server endpoints only | `AuthService`, `AdminAuthService`, `AuthFacade` |
+| Ed25519 admin auth (`AuthApiService`) | none | n/a (concrete service, LIVE wiring) | **client wiring exists; backend absent** — implement `/api/admin/auth/*` server-side | `AuthService` (Ed25519 flow) |
+| `SearchHistoryRepository` | localStorage impl (concrete) | injected concretely — LOCAL-ONLY by design | — (leave local; no backend) | `SearchFacade` (via `SearchHistoryService`) |
+
+Read this table as three tiers:
+
+1. **Done / LIVE (no gateway work):** ConfigProvider, ProductDataProvider, CategoryRepository,
+   BackofficeDataProvider, AdminCategories. These already talk to real HTTP through a real
+   `*Api*` class. The backend job here is only to _stand up the server endpoints_ these clients
+   already call — not to touch frontend code.
+2. **Token-bound, real impl missing:** DashboardMetrics, Media, UserExperience. The seam exists;
+   write the `*Api*` class and bind it. No facade edit.
+3. **No seam yet (the bulk of admin CRUD):** Orders, Products, Users, Transactions, Monitoring,
+   Moderation (plus derived Customers/Analytics). Each needs a token introduced _and_ a facade
+   injection change _before_ a real gateway can even be bound.
+
+### 8.2 Interfaces that stay unchanged (do not touch)
+
+The gateway/provider interface files _are_ the frozen seam. A real implementation satisfies the
+existing TypeScript interface; changing an interface is a frontend contract change and forces UI
+churn. **Do not edit any of these** while wiring a backend:
+
+- `core/config/config-provider.interface.ts` (`ConfigProvider`)
+- `core/products/providers/product-data-provider.interface.ts` (`ProductDataProvider`)
+- `core/categories/repositories/category.repository.ts` (`CategoryRepository`)
+- `core/backoffice/providers/backoffice-data-provider.interface.ts` (`BackofficeDataProvider`)
+- `core/media/media-repository.ts` (abstract class `MediaRepository`)
+- `core/user-experience/repositories/user-experience.repository.ts` (`UserExperienceRepository`)
+- `features/admin/categories/services/admin-categories-gateway.interface.ts` (`AdminCategoriesGateway`)
+- `features/admin/dashboard/services/admin-dashboard-metrics.gateway.interface.ts` (`AdminDashboardMetricsGateway`)
+- `features/admin/orders/services/admin-orders-gateway.interface.ts` (`AdminOrdersGateway`)
+- `features/admin/products/services/admin-products-gateway.interface.ts` (`AdminProductsGateway`)
+- `features/admin/users/services/admin-users-gateway.interface.ts` (`AdminUsersGateway`)
+- `features/admin/transactions/services/admin-transactions-gateway.interface.ts` (`AdminTransactionsGateway`)
+- `features/admin/monitoring/services/admin-monitoring-gateway.interface.ts` (`AdminMonitoringGateway`)
+- `features/admin/moderation/services/admin-moderation-gateway.interface.ts` (`AdminModerationGateway`)
+
+The interface method lists (the shapes the backend must satisfy) are enumerated in audit §14 and
+must not drift. If the backend genuinely cannot meet a method's shape, that is a conversation to
+have with the frontend owner and change the interface deliberately — not something to work around
+inside a mapper.
+
+### 8.3 Facades: which stay unchanged, which need a small adjustment
+
+The facade is the abstraction the components consume. **If a domain already has a DI-token seam
+and the real gateway honors the interface, its facade needs zero changes.** That covers all of
+tier 1 and tier 2 above (ConfigProvider/Product/Category/Backoffice/AdminCategories/Dashboard/
+Media/UserExperience facades are all injection-by-token already).
+
+Facades that **do** need a (small, mechanical) change:
+
+- **`AdminOrdersFacade`, `AdminProductsFacade`, `AdminUsersFacade`, `AdminTransactionsFacade`,
+  `AdminMonitoringFacade`, `AdminModerationFacade`** — each currently injects the concrete
+  `Admin*LocalGateway` class directly (audit §14, §21). The one-line change is to inject the new
+  DI token instead of the concrete class. This is unavoidable for these six because the seam does
+  not exist yet; it is the "add a token seam" half of the migration, not a behavior change.
+
+Facades whose current behavior is **mock-shaped** and needs more than a wiring swap:
+
+- **`AdminCustomersFacade`** (`features/admin/customers/facade/…`) derives its customer list by
+  reading `AdminOrdersLocalGateway` in memory (audit §14, §21). Once orders are real, it can keep
+  deriving customers from the Orders _token_, but if the backend exposes a first-class customers
+  source, prefer that. Either way the "derive from local orders" assumption is mock-specific and
+  should be revisited when Orders goes real.
+- **`AdminAnalyticsFacade`** (`features/admin/analytics/facade/…`) composes orders + products +
+  moderation local gateways plus the categories/dashboard tokens (audit §14, §21). There is **no
+  analytics aggregation endpoint and no tracking pipeline today** (audit §14; remaining-work
+  #13/#17). Real analytics is not a gateway swap — it needs a data source that does not exist yet.
+  Treat it as the last domain, dependent on orders/products/moderation all being real first.
+- **`UserExperienceFacade`** (`facades/platform/user-experience.facade.ts`) stores fully
+  denormalized wishlist/compare objects synchronously in localStorage (audit §19). The backend
+  decision (remaining-work #16) is id-only sync + a `GET /items/batch?ids=` hydration endpoint,
+  which requires redesigning the repository to store id-arrays and hydrate from a local product
+  cache — a real refactor, not a drop-in `*Api*` class. Flagged so nobody assumes the token swap
+  alone finishes wishlist sync.
+- **`ContentManagementFacade`** and **`ProjectEditorFacade`** have **no backend call at all**
+  today (audit §16, §17). They read/mutate the in-memory `BootstrapConfig` and persist drafts to
+  localStorage; "publishing a marketplace" = writing bootstrap back, for which **no client write
+  call exists**. Wiring these to a real backend means _adding_ a draft/publish HTTP path
+  (`ProjectEditorIoService` currently only does JSON.stringify/parse; drafts live in
+  `ProjectEditorDraftStorageService` / localStorage), not swapping a gateway.
+- **Cart** (`CartService`) is local-only by design (localStorage `marketplace_cart`); checkout
+  already emits real `POST /cart` / `POST /orders` calls (audit §10). No facade change — just be
+  aware cart _contents_ never round-trip to a backend.
+
+Also note the mock gateways commonly apply an **artificial delay** and keep state in
+localStorage/in-memory overlays (audit §14). A real gateway should drop the fake latency; the
+facades tolerate real async already (they're signal/Observable-based), so no facade edit is needed
+for that specifically.
+
+### 8.4 DTO mapping examples (worked)
+
+The frontend already carries adapters for its LIVE domains; a backend engineer should treat those
+adapters as the **tolerance contract** for the wire shape. Three representative cases:
+
+#### Example A — Categories (clean stack, mapper already exists)
+
+Real backend JSON (`GET /category`, shape the client already tolerates):
+
+```json
+[
+  {
+    "categoryID": 12,
+    "names": [ { "lang": "ru", "name": "Электроника" }, { "lang": "en", "name": "Electronics" } ],
+    "subcategories": [ { "categoryID": 34, "names": [ { "lang": "en", "name": "Phones" } ] } ]
+  }
+]
+```
+
+Frontend wire DTO: `CategoryDto`, `CategoryNameDto` (`core/categories/dto/category.dto.ts`).
+Domain model: `Category`, `CategoryTranslation` (`core/categories/models/category-domain.model.ts`).
+Bridge: **`CategoryMapper`** (`core/categories/mappers/category.mapper.ts`) — flattens the
+subcategory tree, dedupes by id, and normalizes the language code `am → hy`. **Already written.**
+Backend action: match the `CategoryDto` field names; no new mapper.
+
+#### Example B — Products (largest existing mapper; match its tolerance)
+
+Real backend JSON (`GET /items/{id}`) → frontend `Item` (`src/app/models/item.model.ts`).
+Bridge: **`ApiService.normalizeItem()`** — the single largest inline adapter in the codebase
+(audit §7). It reconciles two historical shapes and normalizes, among others:
+
+- `id` (string) ↔ `itemID` (numeric)
+- `imgs[]` ↔ `photos[]` (→ `ProductMedia`)
+- `names[]` ↔ `translations`
+- `description` as key/value array ↔ string
+- `comments` ↔ `callbacks` (reviews)
+- color `0xRRGGBB` → `#RRGGBB`; `remaining` count → stock band
+
+Backend action: **do not "clean up" these dual shapes** — `normalizeItem`/`normalizeCategory`
+define exactly what the client accepts. Producing a payload inside that tolerance envelope is the
+contract; a stricter/renamed shape breaks the storefront. No new mapper needed — the adapter
+exists and is LIVE.
+
+#### Example C — Admin Orders (no mapper exists yet — one must be written)
+
+Unlike A and B, the admin domains have **no wire DTO and no mapper** — the local gateways
+construct `AdminOrder` view models directly in memory and never touch a URL (audit §14, §24).
+So this is the shape you have _freedom_ to design on the backend, as long as the new
+`AdminOrdersApiGateway` maps it into the existing view model.
+
+Proposed backend JSON (`GET /backoffice/orders/:id`):
+
+```json
+{
+  "id": "ord_1042",
+  "status": "processing",
+  "paymentStatus": "paid",
+  "customer": { "id": "cus_88", "name": "…", "email": "…" },
+  "items": [ { "productId": "…", "title": "…", "qty": 2, "unitPrice": 1990 } ],
+  "shipping": { "method": "…", "address": "…" },
+  "timeline": [ { "event": "created", "at": "2026-07-01T10:00:00Z" } ]
+}
+```
+
+Frontend view model: `AdminOrder` + `AdminOrderCustomer`, `AdminOrderPayment`,
+`AdminOrderShipping`, `AdminOrderItem`, `AdminOrderTimelineEntry`, `AdminOrderStatus`,
+`AdminOrderPaymentStatus` (`features/admin/orders/models/admin-order.model.ts`, audit §23).
+Bridge: **a new `AdminOrdersApiGateway` must contain the mapping** JSON → `AdminOrder`, honoring
+the `AdminOrdersGateway` interface methods (`loadOrders`, `loadOrder`, `updateStatus`,
+`requestRefund`, `addNote`, `archiveOrder`, `restoreOrder`, `deleteOrder`). The `status` field
+must respect the order state machine (see the Orders CRUD contract / BACKEND_API.md §8.1).
+The same "no mapper exists, write one inside the new `*ApiGateway`" note applies to Products,
+Users, Transactions, Monitoring, and Moderation.
+
+### 8.5 Per-domain migration checklist (the pattern, then the table)
+
+**Generic pattern to flip one domain from mock to real.** Steps 1–3 are only needed for the
+"no seam yet" domains; token-bound domains start at step 4.
+
+1. **Ensure the gateway interface exists** (all admin domains already have one — audit §14). If a
+   domain truly has none (e.g. Customers, Analytics derive from others), decide whether to add one
+   or keep deriving.
+2. **Add a DI token** — `InjectionToken` + factory that selects mock vs. real off
+   `RuntimeProviderStrategyService`, mirroring `admin-categories-gateway.token.ts`.
+3. **Update the facade injection** from the concrete `Admin*LocalGateway` class to the new token.
+4. **Implement the `*ApiGateway`** class satisfying the existing interface (contains the DTO→view
+   mapper, per §8.4 Example C).
+5. **Bind the token to the real impl** in the providers (factory returns the api gateway for
+   `api` mode).
+6. **Retire the `*LocalGateway`** — either delete it or keep it behind the existing
+   `useMockData` / mode flag as a dev fixture (the factory already lets both coexist).
+
+This is the exact pattern Categories already follows (`admin-categories-api.gateway.ts` +
+`admin-categories-gateway.token.ts`); replicate it verbatim.
+
+| Domain | Needs steps 1–3 (add seam)? | Interface exists? | Real impl exists? | Net work |
+|---|---|---|---|---|
+| Categories (admin) | no (token-bound) | yes | **yes** | server endpoints only |
+| Dashboard metrics | no (token-bound) | yes | no | steps 4–6 |
+| Media | no (token-bound, class token) | yes (abstract class) | no | steps 4–6 |
+| User experience | no (token-bound) | yes | no | steps 4–6 **+ repo redesign** (id-only + batch hydrate) |
+| Orders | **yes** | yes | no | steps 1–6 (skip 1) |
+| Products (admin) | **yes** | yes | no | steps 1–6 (skip 1) |
+| Users / roles | **yes** | yes | no | steps 1–6 (skip 1) |
+| Transactions | **yes** | yes | no | steps 1–6 (skip 1) |
+| Monitoring | **yes** | yes | no | steps 1–6 (skip 1) |
+| Moderation | **yes** | yes | no | steps 1–6 (skip 1) |
+| Customers | inherits Orders seam | no (derived) | no | derive from Orders token, or add source |
+| Analytics | partial | no (derived) | no | needs data source first (last) |
+| Content management | n/a (no gateway) | n/a | no | **add** draft/publish HTTP path |
+| Project editor / builder | n/a (no gateway) | n/a | no | **add** draft/publish HTTP path |
+
+### 8.6 Recommended backend implementation order (all domains)
+
+Ordered by the frontend's actual dependency structure (audit §5–§18), not by convenience:
+
+1. **Auth + session first.** `TelegramSessionApiService` is LIVE and every admin path is gated by
+   the `adminAuthHeadersInterceptor` (`AdminWebSessionID` / `Bearer`, audit §3). Nothing
+   role-gated works until session issuance and (if used) the Ed25519 `/api/admin/auth/*` flow are
+   real. Blocks everything admin.
+2. **Bootstrap / tenant resolution.** `GET /bootstrap` transport is done, but its **content**
+   (branding/theme/nav/seo) is still stubbed (remaining-work #1). Tenant resolution and
+   `ApiConfigService.getBaseUrl()` depend on it; every tenant-scoped call resolves through it.
+3. **Categories.** Already LIVE for both storefront (`GET /category`) and admin
+   (`AdminCategoriesApiGateway`). Products reference categories, so categories must be real and
+   populated before products are meaningful. Mostly "confirm server endpoints" work.
+4. **Products / catalog.** Storefront reads (`GET /items`, `/searchitems`, `/randomitems`) are
+   LIVE; the **admin Products CRUD** is the first no-seam domain to build (remaining-work #3, P0),
+   and it depends on categories.
+5. **Media.** Products/categories editors reference media assets; a real `ApiMediaRepository`
+   (remaining-work #5, P0) should land alongside/just after admin Products.
+6. **Cart / Orders / Transactions.** Checkout `POST /cart` + `POST /orders` are LIVE; admin
+   **Orders CRUD** (remaining-work #6) then **Transactions** (tied to orders, #7) are the P1 core
+   commerce domains. Orders before Transactions/Customers/Analytics (they derive from it).
+7. **Reviews / Moderation.** Customer review/question writes are LIVE; admin **Moderation**
+   (#10) gates them. Depends on products existing.
+8. **Users / roles / invitations** (#9) — admin governance; independent of commerce but needs
+   auth (step 1).
+9. **Dashboard metrics** (#11) then **Monitoring** (#12) — operational visibility over the
+   domains above.
+10. **Analytics** (#13/#17) — **last**: needs orders/products/moderation real _and_ a tracking
+    pipeline that does not exist yet.
+11. **Builder draft/publish + Content/CMS** (#2 P0 for builder transport, #14 for CMS) — these are
+    net-new write paths (no client call exists, audit §16/§17). Builder publish is high priority
+    for the builder product but is orthogonal to the storefront/commerce chain, so it can proceed
+    in parallel once bootstrap content (step 2) is real.
+12. **User-experience sync** (#16) and **search suggestions/filters** (#15) — P2/P3 enhancements
+    over already-working local features.
+
+### 8.7 Estimated effort (frontend-informed)
+
+These are **frontend-informed** sizes only — they reflect how much of the contract is already
+seamed/mapped on the client. Backend has its own unknowns (schema design, storage, infra, the
+tracking pipeline) that are **out of scope for this document**; a domain marked S here can still be
+L on the server.
+
+| Domain | Size | Why |
+|---|---|---|
+| Categories (storefront + admin) | **S** | LIVE both sides; `CategoryMapper` + `AdminCategoriesApiGateway` exist. Server endpoints only. |
+| Products storefront reads | **S** | LIVE; `normalizeItem` absorbs shape variance. |
+| Bootstrap content | **M** | Transport done; producing real branding/theme/nav/seo values is the work (#1). |
+| Media | **M** | Token seam + abstract interface ready; write `ApiMediaRepository` + upload pipeline (#5). |
+| Admin Orders | **M** | Interface + rich view models exist, but no seam and no mapper — steps 1–6 + mapper. |
+| Admin Products CRUD + variants | **L** | No seam, no mapper; largest admin model set (variants/attributes/translations/seo). |
+| Admin Users/roles/invitations | **M** | No seam; also reconcile the duplicate `AdminRole` naming (audit §14/§25 #3). |
+| Admin Transactions | **M** | No seam; tied to Orders shape. |
+| Admin Moderation | **M** | No seam; two state machines (reviews + reports). |
+| Admin Monitoring | **M** | No seam; three sub-resources (events/queues/webhooks). |
+| Dashboard metrics | **S–M** | Token-bound already; single `loadMetrics` shape. |
+| Customers | **S** | Derives from Orders once Orders is real. |
+| Analytics | **XL** | No data source; needs tracking pipeline + aggregation, gated on everything above. |
+| User-experience sync | **L** | Requires client repository redesign (id-only + batch hydrate), not a drop-in. |
+| Builder draft/publish | **L** | Net-new write path; no client call exists today. |
+| Content management / CMS | **M–L** | Net-new write path; adapter (`ContentPageService`) exists but no HTTP. |
+| Search suggestions/filters | **M** | Client orchestration exists; backend suggestion source is new. |
+
+---
+
+## 9. Backend Checklist
+
+A literal, top-to-bottom checklist. Work the phases in order; within a phase, items are roughly
+independent. Section references point to the assembled backend-integration document (this doc's
+§8, the CRUD-contracts sections, and `docs/BACKEND_API.md` where a full shape already lives).
+
+### Phase 1 — Foundation (nothing role-gated works until these land)
+
+- [ ] Implement session issuance/check/logout: `POST /users/sessions`, `GET /users/sessions/:id`, `DELETE /users/sessions/:id` — per Auth contract (§5a; BACKEND_API.md `/users/sessions/*`, already client-LIVE).
+- [ ] Implement the Ed25519 admin-auth flow `GET /api/admin/auth/challenge`, `POST /verify`, `POST /refresh`, `POST /logout` — client wiring is LIVE and 404s today (§5b). Return `AuthChallenge` / `AuthTokenPair` shapes exactly.
+- [ ] Honor the admin auth headers on every gated path: `AdminWebSessionID` + `Authorization: Bearer` for URLs containing `/admin/`, `/backoffice/`, `/builder/`, `/media/` (§3 interceptor pipeline).
+- [ ] Serve real `GET /bootstrap` **content** (branding, theme, navigation, seo — not just the transport) — per Bootstrap contract (§6; BACKEND_API.md §4). This is a P0 blocker.
+- [ ] Populate `bootstrap.apiEndpoints.{website,builder,backoffice}` records so tenant-scoped paths resolve at runtime (§6; audit §24 — no path literals exist in client code).
+- [ ] Confirm tenant resolution inputs (host/slug/code) match `TenantConfig` so `ApiConfigService.getBaseUrl()` resolves the right base (§2, §6).
+- [ ] Adopt a consistent error envelope; the client maps failures to a `backend-unavailable` screen for admin auth — keep error bodies non-leaky (§5b; security guidance).
+- [ ] Set the header contract: accept `X-Region`, `X-Language` (RU/EN/AM), `Currency` (default RUB), `WebSessionID` on marketplace requests (§3).
+
+### Phase 2 — Read-heavy domains (mostly confirm; already client-LIVE)
+
+- [ ] Stand up `GET /category` returning the `CategoryDto` shape `CategoryMapper` tolerates (§8.4 Example A; audit §8) — already LIVE client-side.
+- [ ] Stand up `GET /items/:id`, `GET /category/:id`, `GET /items/randomitems`, `GET /searchitems` within the `normalizeItem` tolerance envelope (§8.4 Example B; audit §4, §7).
+- [ ] Serve admin categories CRUD via the existing `AdminCategoriesApiGateway` contract: `loadCategories`, `loadCategory`, `create/update/delete/restore`, `isSlugTaken` — per Categories CRUD contract (BACKEND_API.md §6.9). **Already wired client-side (DONE).**
+- [ ] Serve `GET /api/backoffice/products` and `GET /api/backoffice/categories` (storefront cards) — `ApiBackofficeDataProvider` is LIVE (audit §9).
+- [ ] Stand up `GET /regions` → `Region[]` (feeds the `X-Region` header; client falls back to 6 hardcoded regions) (audit §12).
+
+### Phase 3 — Write-heavy customer domains
+
+- [ ] Keep `POST /cart` (`CartPaymentRequest` → `QrCreateResponse`) and the frozen QR/card payment polling working unchanged (§10; payments frozen per BACKEND_API.md §2.8).
+- [ ] Implement `POST /orders` (`CreateOrderRequest` → `CreateOrderResponse`) — client call is LIVE, fire-and-forget after payment (§10; BACKEND_API.md §16.9, marked DONE client-side).
+- [ ] Implement `POST /purchase-email` (email receipt) (audit §4).
+- [ ] Accept review/question writes `POST /items/:id/callback` and `POST /items/:id/questiion` (**preserve the `questiion` typo** — it matches the client literal) (§11; audit §4).
+
+### Phase 4 — Admin domains (each needs the token seam added first — §8.5)
+
+- [ ] Add `AdminOrdersGateway` token + `AdminOrdersApiGateway`, switch `AdminOrdersFacade` to the token; implement `GET/POST /backoffice/orders*` incl. `POST /backoffice/orders/:id/status` respecting the order state machine — per Orders CRUD contract (§8.4 Example C, §8.5; BACKEND_API.md §6.11/§8.1).
+- [ ] Add `AdminProductsGateway` token + `AdminProductsApiGateway`, switch `AdminProductsFacade`; implement Products CRUD + variants — per Products CRUD contract (§8.5; BACKEND_API.md §6.10/§7.2).
+- [ ] Add `AdminTransactionsGateway` token + api gateway, switch `AdminTransactionsFacade`; implement transactions list/detail + `retryFailed` + `setFraudFlag` (tied to orders) — per Transactions contract (§8.5; BACKEND_API.md §6.12).
+- [ ] Add `AdminUsersGateway` token + api gateway, switch `AdminUsersFacade`; implement users/roles/invitations/sessions/audit — per Users contract (§8.5; BACKEND_API.md §6.13). Reconcile the duplicate `AdminRole` naming (audit §25 #3).
+- [ ] Add `AdminModerationGateway` token + api gateway, switch `AdminModerationFacade`; implement review + report status transitions — per Moderation contract (§8.5; BACKEND_API.md §6.14/§8.4/§8.5).
+- [ ] Add `AdminMonitoringGateway` token + api gateway, switch `AdminMonitoringFacade`; implement events/queues/webhooks reads — per Monitoring contract (§8.5; BACKEND_API.md §6.16).
+- [ ] Wire `AdminDashboardMetricsApiGateway` to the existing `ADMIN_DASHBOARD_METRICS_GATEWAY` token; implement `loadMetrics` — per Dashboard contract (§8.5; BACKEND_API.md §6.15).
+- [ ] Resolve Customers: derive from the real Orders token (`AdminCustomersFacade`) or add a first-class customers source (§8.3).
+- [ ] Defer Analytics until orders/products/moderation are real and a tracking pipeline exists; then implement the analytics summary source (§8.3, §8.6 step 10; BACKEND_API.md §6.17).
+
+### Phase 5 — Builder / CMS (net-new write paths — no client call exists today)
+
+- [ ] Implement builder bootstrap draft/publish/validate: `GET/PUT /builder/bootstrap/draft`, `POST /builder/bootstrap/publish`, `POST /builder/bootstrap/validate` — and add the client-side write call in `ProjectEditorFacade`/`ProjectEditorIoService` (§8.3, §17; BACKEND_API.md §6.7). P0 for the builder.
+- [ ] Implement content pages / CMS write path and wire `ContentManagementFacade` beyond in-memory bootstrap (§8.3, §16; BACKEND_API.md §6.8).
+- [ ] Implement the media upload/delete/replace pipeline behind `ApiMediaRepository` bound to the `MediaRepository` token (§8.5; BACKEND_API.md §6.18/§10).
+
+### Phase 6 — Hardening
+
+- [ ] Add rate limiting on all write endpoints (orders, reviews, admin CRUD, media upload) (security guidance).
+- [ ] Set CSP / security headers for the frontend origin (frontend + API share a domain by decision — remaining-work "Explicitly not in this list").
+- [ ] Add audit logging for admin mutations (order status, role changes, moderation actions, publish) — the client already models `*AuditEntry` / timeline shapes (audit §23).
+- [ ] Implement maintenance-mode / graceful `backend-unavailable` responses the client can surface (§5b).
+- [ ] Implement `GET /items/batch?ids=` to unblock the user-experience id-only sync redesign (remaining-work #16; §8.3).
+- [ ] Add search suggestions/catalog-filter source if pursuing #15 (§8.6 step 12; BACKEND_API.md §6.6).
+- [ ] Plan dynamic sitemap generation (server-side, no frontend action) (remaining-work #18).
diff --git a/docs/AUTH.md b/docs/archive/AUTH.md
similarity index 98%
rename from docs/AUTH.md
rename to docs/archive/AUTH.md
index 8d4bc5b..f3e45ae 100644
--- a/docs/AUTH.md
+++ b/docs/archive/AUTH.md
@@ -1,3 +1,5 @@
+> **ARCHIVED 2026-07-26.** Superseded by [`docs/BACKEND_INTEGRATION.md`](../BACKEND_INTEGRATION.md), the single canonical backend integration document. Kept for history only — do not implement against this file.
+
 # Admin Authentication — Ed25519 Foundation
 
 Status: **FRONTEND PREPARED, NOT LIVE.** Everything in this document describes
diff --git a/docs/BACKEND_API.md b/docs/archive/BACKEND_API.md
similarity index 99%
rename from docs/BACKEND_API.md
rename to docs/archive/BACKEND_API.md
index cb35cbd..4c0bbb3 100644
--- a/docs/BACKEND_API.md
+++ b/docs/archive/BACKEND_API.md
@@ -1,3 +1,5 @@
+> **ARCHIVED 2026-07-26.** Superseded by [`docs/BACKEND_INTEGRATION.md`](../BACKEND_INTEGRATION.md), the single canonical backend integration document. Kept for history only — do not implement against this file.
+
 # Backend Integration — Master Specification
 
 Status: canonical. This is the single authoritative backend/API contract for this Angular multi-tenant marketplace platform. It supersedes and replaces `docs/BACKEND.md`, `docs/BACKEND_API.md` (old), `docs/BACKEND-INTEGRATION-PROMPT.md`, `docs/BACKEND-DIFF-VS-MAIN.md`, `docs/architecture/backend/Backend-Platform-API-Spec.md`, and the API-contract portions of `docs/BOOTSTRAP.md`. Those files are deleted; this document is where all of that content now lives, verified against the current source tree on branch `B2B`.
diff --git a/docs/BACKEND_API_REMAINING_WORK.md b/docs/archive/BACKEND_API_REMAINING_WORK.md
similarity index 97%
rename from docs/BACKEND_API_REMAINING_WORK.md
rename to docs/archive/BACKEND_API_REMAINING_WORK.md
index c1d2c8e..38fcd4e 100644
--- a/docs/BACKEND_API_REMAINING_WORK.md
+++ b/docs/archive/BACKEND_API_REMAINING_WORK.md
@@ -1,3 +1,5 @@
+> **ARCHIVED 2026-07-26.** Superseded by [`docs/BACKEND_INTEGRATION.md`](../BACKEND_INTEGRATION.md), the single canonical backend integration document. Kept for history only — do not implement against this file.
+
 # Remaining backend work (everything except auth/session)
 
 Companion to the `API-CONTRACT.md` backend delivered separately (covers `GET /bootstrap`