nick-doc/00 - Overview/Glossary.md

title, tags, created

title	tags	created
Glossary	overview glossary definitions terminology	2026-05-23

Glossary

[!info] How to read this page Terms are listed alphabetically. Where a term is also the subject of its own doc, the heading links there. When a term references another glossary entry, it is shown as plain bold rather than a wikilink — flip back here as needed.

---

Admin

[!info] Definition A user with role: "admin" and full read/write access to every part of the platform — moderation, payments, disputes, content. Created at boot via backend/src/infrastructure/database/init-admin.ts. See Roles & Personas.

Buyer (User)

[!info] Definition A user with role: "buyer". Posts Purchase Requests and accepts Seller Offers. The default role assigned at signup. UI label: "User".

Category

[!info] Definition A taxonomy node used to classify Purchase Requests and templates. Sellers can flag themselves as a preferred seller in a category. Backed by the Category model (backend/src/models/Category.ts); seeded via seedCategories.ts.

Chat

[!info] Definition A multi-party real-time conversation persisted in MongoDB (Chat model) and streamed over Socket.IO. Chats are scoped to a Purchase Request, a Dispute, or a direct support thread. Per-chat rate limiting is enforced by chatRateLimiter.ts.

DePay

[!info] Definition A drop-in Web3 payment widget (@depay/widgets) used on the frontend to let buyers pay directly from their own wallet on supported EVM chains. The transaction is signed in the wallet, broadcast to the chain, and verified server-side. See Payments Overview.

Delivery Code

[!info] Definition A six-digit one-time code generated when a physical order ships. The buyer reads it to the courier (or the seller types it into the app at handoff) to confirm receipt and release escrow. Stored on PurchaseRequest.deliveryInfo.deliveryCode with deliveryCodeExpiresAt and a usage audit trail (backend/src/models/PurchaseRequest.ts).

Dispute

[!info] Definition A formal complaint opened by either party when a deal goes wrong. Creates a three-way chat (buyer, seller, admin) and a Dispute document with a structured timeline[], evidence[], and resolution. Categories: product_quality | delivery_delay | wrong_item | payment_issue | seller_behavior | other. Outcomes: refund | replacement | compensation | warning_seller | ban_seller | no_action. See backend/src/models/Dispute.ts.

Escrow

[!info] Definition The custodial period during which buyer funds are held by the platform (SHKeeper or the smart contract layer) after payment but before release to the seller. Escrow guarantees the seller will be paid if they deliver, and guarantees the buyer can be refunded if they do not. The defining feature of Amn.

Idempotency

[!info] Definition The property that the same request (identified by an idempotency key) can safely be retried without performing the underlying operation more than once. Critical for payment webhooks — SHKeeper may deliver the same webhook several times if it does not receive a 200 quickly. Amn enforces idempotency in PaymentCoordinator and at the model level via unique constraints on transaction hashes.

JWT (Access / Refresh)

[!info] Definition JSON Web Tokens issued by the auth service. Access tokens are short-lived and carried on every authenticated request in the Authorization: Bearer header. Refresh tokens are longer-lived, stored on the User document, and exchanged for a new access token without re-prompting credentials. Rotated on every refresh.

Level

[!info] Definition A user tier derived from accumulated points. Configured in LevelConfig (backend/src/models/LevelConfig.ts). Higher levels unlock perks such as reduced fees or higher-priority placement.

Negotiation

[!info] Definition The back-and-forth between a buyer and a seller after an offer is submitted but before it is accepted. Implemented as standard chat messages in the request's chat room. A purchase request enters the in_negotiation status when at least one offer exists and discussion is active.

Notification

