docs: sync from backend 19f7eb9, frontend 60ee6fb — Task #10 AML screening

01 - Architecture/Backend Architecture.md

@@ -44,7 +44,8 @@ backend/src/
 │   │   ├── migration/          # Legacy data backfill utilities
 │   │   ├── observability/      # Logging and incident controls
 │   │   ├── requestNetwork/     # Request Network pay-in, routes, webhook signature
-│   │   └── shkeeper/           # SHKeeper API, webhook, payout
+│   │   ├── safety/             # Transaction Safety Provider + confirmation thresholds
+│   │   └── wallets/            # Derived destination wallets + sweep orchestration
 │   ├── points/                 # Loyalty points, levels, redemption
 │   ├── redis/                  # Redis client, cache helpers
 │   ├── telegram/               # Bot webhook, Mini App session, identity linking, notifications
@@ -125,17 +126,19 @@ The full route table mounted by `app.ts`:
 | `/api/marketplace/categories` | `services/marketplace/controllerRoutes.ts` | public read | Category list |
 | `/api/marketplace/shop-settings` | `services/marketplace/shopSettingsController.ts` | JWT (seller) | Shop profile |
 | `/api/payment` | `services/payment/paymentControllerRoutes.ts` + `paymentRoutes.ts` | JWT | Payment CRUD, health, export |
-| `/api/payment/decentralized` | `services/payment/decentralizedPaymentRoutes.ts` | mixed | Web3 save, verify, receiver |
-| `/api/payment/shkeeper` | `services/payment/shkeeper/shkeeperRoutes.ts` | mixed | Intents, webhook, release, refund, config |
-| `/api/payment/shkeeper/payout` | `services/payment/shkeeper/shkeeperPayoutRoutes.ts` | JWT (seller/admin) | Withdraw to wallet |
-| `/api/payment/request-network` | `services/payment/requestNetwork/requestNetworkRoutes.ts` | HMAC sig | Request Network pay-in creation, Secure Payment Page, webhooks |
+| `/api/payment/decentralized` | `services/payment/decentralizedPaymentRoutes.ts` | mixed | Legacy/manual Web3 save, verify, receiver |
+| `/api/payment/request-network` | `services/payment/requestNetwork/requestNetworkRoutes.ts` | mixed + HMAC sig on webhook | Request Network pay-in creation, in-house checkout rehydrate, webhooks |
+| `/api/payment/derived-destinations` | `services/payment/wallets/derivedDestinationRoutes.ts` | JWT (admin) | Derived address list, sweeps, cron, config health |
+| `/api/admin/rn/networks` | `services/payment/requestNetwork/networkRegistryRoutes.ts` | JWT (admin) | Supported RN chain/token registry |
+| `/api/admin/settings/confirmation-thresholds` | `services/admin/confirmationThresholdRoutes.ts` | JWT (admin) | Runtime min-confirmation thresholds |
+| `/api/admin/payments/awaiting-confirmation` | `services/admin/awaitingConfirmationRoutes.ts` | JWT (admin) | Payments blocked on safety confirmations |
 | `/api/telegram` | `services/telegram/telegramRoutes.ts` | mixed (some JWT, webhook uses secret-token) | Mini App verify/session, identity link/unlink, bot webhook |
 | `/api/chat` | `services/chat/chatRoutes.ts` | JWT | Conversations, messages |
 | `/api/notification` | `services/notification/notificationRoutes.ts` + `notificationControllerRouter` | JWT | List, mark read |
-| `/api/dispute` | `services/dispute/disputeRoutes.ts` | JWT | **Not implemented** — planned |
-| `/api/blog` | `services/blog/blogRoutes.ts` | mixed | **Not implemented** — planned |
-| `/api/admin` | `services/admin/adminRoutes.ts` | JWT (admin) | **Not implemented** — planned |
-| `/api/points` | `services/points/pointsRoutes.ts` | JWT | **Not implemented** — planned |
+| `/api/disputes` | `routes/disputeRoutes.ts` + `services/dispute/disputeRoutes.ts` | JWT | Dispute CRUD plus release-hold helpers |
+| `/api/blog` | `services/blog/blogRoutes.ts` | mixed | Public reads, admin writes |
+| `/api/admin/cleanup` | `services/admin/dataCleanupRoutes.ts` | JWT (admin) | Data cleanup operations |
+| `/api/points` | `services/points/pointsRoutes.ts` | JWT | Points, levels, referrals |
 | `/api/ai` | `services/ai/aiRoutes.ts` | JWT | OpenAI-backed helpers |
 | `/api/files` | `services/file/fileRoutes.ts` | JWT | Multipart upload |
 | `/api/email` | `services/email/emailRoutes.ts` | JWT | Email dispatch |
