nick/nick-doc
3
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

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

Browse Source 
- 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>
This commit is contained in:
Siavash Sameni
2026-06-12 11:42:18 +04:00
parent 18073afb52
commit e52ffce48a
18 changed files with 2619 additions and 1102 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
09 - Audits/Activity Log.md
View File

@@ -2030,4 +2030,12 @@ Added `10 - Services/README.md` index. All docs now reflect current codebase sta
- `fix(tables/audit): remove hardcoded rgba(194,65,12,0.04) hover colors` — replaced with MUI built-in hover across admin tables, points leaderboard, and blog; violates AGENTS.md rule (no inline hex/rgba colors).
- `fix(payment-list): remove fontFamily:var(--amn-sans) from header cells` — hardcoded fontFamily violation removed; inherits theme font correctly.
### 2026-06-08 — nick-doc sync — added sub-project service docs and updated core docs
Added 4 new service docs to `10 - Services/`: backend, frontend, scanner, deployment.
Updated amanat-assist.md to latest version. Updated Telegram Mini App flow doc and Scanner Architecture doc.
Added `10 - Services/README.md` index. All docs now reflect current codebase state as of 2026-06-08.
---
<!-- Add new entries above this line. Newest at top. -->

2
09 - Audits/Audit Index - 2026-05-24.md
View File

@@ -14,6 +14,8 @@ Full-system audit triggered by completion of Telegram first-class auth, Request
| [[Security Audit - 2026-05-24]] | 6 critical · 5 high · 7 medium · 4 low |
| [[Logic Audit - 2026-05-24]] | 4 critical · 5 high · 7 medium · 2 low |
| [[Performance Audit - 2026-05-24]] | 6 high · 8 medium · 4 low |
| [[Multi-Shop Branch Project Scan - 2026-06-10]] | Full nested-repo scan plus `feature/white-label-shops` documentation sync |
| [[Comprehensive Workspace Audit - 2026-06-10]] | Full all-repo security, frontend/backend, deployment, scanner, assist, dependency, and quality audit |
---

64
09 - Audits/Multi-Shop Branch Project Scan - 2026-06-10.md Normal file
View File

@@ -0,0 +1,64 @@
---
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 <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]].