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

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

Browse Source
This commit is contained in:
Siavash Sameni
2026-05-28 20:35:38 +04:00
parent fd2aa71ef4
commit ddc0434819
34 changed files with 709 additions and 453 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
01 - Architecture/System Architecture.md
View File

@@ -24,7 +24,8 @@ flowchart LR
BE[Express Backend<br/>+ Socket.IO<br/>:5001]
Mongo[(MongoDB 8)]
Redis[(Redis 8)]
SHK[SHKeeper<br/>Crypto Gateway]
RN[Request Network<br/>Pay-in + webhooks]
CFWorker[Durable webhook ingress<br/>roadmap]
SMTP[SMTP<br/>Nodemailer]
OAI[OpenAI API]
BC[Blockchain RPC<br/>Alchemy / WalletConnect]
@@ -37,8 +38,9 @@ flowchart LR
FE -.->|Socket.IO| BE
BE --> Mongo
BE --> Redis
BE -->|Pay-in / Pay-out| SHK
SHK -.->|Webhook HMAC| BE
BE -->|Pay-in intent / status| RN
RN -.->|Signed webhook| CFWorker
CFWorker -.->|Forward / replay| BE
BE --> SMTP
BE --> OAI
FE -->|Wallet Connect| BC
@@ -142,25 +144,29 @@ Mutations follow optimistic-then-confirm:
### 5.3 Webhook path (inbound)
External services (SHKeeper) POST to `/api/payment/shkeeper/webhook`. The backend verifies HMAC signature, updates the `Payment` document, advances any linked `PurchaseRequest`/`SellerOffer` state, and emits Socket.IO events to both buyer and seller rooms.
External services POST payment callbacks to provider-specific webhook routes. The current primary path is Request Network at `/api/payment/request-network/webhook`; the target architecture puts a durable ingress worker in front of the backend so raw delivery evidence can be replayed after outages. The backend remains the trust oracle: it verifies signatures, deduplicates deliveries, applies Transaction Safety Provider checks, updates ledger/payment state, and emits Socket.IO events to both buyer and seller rooms.
```mermaid
sequenceDiagram
participant SHK as SHKeeper
participant RN as Request Network
participant WK as Durable ingress worker
participant BE as Backend
participant DB as MongoDB
participant Buyer
participant Seller
SHK->>BE: POST /api/payment/shkeeper/webhook<br/>X-Signature: HMAC-SHA256
BE->>BE: verifySignature(body, header, SHKEEPER_WEBHOOK_SECRET)
BE->>DB: Payment.updateOne({providerPaymentId}, {status:"completed"})
BE->>DB: PurchaseRequest.updateOne(..., {status:"funded"})
RN->>WK: POST signed webhook<br/>delivery id + raw body
WK->>WK: Store immutable delivery evidence
WK->>BE: Forward / replay webhook
BE->>BE: Verify RN signature + idempotency
BE->>BE: Transaction Safety Provider checks tx hash, recipient, token, amount, confirmations
BE->>DB: Append ledger entry + Payment escrowState="funded"
BE->>DB: PurchaseRequest.updateOne(..., {status:"payment"})
BE-->>Buyer: socket emit "payment:status-updated"
BE-->>Seller: socket emit "request:funded"
BE-->>SHK: 200 OK
BE-->>WK: 200 OK
```
See [[Payment Flow - SHKeeper]] for the full sequence.
See [[PRD - Request Network In-House Checkout]] and [[Request Network Integration Constraints]] for the full Request Network sequence.
---