@@ -253,9 +256,12 @@ Full table in [[Environment Variables]]. Critical ones:
 | `JWT_EXPIRES_IN` | `7d` | |
 | `REFRESH_TOKEN_EXPIRES_IN` | `30d` | |
 | `FRONTEND_URL` | `http://localhost:3000` | CORS origin |
-| `SHKEEPER_API_URL` | `https://pay.amn.gg` | |
-| `SHKEEPER_API_KEY` | required | |
-| `SHKEEPER_WEBHOOK_SECRET` | required | HMAC key |
+| `REQUEST_NETWORK_API_BASE_URL` | `https://api.request.network` | Request Network API |
+| `REQUEST_NETWORK_API_KEY` | required | Request Network API credential |
+| `REQUEST_NETWORK_WEBHOOK_SECRET` | required | Webhook HMAC key |
+| `PAYMENT_LEDGER_ENFORCEMENT` | `false` | Target `true` before launch-scale releases |
+| `TRANSACTION_SAFETY_*` | required for payments | Confirmation, transfer-match, and AML controls |
+| `DERIVED_DESTINATION_SWEEP_SIGNER` | `build-only` | Target hardware/Safe-backed signer |
 | `SMTP_*` | required | Nodemailer |
 | `OPENAI_API_KEY` | required | |
 
@@ -279,7 +285,7 @@ Redis client (in `src/services/redis/`) provides:
 
 The codebase has no dedicated queue runner — scheduled / async work is triggered inline from request handlers and uses `setTimeout` / `setInterval` patterns where needed (e.g., delayed retries). Consider introducing Bull / BullMQ if you grow:
 
-- Payment status reconciliation (polling SHKeeper for stragglers)
+- Request Network webhook replay/reconciliation and derived-destination balance checks
 - Notification email digests
 - Auto-release escrow timers
 - Token / refresh-token cleanup
@@ -295,7 +301,7 @@ Jest test suites in `backend/__tests__/`:
 | `models.test.ts` | Schema validation, virtuals, hooks |
 | `payment-services.test.ts` | Payment orchestration logic |
 | `complete-backend.test.ts` | Cross-service integration |
-| `shkeeper-backend.test.ts` | SHKeeper service + webhook |
+| Request Network / payment tests | Request Network adapter, webhook signature, ledger, release/refund orchestration |
 
 Run with `npm run test:all`. CI runs the same. Reach for `npm run test:models`, `npm run test:payment`, etc. when iterating on a slice.
 
@@ -310,7 +316,8 @@ Run with `npm run test:all`. CI runs the same. Reach for `npm run test:models`,
 | `src/shared/utils/response-handler.ts` | Standard response shape |
 | `src/shared/middleware/auth.ts` | JWT verify + RBAC |
 | `src/infrastructure/socket/socketService.ts` | All socket plumbing |
-| `src/services/payment/shkeeper/shkeeperWebhook.ts` | Webhook signature scheme |
+| `src/services/payment/requestNetwork/requestNetworkRoutes.ts` | Request Network checkout and webhook route |
+| `src/services/payment/ledger/fundsLedgerService.ts` | Immutable payment ledger writes |
 | `src/services/marketplace/PurchaseRequestService.ts` | Core marketplace state machine |
 | `src/services/auth/authService.ts` | Auth flows, lockout, hashing |
 | `src/models/User.ts` | Central entity with role/preferences |
@@ -325,4 +332,4 @@ Run with `npm run test:all`. CI runs the same. Reach for `npm run test:models`,
 - [[Real-time Layer]] — Socket.IO room model
 - [[Security Architecture]] — JWT, passkeys, webhook HMAC
 - [[Data Model Overview]] — entity-relationship map
-- [[Authentication Flow]] · [[Payment Flow - SHKeeper]] · [[Dispute Flow]]
+- [[Authentication Flow]] · [[Escrow Flow]] · [[Dispute Flow]]