[!info] Definition A platform event delivered to a user, either in-app (via Socket.IO to the user's personal room) or by email (nodemailer). Persisted as Notification documents so they can be read on subsequent sessions. Categories include offer_received, payment_confirmed, dispute_update, and more.

Owner

[!info] Definition The UI label for a Seller. They "own" a shop. Synonym; same underlying role: "seller".

Passkey

[!info] Definition A WebAuthn credential bound to a device (platform or cross-platform). Replaces passwords for fast biometric login. Multiple passkeys per user supported (User.passkeys[] in backend/src/models/User.ts:125). See Authentication Flow.

Pay-in

[!info] Definition Money flowing into escrow from the buyer. Recorded as Payment.direction: "in". The buyer's choice of pay-in surface (SHKeeper invoice vs. Web3 wallet) is independent of how the payout will be sent.

Pay-in Intent

[!info] Definition The pre-authorisation record created when a buyer commits to paying but the funds have not yet arrived on-chain. Holds the chosen amount, currency, expected wallet address (SHKeeper) or counterparty (DePay), and an expiry. Becomes a confirmed Payment once the chain or webhook confirms settlement.

Payment

[!info] Definition A monetary transaction record. One Payment document covers a pay-in, payout, or refund. Carries direction, provider, blockchain metadata (network, tx hash, confirmations), buyer, seller, and the related purchase request and seller offer. See backend/src/models/Payment.ts.

Payment Coordinator

[!info] Definition A backend module (backend/src/services/payment/paymentCoordinator.ts) that serialises payment state transitions using Redis locks. Prevents the race condition where a webhook and a manual confirmation both try to flip the same payment to paid.

Payout

[!info] Definition Money flowing out of escrow to the seller's wallet. Recorded as Payment.direction: "out". Triggered by admin action after delivery is confirmed; implemented via SHKeeper's payout API (shkeeperPayoutService.ts).

Points

[!info] Definition The loyalty currency. Earned for completed deals, verified referrals, and certain in-app actions. Spent on fee discounts or platform perks. Each grant or spend writes a PointTransaction row for full auditability (backend/src/models/PointTransaction.ts).

Point Transaction

[!info] Definition An immutable record of a single change to a user's point balance — credit or debit, with reason, relatedEntity, and timestamp. The audit trail for the points system.

Preferred Seller

[!info] Definition A seller a buyer can specify on a purchase request to direct the offer notification to a narrower audience. Listed in PurchaseRequest.preferredSellerIds[]. Other sellers may still see the request if it is public.

Purchase Request

[!info] Definition The buyer's brief — what they want to acquire, for how much, by when, and where to deliver. The originating document of every deal. Long status enum walking the entire lifecycle from pending_payment through completed. See backend/src/models/PurchaseRequest.ts.

Referral

[!info] Definition A signup attributed to an existing user via their unique referralCode. Triggered through the /r/:code short URL (backend/src/app.ts:274) which redirects to the signup page with the code pre-filled. Referrer earns points when the referred user completes qualifying actions.

Referral Code

[!info] Definition A short unique string on every user (User.referralCode) that identifies them as a referrer. Used in the /r/:code redirect.

Request Template

[!info] Definition A reusable, pre-configured purchase request that acts like an express checkout. Admin templates appear in a platform catalogue; seller templates are shop-scoped. Clicking "buy" on a template spawns a real PurchaseRequest with the template's defaults. See backend/src/models/RequestTemplate.ts and frontend/template-request-feature.md.

Review

[!info] Definition Post-completion feedback from one party about the other — star rating plus free-form text. Stored in the Review model. Aggregated onto the seller's shop profile.

Role

[!info] Definition The user's identity tier in the system: "admin" | "buyer" | "seller" (backend/src/models/User.ts:94). Drives middleware authorisation. Support is a special admin variant rather than a distinct role.

Seller (Owner)

[!info] Definition A user with role: "seller". Submits offers on requests, runs a shop, receives payouts. Retains all buyer capabilities. UI label: "Owner".

Seller Offer

[!info] Definition A single bid attached to one Purchase Request — price, deliveryTime, status (pending | accepted | rejected | withdrawn), optional validUntil, optional attachments. See backend/src/models/SellerOffer.ts.

Shop

[!info] Definition A seller's public profile + storefront — name, banner, description, payout wallet, response-time SLA, working hours. Configured in ShopSettings and rendered at /dashboard/shops/<id>.

SHKeeper

[!info] Definition A self-hosted crypto payment processor used as Amn's primary custodial pay-in / payout rail. Issues a fresh wallet address per invoice, watches the chain for incoming USDT, and emits a signed webhook on settlement. Lives at https://pay.amn.gg per backend/TODO.md. Integration code under backend/src/services/payment/shkeeper/.

Socket Room

[!info] Definition A logical channel inside the Socket.IO server that scopes events to a subset of connected clients. Rooms used by Amn include user-<id>, chat-<id>, request-<id>, seller-<id>, buyer-<id>, sellers, buyers. See backend/src/app.ts:79-179.

Status (Order)

[!info] Definition The current point in a Purchase Request's lifecycle. Full enum: pending_payment | pending | active | received_offers | in_negotiation | payment | processing | delivery | delivered | confirming | completed | cancelled | seller_paid. Each transition emits a Socket.IO event and may trigger notifications.

Support

[!info] Definition A constrained admin persona dedicated to answering tickets and triaging disputes. Same role enum (admin) but with permission middleware that blocks destructive operations. Seeded as support@amn.gg.

USDT / USDC

[!info] Definition The two stablecoins Amn supports out of the box for pay-in and payout. USDT is the default for SHKeeper invoices; both are supported in offer pricing (SellerOffer.price.currency enum: USD | EUR | IRR | USDT | USDC).

Webhook

[!info] Definition An inbound HTTP POST from an external service notifying Amn of an event. SHKeeper webhooks (/api/payment/shkeeper/webhook) are the most important — they confirm pay-ins. All webhooks are HMAC-signed; verification uses SHKEEPER_WEBHOOK_SECRET. Failed verifications are dropped.

WalletConnect

[!info] Definition An open protocol for connecting wallets to web apps via a QR code or deep link. Configured but currently disabled in frontend/src/web3/config.ts pending an SSR-compatibility fix; MetaMask is the active connector.

Web3 Wallet

[!info] Definition A user-controlled key store (MetaMask, hardware wallet, mobile wallet) that signs blockchain transactions. The frontend talks to wallets through Wagmi + Viem and the user keeps custody of funds right up to the moment of payment.

---

See also

• Introduction — high-level project framing.
• System Overview — how the pieces connect.
• Roles & Personas — who uses what.
• Tech Stack — exact tool versions.
• 02 - Data Models — schemas for every term defined above.
• 04 - Flows — the lifecycle diagrams those terms appear in.