docs: sync vault with codebase state (2026-06-12)

- Update backend, frontend, scanner, deployment, amanat-assist service docs
- Update System Overview, Scanner Architecture, Telegram Mini App flow
- Update 10 - Services/README.md
- Add Tenant data model, Tenant API reference, Tenant Storefront Flow
- Add Multi-Shop Branch Project Scan (2026-06-10)
- Add tenant.md service doc
- Append activity log entry
- Reflects archived/search/stats route fix and new E2E test suite

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

00 - Overview/System Overview.md

@@ -11,12 +11,18 @@ created: 2026-05-23
 
 ## The 10,000-foot view
 
-Amn is a **two-repo system**:
+Amn is a **multi-repo workspace**:
 
-- **Frontend** (`/Users/mojtabaheidari/code/frontend`) — a Next.js 16 App Router application that serves the marketplace UI, the admin dashboard, the public blog, and the user-facing Web3 wallet flow.
-- **Backend** (`/Users/mojtabaheidari/code/backend`) — an Express 5 + TypeScript API server that owns all business logic, persists live app state primarily to MongoDB, caches in Redis, and brokers all external integrations. The active integration backend also contains the Postgres/Drizzle migration layer, but it is not yet the broad runtime store.
+- **Frontend** (`frontend/`) — a Next.js 16 App Router application that serves the marketplace UI, admin dashboard, public blog, Telegram Mini App shell, seller shop surfaces, and the white-label tenant admin UI.
+- **Backend** (`backend/`) — an Express 5 + TypeScript API server that owns business logic, persists runtime state through PostgreSQL/Drizzle repositories, caches in Redis, brokers external integrations, and now hosts the tenant/storefront/custom-domain APIs.
+- **Deployment** (`deployment/`) — Docker Compose, Caddy, migrations, and Gatus configuration for `dev.amn.gg` plus the `escrow-multi` / `multi.amn.gg` stack.
+- **Scanner** (`scanner/`) — the Go AMN Pay Scanner that watches chains and delivers signed payment webhooks back to the backend.
+- **Amanat Assist** (`amanat-assist/`) — the AI request-assistant Mini App and LLM proxy.
+- **Documentation vault** (`nick-doc/`) — Obsidian/Taskmaster documentation and audit history.
 
-The two repos are deployable independently. They communicate over **HTTPS (REST)** for stateful actions and over **WebSocket (Socket.IO)** for live updates. The frontend never talks directly to MongoDB, Redis, Request Network API keys, OpenAI, or admin custody secrets -- every sensitive external interaction is mediated by the backend so that secrets stay on the server.
+The deployable repos are versioned independently, but frontend/backend are kept in lockstep for image tags. They communicate over **HTTPS (REST)** for stateful actions and over **WebSocket (Socket.IO)** for live updates. The frontend never talks directly to PostgreSQL, Redis, scanner API keys, OpenAI, Telegram BotFather tokens, or admin custody secrets -- every sensitive external interaction is mediated by server-side services.
+
+The active multi-shop branch is `feature/white-label-shops` in `frontend/` and `backend/`. It powers `multi.amn.gg`, tenant subdomains, custom domains routed dynamically through Caddy, and tenant-owned Telegram bots. See [[Tenant]], [[Tenant API]], and [[Tenant Storefront Flow]].
 
 ## System map
 
@@ -40,6 +46,7 @@ flowchart TB
         SocketS["Socket.IO server<br/>rooms per user / chat / request"]
         Auth["Auth service<br/>JWT + Passkey + Google + Telegram"]
         Market["Marketplace service<br/>Requests, Offers, Templates"]
+        TenantSvc["Tenant service<br/>host resolution + domain + bot"]
         ChatSvc["Chat service"]
         PaySvc["Payment service<br/>Request Network + ledger + custody controls"]
         TelegramSvc["Telegram service<br/>bot + Mini App + notifications"]
@@ -52,8 +59,7 @@ flowchart TB
     end
 
     subgraph Data["Data tier"]
