nick-doc/09 - Audits/Multi-Shop Branch Project Scan - 2026-06-10.md

title, tags, created

title	tags	created
Multi-Shop Branch Project Scan - 2026-06-10	audit repo-scan multi-shop white-label documentation-sync	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 <claimToken> 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.