--- title: Multi-Shop Branch Project Scan - 2026-06-10 tags: [audit, repo-scan, multi-shop, white-label, documentation-sync] created: 2026-06-10 --- # Multi-Shop Branch Project Scan - 2026-06-10 > Scope: full workspace scan of nested Git repositories under `/Users/manwe/CascadeProjects/escrow`, with special focus on `frontend/` and `backend/` `feature/white-label-shops`. ## Repository snapshot | Repo | Branch | Head | Status summary | Notes | | --- | --- | --- | --- | --- | | `frontend/` | `feature/white-label-shops` | `df679a4` | Ahead of `forgejo/feature/white-label-shops` by 43 commits; dirty worktree | Version `2.11.49`. Multi-shop frontend, admin tenants UI, `WEBAPP_ENABLED` gate, many untracked E2E specs/report artifacts. | | `backend/` | `feature/white-label-shops` | `ce06f47` | Ahead of `forgejo/feature/white-label-shops` by 35 commits; clean | Version `2.11.49`. Tenant services, storefront routes, tenant bot webhook, custom-domain/Caddy provisioning. | | `deployment/` | `main` | `08fca31` | Ahead of `origin/main` by 2 commits; dirty worktree | Adds `escrow-multi` stack for `multi.amn.gg`; `escrow-multi/docker-compose.yml` modified; `dev-amn/` untracked. | | `scanner/` | `development` | `1911c3a` | Ahead of `origin/development` by 8 commits; clean | Version `0.1.10`. Recent BSC Testnet/tUSDT alignment. | | `amanat-assist/` | `main` | `821601a` | Dirty worktree | Version `1.1.0`. Recent Telegram theme/auth/review UX work; local `docker-compose.yml` modified and `nginx.conf` untracked. | | `nick-doc/` | `main` | `6724422` | Dirty worktree | Existing tenant docs were untracked before this sync; `.obsidian/graph.json` already modified. | ## Multi-shop branch summary The active multi-shop implementation is split across `frontend/`, `backend/`, and `deployment/`: - `backend/src/db/schema/tenant.ts` defines six PG-native tenant tables: `tenants`, `tenant_domains`, `tenant_bots`, `tenant_integrations`, `tenant_payment_policies`, and `tenant_user_roles`. - `backend/src/routes/tenantRoutes.ts` exposes tenant CRUD, activation/suspension, domains, bot registration/deletion/claim links, payment policies, and tenant roles. - `backend/src/routes/storefrontRoutes.ts` exposes public tenant bootstrap and reserved catalog/checkout/order stubs. - `backend/src/routes/tenantWebhookRoutes.ts` handles tenant Telegram bot webhooks and `/start ` admin activation. - `backend/src/services/tenant/domainProvisioningService.ts` verifies DNS, provisions Caddy routes, checks TLS, syncs active routes at startup, and runs a polling loop. - `frontend/src/contexts/TenantContext.tsx` fetches `/api/storefront/bootstrap` and falls back to Amanat defaults on expected tenant misses. - `frontend/src/app/dashboard/admin/tenants` and `frontend/src/sections/admin/tenants` provide tenant list/detail UI, DNS/TLS controls, bot activation links, payment policy editing, and member role controls. - `deployment/escrow-multi/docker-compose.yml` defines the isolated `escrow-multi` stack with `:multi` frontend/backend images, one-shot migrations, isolated Postgres/Redis, and `shared-web` ingress. ## Documentation updated in this sync | Doc | Update | | --- | --- | | [[System Overview]] | Reframed the platform as a multi-repo workspace and added the active multi-shop branch role. | | [[10 - Services/README]] | Added tenant/white-label service row and `multi.amn.gg` routing. | | [[frontend]] | Updated version/status/remote and noted tenant admin UI plus `WEBAPP_ENABLED`. | | [[backend]] | Updated version/status and added tenant/storefront/tenant-webhook route groups. | | [[deployment]] | Added `escrow-multi` stack details and branch isolation warning. | | [[Tenant]] | Added bot claim fields and current domain lifecycle. | | [[Tenant API]] | Added domain verify/TLS/delete routes, bot claim/delete/webhook routes, and current request/response behavior. | | [[Tenant Storefront Flow]] | Updated domain provisioning and Telegram bot claim sequences. | | [[tenant]] | Added Caddy/domain services, tenant webhook route, current env vars, and frontend/backend member-route mismatch. | ## Open findings | Priority | Finding | Evidence | Suggested next step | | --- | --- | --- | --- | | P1 | Tenant member UI and backend route names do not match. | Frontend Members tab calls `/tenants/:tenantId/members` and `/tenants/:tenantId/members/:memberId`; backend exposes `POST /tenants/:tenantId/roles` and `DELETE /tenants/:tenantId/roles`. | Align frontend hooks/UI to backend routes or add backend member aliases before relying on tenant member management. | | P2 | `useTenantDomains().addDomain()` sends `mode: "primary"` when `isPrimary` is true, but backend/domain enum accepts `cname` or `managed_ns`. | `frontend/src/hooks/use-tenants.ts` maps `isPrimary` to `"primary"`; `tenantDomainMode` enum is `managed_ns`, `cname`. | Remove `isPrimary` mapping or introduce a separate primary-domain model. | | P2 | Tenant API docs and code now show bot webhook auto-registration, but production readiness depends on correct public `APP_URL`/`FRONTEND_URL`, Telegram secret header delivery, and tenant bot notification routing. | `tenantBotService.registerBot()` fire-and-forgets `setWebhook`; non-claim updates are currently acknowledged and ignored. | Add smoke tests for bot claim and document how tenant seller notifications will route after claim. | | P3 | The docs vault now reflects Postgres/Drizzle as current runtime, but older pages still contain Mongo-era language. | `System Overview` was corrected; deeper flow/data pages may still mention legacy Mongo models. | Run a later doc-audit pass focused on Mongo/Mongoose references after code migration status is final. | ## Guardrails confirmed - No frontend/backend code changes were made in this documentation sync, so no version bump is required. - Do not touch the `escrow-dev` / `dev-amn` stack while working on `feature/white-label-shops`; target only `escrow-multi`. - Do not print or copy `.env` contents, BotFather tokens, private keys, database credentials, or Woodpecker agent tokens into docs or chat. Related: [[Tenant]], [[Tenant API]], [[Tenant Storefront Flow]], [[tenant]], [[deployment]], [[PRD - Seller-Owned White-Label Shops and Bots]].