-        Mongo[("MongoDB<br/>via Mongoose<br/>primary runtime")]
-        PG[("PostgreSQL 18<br/>Drizzle migration layer")]
+        PG[("PostgreSQL 18<br/>Drizzle repositories")]
         RedisDB[("Redis<br/>cache + locks")]
         Disk[("Local disk<br/>/uploads")]
     end
@@ -81,11 +87,10 @@ flowchart TB
     ClientJS --> REST
     SocketC <--> SocketS
 
-    REST --> Auth & Market & ChatSvc & PaySvc & TelegramSvc & Disp & Points & BlogSvc & AISvc & Notif & Files
+    REST --> Auth & Market & TenantSvc & ChatSvc & PaySvc & TelegramSvc & Disp & Points & BlogSvc & AISvc & Notif & Files
     SocketS --> ChatSvc & Notif & Market
 
-    Auth & Market & ChatSvc & PaySvc & Disp & Points & BlogSvc & TelegramSvc --> Mongo
-    PaySvc -.->|oracle payment_quotes when enabled| PG
+    Auth & Market & TenantSvc & ChatSvc & PaySvc & Disp & Points & BlogSvc & TelegramSvc --> PG
     Auth & PaySvc & Notif --> RedisDB
     Files --> Disk
 
@@ -96,6 +101,7 @@ flowchart TB
     PaySvc -.tx fetch.-> Alchemy
 
     TelegramSvc <--> TelegramAPI
+    TenantSvc <--> TelegramAPI
     TelegramAPI -.webhook.-> TelegramSvc
     Auth --> TelegramAPI
     Notif --> SMTP
@@ -151,7 +157,7 @@ Chat is built on Socket.IO rooms. Every entity that needs live updates gets its
 - `buyer-<id>` / `seller-<id>` — marketplace-wide updates
 - `sellers` / `buyers` — global broadcast pools
 
-Messages persist to MongoDB through the `Chat` model and are rate-limited per chat (`chatRateLimiter.ts`). The frontend's `socket/` directory wraps `socket.io-client` and exposes typed event hooks to React components.
+Messages persist through the backend chat repository layer and are rate-limited per chat (`chatRateLimiter.ts`). The frontend's `socket/` directory wraps `socket.io-client` and exposes typed event hooks to React components.
 
 ### Notifications — [[Notifications]]
 
@@ -164,7 +170,7 @@ Push and SMS are tracked as **planned** in `backend/TODO.md`.
 
 ### Disputes — [[Dispute System]]
 
-When a deal goes wrong (see [[Glossary#Dispute]]), either party can open a dispute. The backend creates a **three-way chat** between buyer, seller, and admin, opens a `Dispute` document with a structured `timeline[]` and `evidence[]`, and can assign the dispute to an admin via `assignAdmin()`. Resolution can be `refund | replacement | compensation | warning_seller | ban_seller | no_action` in the current Mongoose model.
+When a deal goes wrong (see [[Glossary#Dispute]]), either party can open a dispute. The backend creates a **three-way chat** between buyer, seller, and admin, opens a dispute record with a structured timeline/evidence model, and can assign the dispute to an admin. Resolution can be `refund | replacement | compensation | warning_seller | ban_seller | no_action` in the current service surface.
 
 > [!note] State alignment gap
 > The dispute module exists now, but its model still uses the legacy `pending | in_progress | resolved | ...` enum. [[Funds Ledger and Escrow State Machine Specification]] defines the canonical future enum and financial side effects.
@@ -226,6 +232,6 @@ OpenAI (model configurable per call) is exposed through `/api/ai/*`. The current
 - [[Roles & Personas]] — who does what in the system.
 - [[Glossary]] — a domain dictionary you will want open in another pane.
 - [[01 - Architecture]] — service boundaries, module layout, and deployment topology.
-- [[02 - Data Models]] — MongoDB collections and field-by-field schemas.
+- [[02 - Data Models]] — PostgreSQL/Drizzle tables plus legacy model references where still relevant.
 - [[03 - API Reference]] — every endpoint, its payload, and its auth requirements.
 - [[04 - Flows]] — diagrammed user journeys for every major use case.