marketplaces/docs/BACKEND-DIFF-VS-MAIN.md

# Backend Handoff — B2B branch vs `main`

Audience: backend developer. This is the "what changed and what you need to build" summary for the `B2B` branch compared to `main`. It frames the detailed punch list in [`BACKEND.md`](BACKEND.md) — read that file for exact endpoint shapes and the frontend files that change once each endpoint exists.

## TL;DR

`B2B` is **~138 commits ahead of `main`**. Almost all of it is **frontend that has been built ahead of the backend**: a full admin backoffice, a project editor, a media manager, and a design-system component library. Every data-writing feature runs today against an **in-memory / `localStorage` mock gateway** that is already designed to be swapped for a real API via an injection token — the UI, facades, and pages do **not** change when you wire a real backend; you implement one gateway/provider class per domain and rebind its token.

**You are not changing any existing contract.** Existing auth, payments, `GET /bootstrap`, and `GET /category` are frozen. Everything below is *new* backend surface the frontend is waiting on.

## What `B2B` adds over `main` (feature-level)

| Area | What's new on the frontend | Backend today | Priority |
|---|---|---|---|
| Design system | Reusable primitives (Button, Input, Card, Badge, Dialog, Table, Pagination, Skeleton, EmptyState, FormField) + editor primitives (Toggle, Select, ColorPicker, SectionCard, LocaleTabs, KeyValueEditor) | n/a (pure UI) | — |
| Project Editor | Full tenant `BootstrapConfig` editor (11 sections, draft/publish, validation, per-locale content, HTML editor for static pages) | **mock**: draft/publish is `localStorage` only, no persistence | **High** |
| Media manager | Upload / grid / delete + reusable media picker | **mock**: IndexedDB adapter, nothing server-side | High |
| Categories admin | List + create/edit, hierarchy, drag reorder, soft delete/restore, draft/publish, SEO/translations | **mock**: in-memory, no write path | High |
| Products admin | List + editor (variants, barcode, archive, related products, bulk actions) | **mock**: in-memory gateway | High |
| Orders admin | List/detail, status changes, refund, cancel, notes, CSV, invoice | **mock**: 24 synthetic orders | High |
| Transactions admin | List, retry, fraud flag, audit log, CSV | **mock**: derived from mock orders | Medium |
| Users / roles admin | Users, roles, invitations, sessions, audit log | **mock**: synthetic; ties to auth gap below | High |
| Dashboard metrics | Counts, status, health, activity feed | **partial**: counts composed client-side; activity is `localStorage` | Medium |
| Monitoring | Health (real) + event/queue/webhook feeds | **mock** except Health | Medium |
| Analytics | Revenue/orders/top-products (from mock orders) + visitors/funnels/heatmaps | **no data source** for traffic/funnels | Low |
| SEO | Tenant-driven meta tags, `sitemap.xml` / `robots.txt` baseline | **static baseline** only, not per-tenant | Low |

## The two things to do first

1. **Admin authorization (security).** Admin and customer login currently share **one** Telegram QR session backend, so the server has no concept of "this is an admin session." Any Telegram user who completes the QR flow on the admin login screen gets an `adminSessionID`. **Server-side authorization keyed off the session id is required** — nothing on the frontend can substitute. See [`BACKEND.md`](BACKEND.md) §1.

2. **Bootstrap draft / publish persistence.** The Project Editor edits the same `BootstrapConfig` the storefront consumes, but Save is `localStorage`-only and Publish is in-memory — no backend call. Needs `GET/PUT /builder/bootstrap/draft`, `POST /builder/bootstrap/publish`, optional `POST /builder/bootstrap/validate`, and **server-side re-validation** (the client validator is not a trust boundary). See [`BACKEND.md`](BACKEND.md) §2.

## The pattern for every mocked domain

For categories, products, orders, transactions, users, monitoring, dashboard metrics:

1. A `*LocalGateway` (or `*Provider`) implements a gateway interface and is bound via an Angular injection token.
2. You implement a `*ApiGateway` against the **same interface**, hitting real endpoints matching the domain model in `features/admin/<area>/models/*.model.ts`.
3. You rebind the token in DI config. **Facades and page components do not change.**

Model shapes to build against are named per area in [`BACKEND.md`](BACKEND.md) §5–§16.

## Known production issue not fixable here

Intermittent `502`/`504` on refresh / back-navigation in production originates from the **backend API's own reverse proxy** (`api.dexarmarket.ru:445`, `users.vitanova.network:456`) — the frontend calls those absolute URLs directly, bypassing this repo's nginx. Needs DevOps/backend investigation of upstream health and timeouts around session-check + bootstrap endpoints. See [`BACKEND.md`](BACKEND.md) "Known reliability issues".

## Verifying the frontend locally without a backend

`environment.ts` ships `useMockBootstrapOnLocal: true` and mock gateways are the default bindings, so `npm run dexar` runs the whole thing offline. Admin routes are reachable in dev via `?devBypassAdmin=true`. Flipping a domain to a real API is the gateway-swap above — no mock removal needed to start.