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

Initial commit: nick docs

Browse Source
This commit is contained in:
moojttaba
2026-05-23 20:35:34 +03:30
commit 0da235ae27
90 changed files with 18268 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

223
00 - Overview/Glossary.md Normal file
View File

@@ -0,0 +1,223 @@
---
title: Glossary
tags: [overview, glossary, definitions, terminology]
created: 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.

71
00 - Overview/Introduction.md Normal file
View File

@@ -0,0 +1,71 @@
---
title: Introduction
tags: [overview, introduction, mission, product]
created: 2026-05-23
---
# Introduction
> [!info] About this vault
> This is the technical documentation for **Amn** (internal code name: *nick app*), a crypto-native escrow marketplace. The vault is organised into numbered sections — start here in `00 - Overview`, then drill into [[01 - Architecture]], [[02 - Data Models]], and so on.
## Mission
**Amn exists to make peer-to-peer commerce trustworthy without forcing either side to trust the other.**
The platform is built on a simple premise that has been hard to pull off in practice: a buyer should be able to describe what they want, receive competing offers from sellers, pay safely, and only release that payment once the goods or service have actually been delivered — all without exposing themselves to chargebacks, payment fraud, or a counterparty who simply disappears. Sellers, in turn, should know that the money they are quoting for is already locked in escrow before they invest time and inventory in fulfilling the order.
Amn solves this with a fully integrated escrow flow, a real-time chat layer that keeps both parties accountable, and a human dispute system that catches the edge cases that automation cannot.
## The problem we solve
Traditional marketplaces tend to live at one of two extremes:
1. **Fully custodial platforms** (Amazon, eBay, Fiverr) take a large cut, dictate every term of the transaction, and freeze funds on a whim. They work, but they are expensive and opaque.
2. **Free-form P2P channels** (Telegram groups, Discord servers, direct DMs) charge nothing but offer no protection at all. The first scam empties the wallet and there is no recourse.
Amn sits between the two. It charges a thin escrow margin, holds funds for only as long as it takes to confirm delivery, and supports both fiat-style stablecoin escrow (via [[SHKeeper]]) and direct on-chain settlement (via [[DePay]] and the user's own wallet) — meaning the buyer can keep custody of their crypto until the literal moment of release.
> [!tip] Why "crypto-native"?
> The escrow rails are built around stablecoins (USDT/USDC) on EVM chains rather than card networks. That means no chargebacks, no 3-day settlement, no geographic restrictions — and a transparent, auditable transaction trail for every step of the deal. See [[Tech Stack]] for the full Web3 surface.
## Target users
Amn serves four distinct personas, each with their own workflows and dashboard. The full breakdown lives in [[Roles & Personas]]; in summary:
- **Buyers** (a.k.a. *Users*) post a **Purchase Request** describing what they want — a physical product, a digital good, a service, or a consultation — and receive bids from sellers.
- **Sellers** (a.k.a. *Owners*) browse open requests, submit **Seller Offers** with their price and delivery time, and run their shop with the help of a personalised dashboard, reviews, and a points-based loyalty programme.
- **Admins** moderate the marketplace, resolve disputes, manage categories and templates, configure payout wallets, and have full visibility into payments and users.
- **Support agents** are a lightweight subset of admin who can join chats, respond to user tickets, and triage disputes without having destructive permissions.
Beyond the four roles, two ambient audiences read the platform:
- **Anonymous visitors** browse the [[Blog]], read public seller profiles, and convert through the referral programme.
- **Search engines** index the public blog and seller shops, which are server-rendered by Next.js for SEO.
## What makes Amn distinctive
A handful of design choices set Amn apart from generic marketplace software:
1. **Dual payment rails.** Every order can be paid through SHKeeper (a self-hosted crypto payment processor that issues a fresh wallet per invoice) *or* through a Web3 wallet connect flow (DePay + Wagmi/Viem + MetaMask). The buyer picks; the escrow logic is identical downstream. See [[Payments Overview]].
2. **Request-first marketplace.** Most platforms list *products*. Amn lists *needs*. Buyers describe what they want and let the market come to them — closer to a reverse auction than a catalogue. The unidirectional flow eliminates the "thousand-listings-with-no-stock" problem.
3. **Request Templates.** Power buyers (and admins) can publish reusable purchase request templates that act like express checkouts — a buyer clicks "I want this" and the order is opened pre-filled. Templates are the bridge between Amn and conventional ecommerce.
4. **First-class i18n with RTL.** The frontend ships with six locales out of the box (English, French, Vietnamese, Chinese, Arabic, Persian) and full right-to-left support — Persian is the default fallback. See `frontend/src/locales/locales-config.ts:36`.
5. **Real-time everything.** Chat, offer notifications, payment status, dispute updates, and presence indicators all flow over Socket.IO rooms. The UI is not just reactive to user input — it is reactive to other users.
6. **Points and referrals built in.** A loyalty system rewards completed deals, referrals, and verified actions. Points unlock fee tiers and are tracked in `PointTransaction` records for full auditability.
7. **AI assist.** OpenAI is wired into the backend to help draft purchase requests, summarise long chat threads, and surface intent classification for the admin dashboard.
8. **Human dispute resolution with a paper trail.** When a deal goes wrong, a three-way chat is opened (buyer, seller, admin) with a full timeline of every action and a structured resolution record. Disputes never disappear into a black box.
## How to read this vault
> [!note] Recommended reading order
> 1. **[[Introduction]]** — you are here.
> 2. **[[System Overview]]** — the 10,000-foot map.
> 3. **[[Tech Stack]]** — every dependency with versions.
> 4. **[[Roles & Personas]]** — who uses what.
> 5. **[[Glossary]]** — definitions of every domain term you will encounter.
>
> After the overview, jump to **[[01 - Architecture]]** for service boundaries, **[[02 - Data Models]]** for schemas, or **[[04 - Flows]]** for end-to-end user journeys.
## Project status at a glance
Amn is at version **2.6.x** across both repositories, on the `development` branch, and tagged "production-ready with minor enhancements" by the project leads. The core escrow loop, real-time chat, multi-language UI, dispute system, points programme, and blog are all live. Active work focuses on UX polish, admin analytics, and a more granular permissions matrix — see `backend/TODO.md` and `frontend/VERSION_0_PREPARATION_TODO.md` for the rolling task list, and [[Roadmap]] (forthcoming) for the strategic view.

237
00 - Overview/Roles & Personas.md Normal file
View File

@@ -0,0 +1,237 @@
---
title: Roles & Personas
tags: [overview, roles, personas, permissions, rbac]
created: 2026-05-23
---
# Roles & Personas
> [!info] Where roles live in code
> The hard role enum is defined in `backend/src/models/User.ts:94` as `"admin" | "buyer" | "seller"`. Support is implemented as an admin variant (a dedicated `support@amn.gg` user is created at bootstrap — see `backend/TODO.md`) rather than as its own enum value. Permission checks live in route middleware and in service guards.
Amn has four user personas. Three are first-class roles in the data model; the fourth (Support) is a special-cased admin with reduced privileges.
```mermaid
flowchart LR
Visitor["Anonymous visitor<br/>(blog, public shops)"]
Buyer["Buyer<br/>(User)"]
Seller["Seller<br/>(Owner)"]
Support["Support<br/>(admin variant)"]
Admin["Admin"]
Visitor -->|signs up| Buyer
Buyer -->|requests seller mode<br/>+ admin approval| Seller
Buyer & Seller -->|opens ticket| Support
Support -->|escalates| Admin
```
---
## Buyer (User)
> [!example] Who they are
> Default new user. Anyone who signs up is a buyer until they request seller status. The persona name in the UI is **"User"** but the model role is `buyer`.
### Primary workflows
- **Browse and search** the public marketplace and request templates.
- **Create a [[Purchase Request]]** describing what they want — product type (physical / digital / service / consultation), budget, urgency, delivery info, attachments. See `backend/src/models/PurchaseRequest.ts`.
- **Review incoming [[Seller Offer]]s**, negotiate over chat, accept the best one.
- **Pay** via [[SHKeeper]] (custodial crypto invoice) or Web3 wallet ([[DePay]] + MetaMask through Wagmi).
- **Track the order** through `processing → delivery → delivered → confirming → completed` states.
- **Confirm receipt** (or let the SLA auto-confirm), leave a review, accrue points.
- **Open a [[Dispute]]** if delivery never lands, item is wrong, or quality is poor.
- **Refer friends** via their personal referral code; earn points per signup that converts.
- **Manage profile**: avatar, addresses, wallet address, passkeys, notification preferences, language.
### Key permissions
- Create, edit, cancel **own** purchase requests.
- Accept / reject offers on **own** requests.
- Initiate payments on **own** requests.
- Open disputes on **own** orders.
- Chat with sellers on **own** open requests and disputes.
- Read public sellers, public requests, public blog.
- **Cannot**: see other users' private data, moderate content, issue payouts, change another user's role.
### Dashboard sections (frontend routes)
The buyer dashboard lives under `/dashboard` (`frontend/src/app/dashboard/`). Notable areas:
- `/dashboard` — overview (recent requests, recent offers received, points balance)
- `/dashboard/request` — list, detail, and create flow for purchase requests
- `/dashboard/request-template` — saved templates and the catalogue of admin templates
- `/dashboard/chat` — all conversations
- `/dashboard/payment` — payment history (in + out) and active invoices
- `/dashboard/disputes` — open and resolved disputes
- `/dashboard/points` — points, levels, referrals
- `/dashboard/account` — profile, security (passkeys), addresses, language
- `/dashboard/post` — read-only blog reader (also public)
> [!tip] See also
> Full buyer playbook in [[User Guide]]. Auth specifics in [[Authentication Flow]].
---
## Seller (Owner)
> [!example] Who they are
> A buyer who has been promoted to `role: "seller"`. The UI sometimes calls them **"Owner"** because they own a shop. Sellers retain all buyer capabilities — they can still post requests of their own.
### Primary workflows
- **Configure shop**: shop name, banner, description, response time SLA, accepted payment methods, payout wallet address. See `backend/src/models/ShopSettings.ts` and `frontend/src/sections/shop-settings/`.
- **Discover requests** through the seller feed (filtered by category and preferred-seller status). Receive live notifications when a relevant request is posted via the `sellers` / `seller-<id>` Socket.IO rooms (`backend/src/app.ts:101-112`).
- **Submit offers** with price, currency (USDT default, USDC, USD, EUR, IRR supported), delivery time, optional attachments and notes.
- **Negotiate** in the per-request chat — bilateral with the buyer until an offer is accepted.
- **Fulfil** the order: ship physical goods (with optional tracking number), or upload/email digital deliverables.
- **Use the [[delivery code]]** for physical handoffs: a six-digit one-time code the buyer reads to the courier to confirm receipt.
- **Receive payout** automatically via SHKeeper to the configured wallet once the order is finalised (admin-triggered batch or per-order based on shop policy).
- **Manage [[Request Templates]]** scoped to their shop — publish "off-the-shelf" offerings buyers can purchase in one click.
- **Engage with reviews and disputes**: respond to reviews, contest disputes, provide evidence.
### Key permissions
- All buyer permissions.
- Create / edit / withdraw **own** seller offers.
- Read all public purchase requests + read-only access to requests where they have an active offer.
- Manage **own** shop settings, payout wallet, business hours.
- Publish [[Request Templates]] scoped to their shop.
- Mark orders as shipped, upload digital deliverables, request delivery codes.
- Respond in disputes they are a party to.
- **Cannot**: see another seller's analytics, edit another seller's shop, moderate the platform.
### Dashboard sections
Seller dashboard reuses the same `/dashboard` shell with extra modules:
- `/dashboard/shops` — public-facing shop browser (also visible to buyers)
- `/dashboard/shop-settings` — edit own shop, payout wallet, working hours
- `/dashboard/request-template` — create / edit shop-scoped templates
- `/dashboard/payment` — receivables, payout history, pending releases
- `/dashboard/disputes` — disputes where the seller is the respondent
> [!tip] See also
> [[Seller Guide]] walks through onboarding, first listing, and payout setup end-to-end. [[Payments Overview]] explains the escrow + payout state machine.
---
## Admin
> [!example] Who they are
> Platform operators with full read/write access. Admins are seeded at startup via `backend/src/infrastructure/database/init-admin.ts`. There is typically one root admin (`admin@amn.gg`) and additional admins promoted through database operations or a dedicated admin-creation endpoint.
### Primary workflows
- **Moderate users**: suspend / unsuspend accounts (`User.status: "active" | "suspended" | "deleted"`, see `backend/src/models/User.ts`), promote buyers to sellers, ban repeat offenders.
- **Moderate marketplace content**: categories (`Category` model), request templates (the canonical platform-wide ones), blog posts.
- **Resolve disputes**: get assigned to disputes, drive them to resolution, choose an outcome (`refund | replacement | compensation | warning_seller | ban_seller | no_action`). See `backend/src/services/dispute/DisputeService.ts`.
- **Operate payments**: trigger payouts, fetch on-chain transactions, manually confirm stuck payments (the manual transaction-hash flow described in `backend/TODO.md`), audit the SHKeeper webhook history (`services/payment/shkeeper/webhookStats.ts`).
- **Configure the platform**: levels (`LevelConfig`), points multipliers, blog seed content, default templates.
- **Run data cleanup**: `/api/admin/cleanup` exposes destructive maintenance utilities (`services/admin/`).
- **Author blog posts** via the TipTap rich-text editor.
- **Monitor health**: SHKeeper status (background health monitor in `app.ts:433`), Redis, MongoDB.
### Key permissions
- **All** read and write across the platform — no row-level scoping.
- Promote users, change roles, suspend accounts.
- Approve / reject seller applications.
- Resolve any dispute, override any payment state.
- Trigger payouts and refunds.
- Edit / delete any blog post, template, or category.
- Run admin cleanup endpoints (irreversible — use with care).
- Access the full Sentry stream and webhook logs.
### Dashboard sections
Admins see the buyer/seller surfaces plus dedicated admin modules (typically under `/dashboard` with admin-only guards, growing into a dedicated `/admin` area in later versions):
- User management (search, suspend, role change)
- Dispute queue with assignment and resolution
- Payment console (manual confirmation, payout dispatch, webhook log)
- Category and template management
- Blog editor (publish / unpublish / featured)
- Platform analytics (TODO — see `backend/TODO.md`)
- Data cleanup utilities
> [!warning] Destructive operations
> `/api/admin/cleanup/*` and direct role mutations are not undoable. Admin actions should be logged to an audit trail. Audit logging is on the roadmap (`backend/TODO.md` → Security Enhancements → Audit Logging).
> [!tip] See also
> [[Admin Guide]] gives the step-by-step for moderation, dispute resolution, and payment operations.
---
## Support
> [!example] Who they are
> A dedicated support persona — the seeded `support@amn.gg` account — that exists to handle user tickets and triage disputes without granting full destructive access. Implemented as an `admin` role with a restricted permission profile applied in middleware (see `backend/TODO.md` → "Support user creation").
### Primary workflows
- **Join existing chats** to assist a buyer or seller in real time.
- **Triage disputes**: read incoming disputes, attach notes, assign to the right admin, set priority.
- **Answer user queries** about payments and orders without performing the payment action itself.
- **Escalate** anything that requires destructive action (refunds, bans, manual payouts) to a full admin.
### Key permissions
- Read access to all user accounts (no PII edits).
- Read access to all disputes and chats.
- Comment / reply in disputes and chats (write access scoped to messages, not resolution).
- **Cannot**: change roles, issue payouts, suspend users, delete content, resolve a dispute, edit settings.
### Dashboard sections
Support sees a stripped-down admin view focused on the inbox:
- Support chat queue
- Dispute triage list
- User lookup (read-only)
- Order lookup (read-only)
---
## Cross-cutting concerns
### Role transitions
| From | To | How | Audit |
|---|---|---|---|
| Anonymous | Buyer | Self-service signup | `User` created |
| Buyer | Seller | Application → admin approval | `User.role` change |
| Buyer / Seller | Admin | Manual DB / boot-time seed | High-risk, manual |
| Admin | Support | Permission profile applied at middleware | Role stays `admin` |
### Permission model
Permissions are enforced at three layers:
1. **Route middleware** (e.g. `requireAuth`, `requireRole('admin')`) — coarse gating on the HTTP layer.
2. **Service guards** — finer ownership checks (e.g. "you can only edit a request whose `buyerId` matches your `userId`").
3. **Frontend route guards** — `frontend/src/auth/guard/` hides UI from users who would be rejected anyway, preventing dead-ends.
### Identity sources
- **Email + password** — primary, with bcrypt hashing.
- **Passkey (WebAuthn)** — multi-device, stored in `User.passkeys[]`.
- **Google OAuth** — server-verified, links by email.
See [[Authentication Flow]] for the full sequence diagram.
### Internationalisation per persona
All four personas see the same six-language UI (en, fr, vi, cn, ar, fa) with the default fallback being Persian (`fa`) — see `frontend/src/locales/locales-config.ts:39`. Date formatting switches to the Jalali calendar in Persian.
---
## See also
- [[Introduction]] — project mission and target audience framing.
- [[System Overview]] — where each persona fits in the architecture.
- [[Authentication Flow]] — how identity becomes a role.
- [[Admin Guide]] — operational handbook for admins and support.
- [[User Guide]] — buyer journey end-to-end.
- [[Seller Guide]] — seller onboarding and shop ops.
- [[Glossary]] — definitions of every domain term referenced above.

216
00 - Overview/System Overview.md Normal file
View File

@@ -0,0 +1,216 @@
---
title: System Overview
tags: [overview, architecture, system-map, mermaid]
created: 2026-05-23
---
# System Overview
> [!info] Scope
> This document gives you a single-page map of Amn from browser to blockchain. It is intentionally broad — the goal is for a new developer to walk away knowing what each major box does and how the boxes talk to each other. For deep dives into any subsystem, follow the wikilinks into [[01 - Architecture]].
## The 10,000-foot view
Amn is a **two-repo system**:
- **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 to MongoDB, caches in Redis, and brokers all external integrations.
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, SHKeeper, or OpenAI — every external interaction is mediated by the backend so that secrets stay on the server.
## System map
```mermaid
flowchart TB
subgraph Client["Client tier"]
Browser["Browser<br/>(Chrome / Safari / mobile)"]
Wallet["Wallet extension<br/>(MetaMask / WalletConnect)"]
end
subgraph FE["Frontend tier — Next.js 16"]
SSR["Next.js SSR / RSC<br/>App Router"]
ClientJS["Client JS<br/>MUI v7 + React 19"]
Wagmi["Wagmi + Viem<br/>Web3 client"]
SocketC["socket.io-client"]
I18n["i18next<br/>6 locales + RTL"]
end
subgraph BE["Backend tier — Node.js / Express 5"]
REST["REST API<br/>/api/*"]
SocketS["Socket.IO server<br/>rooms per user / chat / request"]
Auth["Auth service<br/>JWT + Passkey + Google"]
Market["Marketplace service<br/>Requests, Offers, Templates"]
ChatSvc["Chat service"]
PaySvc["Payment service<br/>+ PaymentCoordinator"]
Disp["Dispute service"]
Points["Points / Referrals"]
BlogSvc["Blog service"]
AISvc["AI service"]
Notif["Notification service"]
Files["File upload<br/>(multer + sharp)"]
end
subgraph Data["Data tier"]
Mongo[("MongoDB<br/>via Mongoose")]
RedisDB[("Redis<br/>cache + locks")]
Disk[("Local disk<br/>/uploads")]
end
subgraph External["External services"]
SHK["SHKeeper<br/>crypto invoicing"]
DePay["DePay widget"]
Chain["EVM chains<br/>BSC / ETH / Polygon"]
SMTP["SMTP<br/>(nodemailer)"]
OpenAI["OpenAI API"]
Google["Google OAuth"]
Sentry["Sentry"]
Alchemy["Alchemy RPC"]
end
Browser --> SSR
Browser <--> ClientJS
ClientJS <--> SocketC
ClientJS --> Wagmi
Wagmi <--> Wallet
Wallet <--> Chain
SSR --> REST
ClientJS --> REST
SocketC <--> SocketS
REST --> Auth & Market & ChatSvc & PaySvc & Disp & Points & BlogSvc & AISvc & Notif & Files
SocketS --> ChatSvc & Notif & Market
Auth & Market & ChatSvc & PaySvc & Disp & Points & BlogSvc --> Mongo
Auth & PaySvc & Notif --> RedisDB
Files --> Disk
PaySvc <--> SHK
SHK -.webhook.-> PaySvc
PaySvc --> Chain
Wagmi --> DePay
DePay --> Chain
PaySvc -.tx fetch.-> Alchemy
Notif --> SMTP
Auth --> Google
AISvc --> OpenAI
BE --> Sentry
FE --> Sentry
```
## Walk-through of each subsystem
### Authentication & identity — [[Authentication Flow]]
Auth is the gate to every authenticated route. Amn supports three login methods in parallel:
- **Email + password (JWT).** Standard `bcrypt`-hashed credentials, access + refresh token pair, six-digit email verification codes, and password reset codes. Source: `backend/src/services/auth/authService.ts`.
- **Passkey (WebAuthn).** Platform and cross-platform authenticators are registered against the user account; multiple devices per user are stored in `User.passkeys[]` (`backend/src/models/User.ts:125`).
- **Google OAuth.** Server-side verification via `google-auth-library`. See `backend/src/services/auth/googleOAuthService.ts`.
Roles are `admin | buyer | seller` (`backend/src/models/User.ts:94`). Role checks happen in route middleware. **Refresh tokens** are stored on the `User` document and rotated.
### Marketplace — [[Marketplace Domain]]
The heart of the platform. Three first-class models drive it:
- **PurchaseRequest** (`backend/src/models/PurchaseRequest.ts`) — the buyer's brief, with productType (`physical_product | digital_product | service | consultation`), budget range, urgency, delivery info (physical or online), and a long status enum that walks the entire deal: `pending_payment → pending → active → received_offers → in_negotiation → payment → processing → delivery → delivered → confirming → completed`.
- **SellerOffer** (`backend/src/models/SellerOffer.ts`) — a single bid attached to a request with `price`, `deliveryTime`, `status`, `validUntil`, and free-form `notes`.
- **RequestTemplate** (`backend/src/models/RequestTemplate.ts`) — a reusable "express checkout" version of a purchase request that can spawn real `PurchaseRequest` instances at click time.
Services live in `backend/src/services/marketplace/` and are exposed through `/api/marketplace/*`. The frontend uses a mix of React Query (`@tanstack/react-query`) and SWR for data fetching, with mutations gated through the actions layer in `frontend/src/actions/`.
### Payments — [[Payments Overview]] / [[SHKeeper Integration]]
Payments are where Amn is most distinctive. The backend supports **three payment surfaces** routed through a common `Payment` model (`backend/src/models/Payment.ts`):
- **SHKeeper** — `/api/payment/shkeeper`. Mounted at `backend/src/app.ts:327`. Issues a fresh wallet address per invoice, polls / webhooks for payment confirmation, and runs through `PaymentCoordinator` to avoid race conditions where a payment status is updated twice. Health is monitored in the background (`shkeeperHealthCheck.ts`, started in `app.ts:433`).
- **Decentralized (Wagmi + DePay)** — `/api/payment/decentralized`. The user signs and sends the transfer from their own wallet; the backend then verifies the transaction on-chain via `blockchainTxFetcher.ts` and the Alchemy SDK.
- **Payout** — `/api/payment/shkeeper/payout`. Admin-triggered release of escrow funds to the seller's wallet once delivery is confirmed.
All three surfaces converge on the same `Payment` record (with `direction: 'in' | 'out' | 'refund'`) and trigger the same downstream events: order status update, notification, points award. **Pending payments are auto-cleaned** by a background timer started in `app.ts:374`.
### Real-time chat — [[Chat System]]
Chat is built on Socket.IO rooms. Every entity that needs live updates gets its own room (see `backend/src/app.ts:79-178`):
- `user-<id>` — personal notifications
- `chat-<id>` — chat room messages, typing indicators, presence
- `request-<id>` — purchase request lifecycle events
- `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.
### Notifications — [[Notifications]]
Two notification channels:
- **In-app** — `Notification` documents pushed over Socket.IO to `user-<id>` rooms; rendered in the frontend's bell-icon drawer.
- **Email** — `nodemailer` + SMTP for verification codes, password resets, and high-importance events. See `backend/src/services/email/`.
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 (`backend/src/services/dispute/DisputeService.ts`) creates a **three-way chat** between buyer, seller, and admin, opens a `Dispute` document with a structured `timeline[]` and `evidence[]`, and assigns the dispute to an admin via `assignAdmin()`. Resolution can be `refund | replacement | compensation | warning_seller | ban_seller | no_action` and is recorded on the dispute itself.
### Points & referrals — [[Points System]]
Each user has an embedded `points` object (`total | available | used | level`) and `referralStats` (`backend/src/models/User.ts`). Every grant or spend writes a `PointTransaction` record for auditability. The points module supplies referral codes (the `/r/:code` short URL in `app.ts:274` redirects to signup), tracks level progression against `LevelConfig`, and exposes the user-facing dashboard through `frontend/src/sections/points/`.
### Blog — [[Blog System]]
A simple admin-authored CMS. `BlogPost` documents support categories, tags, and embedded video via TipTap's rich-text editor on the frontend. Public reads are unauthenticated (`/api/blog/posts`); writes require admin role. Seed data lives in `backend/src/seeds/seedBlogPosts.ts` and runs on dev startup.
### AI — [[AI Assist]]
OpenAI (model configurable per call) is exposed through `/api/ai/*`. The current surface includes purchase-request drafting, chat summarisation, and admin-facing intent classification. Requests are queued from the frontend's `actions/ai*` modules and use streaming where appropriate.
### File uploads
`multer` accepts multipart uploads (max 10 MB body, `app.ts:232`), `sharp` resizes images on the fly, and files land in `/uploads` (mounted as a static directory at `app.ts:260`). In production the path is configurable via `UPLOAD_PATH`.
### Caching, locks & background jobs
**Redis** (`backend/src/services/redis/`) is used for:
- short-lived caches (sessions, marketplace listings)
- locks used by `PaymentCoordinator` to serialise status transitions
- rate-limit counters (currently disabled in code but plumbed in)
**Background workers** run inside the Express process for now — no separate worker tier. Notable timers:
- `startPendingPaymentsCleanup()` — sweeps stale unpaid invoices
- `startShkeeperHealthMonitor()` — pings the SHKeeper instance and surfaces alerts
- Auto-seed logic on startup (gated by `NODE_ENV` and `AUTO_SEED_ON_START`)
## Request lifecycle (the happy path)
> [!example] End-to-end deal walk-through
> 1. Buyer signs in (JWT). UI joins `user-<buyerId>` over Socket.IO.
> 2. Buyer creates a [[Purchase Request]] → `POST /api/marketplace/requests`. The request lands in `pending`/`active`. Sellers in the matching category receive a Socket.IO notification.
> 3. Seller views the request, opens [[Seller Offer]] modal, submits price + delivery time → `POST /api/marketplace/offers`. Buyer sees the offer arrive live.
> 4. Buyer accepts an offer → request moves to `payment`. UI opens the payment selector.
> 5. Buyer picks **SHKeeper** → backend creates a SHKeeper invoice, returns a wallet address + QR code. Buyer pays. SHKeeper webhook hits `/api/payment/shkeeper/webhook`; `PaymentCoordinator` flips `Payment.status = paid` and `PurchaseRequest.status = processing`.
> 6. Seller ships. Buyer confirms delivery (or it auto-confirms after the SLA window). Admin triggers (or schedules) a **payout** → SHKeeper releases USDT to the seller's wallet.
> 7. Both parties leave reviews. Points are awarded. The deal is closed.
>
> If the buyer disputes the delivery, jump to step 7 of the [[Dispute Flow]] instead.
## Cross-cutting concerns
- **Observability** — Sentry is initialised at the very top of `app.ts` (line 2-3) and on the frontend in `sentry.{client,edge,server}.config.ts`. Logs flow through `backend/src/utils/logger.ts`.
- **Security** — `helmet`, CORS scoped to `FRONTEND_URL`, JWT with bcrypt-hashed passwords, role-gated middleware. Rate limiting is plumbed but currently disabled (see `app.ts:227`).
- **Internationalisation** — Six locales (en, fr, vi, cn, ar, fa), with `fa` as default. RTL via `stylis-plugin-rtl`. See `frontend/src/locales/`.
- **Theming** — MUI v7 with a custom theme in `frontend/src/theme/`. Dark mode is on the roadmap.
- **Containerisation** — Docker Compose stacks for dev and prod live in both repos (`docker-compose.dev.yml`, `docker-compose.production.yml`).
## Where to go next
- [[Tech Stack]] — exact versions of every dependency.
- [[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.
- [[03 - API Reference]] — every endpoint, its payload, and its auth requirements.
- [[04 - Flows]] — diagrammed user journeys for every major use case.

233
00 - Overview/Tech Stack.md Normal file
View File

@@ -0,0 +1,233 @@
---
title: Tech Stack
tags: [overview, tech-stack, dependencies, versions]
created: 2026-05-23
---
# Tech Stack
> [!info] Versions
> Versions below are pulled directly from `frontend/package.json` and `backend/package.json` on the `development` branch. Where a `^` range is declared in package.json, the **declared minimum** is shown — the lockfile may have resolved a newer patch. When in doubt, check `yarn.lock` in each repo.
## Frontend stack
The frontend is a Next.js 16 App Router application written in TypeScript. The build is deliberately heavy on best-in-class libraries rather than home-grown solutions: MUI for components, Wagmi for Web3, React Query / SWR for data, Zod for validation, Sentry for errors. The package is `amn-frontend@2.6.5-beta` and requires Node `>=20`.
### Core framework & language
| Tool | Version | Purpose | Where used |
|---|---|---|---|
| Next.js | ^16.1.1 | App Router framework, SSR, RSC, image opt, file-based routing | `frontend/src/app/**` |
| React | ^19.1.0 | UI runtime (concurrent, transitions) | Everywhere |
| react-dom | ^19.1.0 | DOM renderer | Entry / layout |
| TypeScript | ^5.8.3 | Strict typing across the codebase | `tsconfig.json` |
| Node.js | >=20 | Runtime for `next dev`, `next build`, `next start` | `package.json` `engines` |
### UI, theming & icons
| Tool | Version | Purpose | Where used |
|---|---|---|---|
| @mui/material | ^7.1.0 | Component library (buttons, inputs, dialogs) | `frontend/src/components/**` |
| @mui/lab | ^7.0.0-beta.12 | Pre-release MUI components (Timeline, Masonry) | Dispute timeline, layouts |
| @mui/material-nextjs | ^7.1.0 | App Router cache + SSR integration | `frontend/src/app/layout.tsx` |
| @mui/x-data-grid | ^8.4.0 | Admin grids with sorting / filtering | Admin dashboard tables |
| @mui/x-date-pickers | ^8.4.0 | Date + time inputs | Request forms, delivery |
| @mui/x-tree-view | ^8.4.0 | Category and admin trees | Category management |
| @emotion/react | ^11.14.0 | CSS-in-JS engine for MUI | Theme + sx prop |
| @emotion/styled | ^11.14.0 | Styled-component sugar | Custom MUI wrappers |
| @emotion/cache | ^11.14.0 | RTL-aware emotion cache | RTL plugin chain |
| stylis | ^4.3.6 | Emotion's CSS preprocessor | Style pipeline |
| stylis-plugin-rtl | ^2.1.1 | Right-to-left CSS transformation | Persian/Arabic layouts |
| @iconify/react | ^6.0.0 | Iconify icon component (100k+ icons) | Icons everywhere |
| framer-motion | ^12.13.0 | Animations and transitions | Modals, page transitions |
| @fontsource-variable/{inter,dm-sans,nunito-sans,public-sans} | ^5.2.5 | Self-hosted variable fonts | Theme typography |
| @fontsource/barlow | ^5.2.5 | Display font for headlines | Marketing pages |
### Data, state & forms
| Tool | Version | Purpose | Where used |
|---|---|---|---|
| @tanstack/react-query | ^5.83.0 | Server state, mutations, caching | API hooks under `actions/` |
| swr | ^2.3.3 | Lightweight data fetching | Lists, polling endpoints |
| react-hook-form | ^7.56.4 | Form state and validation glue | Every form |
| @hookform/resolvers | ^5.0.1 | Bridges RHF with Zod schemas | Form schemas |
| zod | ^4.0.10 | Runtime + compile-time schema validation | `actions/**/schema.ts` |
| es-toolkit | ^1.38.0 | Modern Lodash alternative | Utility helpers |
| dayjs | ^1.11.13 | Date manipulation | Formatting throughout |
| date-fns-jalali | ^4.1.0-0 | Jalali (Persian) date formatting | Persian locale |
| axios | ^1.11.0 | HTTP client | Backend calls in `actions/` |
### Web3 & crypto
| Tool | Version | Purpose | Where used |
|---|---|---|---|
| wagmi | ^2.15.6 | React hooks for EVM (connect, signer, tx) | `frontend/src/web3/` |
| viem | ^2.31.7 | Low-level EVM client | RPC calls, encoding |
| ethers | ^6.15.0 | Alternative EVM client (legacy paths) | Tx signing helpers |
| @depay/widgets | ^13.0.36 | DePay drop-in payment widget | Wallet checkout |
| alchemy-sdk | ^3.6.1 | Enriched RPC + transaction history | Tx verification |
### Realtime, i18n, rich text
| Tool | Version | Purpose | Where used |
|---|---|---|---|
| socket.io-client | ^4.8.1 | WebSocket transport | Chat, notifications |
| i18next | ^25.2.1 | i18n engine | All translations |
| react-i18next | ^15.5.2 | React bindings for i18next | `useTranslation` hooks |
| i18next-browser-languagedetector | ^8.1.0 | Browser locale detection | Initial language pick |
| i18next-resources-to-backend | ^1.2.1 | Lazy locale loading | `frontend/src/locales/` |
| accept-language | ^3.0.20 | Server-side language negotiation | SSR locale detection |
| @tiptap/{core,react,starter-kit,...} | ^2.12.0 | Rich-text editor (blog, descriptions) | Blog editor |
| lowlight | ^3.3.0 | Code syntax highlighting in TipTap | Blog code blocks |
| react-markdown | 10.1.0 | Markdown rendering | Blog views, chat |
| remark-gfm / rehype-raw / rehype-highlight | latest | Markdown extensions | Blog pipeline |
| turndown | 7.2.0 | HTML → Markdown converter | Blog migration |
### Maps, media, misc UI
| Tool | Version | Purpose | Where used |
|---|---|---|---|
| mapbox-gl | ^3.12.0 | Map rendering | Address picker |
| react-map-gl | ^8.0.4 | React wrapper for Mapbox | Address picker |
| react-apexcharts | ^1.7.0 | Charts and graphs | Admin analytics |
| react-dropzone | ^14.3.8 | Drag-and-drop file upload | Attachments |
| react-phone-number-input | ^3.4.12 | International phone input | Profile, address |
| mui-one-time-password-input | ^5.0.0 | OTP input cells | Email verification |
| embla-carousel + autoplay/auto-scroll | 8.6.0 | Carousels | Marketing, blog hero |
| notistack | ^3.0.2 | Snackbar / toast queue | App-wide notifications |
| sonner | ^2.0.3 | Modern toast library | Newer surfaces |
| nprogress | ^0.2.0 | Top-of-page progress bar | Page transitions |
| qrcode | ^1.5.4 | QR code generation | Wallet QR for invoices |
| simplebar-react | ^3.3.0 | Custom scrollbars | Sidebars, drawers |
| yet-another-react-lightbox | ^3.23.2 | Image lightbox | Gallery viewers |
| autosuggest-highlight | ^3.3.4 | Search match highlighting | Combobox results |
| minimal-shared | ^1.0.11 | Shared theme helpers (from Minimal template) | Theme tokens |
### Observability & tooling
| Tool | Version | Purpose | Where used |
|---|---|---|---|
| @sentry/nextjs | ^10.22.0 | Error + perf monitoring | `sentry.*.config.ts` |
| @playwright/test | ^1.56.1 | E2E test runner | `e2e/` |
| jest | ^29.7.0 | Unit test runner | `__tests__/` |
| @testing-library/react | ^16.3.0 | React component testing | Component tests |
| eslint + perfectionist/import/react plugins | ^9.27.0 | Linting | `eslint.config.mjs` |
| prettier | ^3.5.3 | Formatting | `prettier.config.mjs` |
| @svgr/webpack | ^8.1.0 | SVG → React component loader | Build pipeline |
## Backend stack
The backend is `amn-backend@2.6.3-beta`, an Express 5 server in TypeScript backed by MongoDB (Mongoose), Redis, and Socket.IO. It owns all integrations with SHKeeper, the EVM chains, OpenAI, Google OAuth, and SMTP.
### Core runtime & framework
| Tool | Version | Purpose | Where used |
|---|---|---|---|
| Node.js | (per Dockerfile) | Runtime | `Dockerfile.prod` |
| TypeScript | ^5.8.3 | Strict typing | `tsconfig.json` |
| express | ^5.2.1 | HTTP framework | `backend/src/app.ts` |
| body-parser | ^2.2.0 | Body parsing (legacy fallback) | Body middleware |
| helmet | ^8.1.0 | HTTP security headers | `app.ts:189` |
| cors | ^2.8.5 | Cross-origin policy | `app.ts:194` |
| express-rate-limit | ^8.0.1 | Rate-limit middleware (currently off) | Plumbed in |
| express-validator | ^7.2.1 | Request validation | Auth, marketplace |
| multer | ^2.0.2 | Multipart file uploads | `services/file/` |
| sharp | ^0.34.3 | Image resizing / format conversion | Upload pipeline |
| dotenv | ^17.2.0 | Env var loader | Bootstrap |
| uuid | ^11.1.0 | ID generation | Tokens, ephemeral IDs |
| axios | ^1.11.0 | Outbound HTTP (SHKeeper, blockchain) | Integration calls |
| @babel/runtime | ^7.27.6 | Babel runtime helpers | Compiled output |
> [!warning] React in backend dependencies
> `react` and `react-dom` are listed in `backend/package.json:86-87`. These are vestigial — they slipped in via a tool that shared types and are not used at runtime. Safe to remove during cleanup; see `backend/TODO.md`.
### Database & cache
| Tool | Version | Purpose | Where used |
|---|---|---|---|
| mongoose | ^8.16.4 | MongoDB ODM | `backend/src/models/**` |
| redis | ^5.6.0 | Cache, locks, rate-limit store | `services/redis/`, `app.ts:362` |
| mongodb-memory-server | ^10.2.0 (dev) | In-memory Mongo for tests | `__tests__/` |
### Auth, crypto & validation
| Tool | Version | Purpose | Where used |
|---|---|---|---|
| jsonwebtoken | ^9.0.2 | JWT issue + verify | `services/auth/` |
| bcrypt | ^6.0.0 | Password hashing (native) | Auth service |
| bcryptjs | ^3.0.2 | Pure-JS fallback for bcrypt | Auth fallback |
| google-auth-library | ^10.3.0 | Google OAuth token verification | `googleOAuthService.ts` |
| crypto | ^1.0.1 | Node `crypto` polyfill (legacy package) | Webhook signing |
### Realtime, AI, email
| Tool | Version | Purpose | Where used |
|---|---|---|---|
| socket.io | ^4.8.1 | WebSocket server with rooms | `app.ts:70-179` |
| openai | ^5.10.1 | OpenAI SDK | `services/ai/` |
| nodemailer | ^7.0.5 | SMTP email | `services/email/` |
| @types/nodemailer | ^6.4.17 | Types | dev |
### Blockchain
| Tool | Version | Purpose | Where used |
|---|---|---|---|
| ethers | ^6.15.0 | EVM client | `services/blockchain/` |
| web3 | ^4.16.0 | Alternative EVM client | Legacy paths |
### Observability
| Tool | Version | Purpose | Where used |
|---|---|---|---|
| @sentry/node | ^10.22.0 | Error + perf monitoring | `config/sentry.ts` |
| @sentry/profiling-node | ^10.22.0 | CPU profiling | Sentry init |
### Build & test
| Tool | Version | Purpose | Where used |
|---|---|---|---|
| ts-node | ^10.9.2 | TS execution in dev / seeds | `npm run dev` |
| nodemon | ^3.1.10 | Auto-restart on change | `dev:start` script |
| jest | ^29.7.0 | Unit / integration tests | `__tests__/` |
| ts-jest | ^29.4.0 | TS transform for Jest | jest config |
| supertest | ^7.1.4 | HTTP-level API tests | `__tests__/` |
| eslint | ^9.31.0 | Linting | `eslint.config.js` |
| prettier | ^3.6.2 | Formatting | scripts |
## Infrastructure
| Component | Tool / version | Purpose | Notes |
|---|---|---|---|
| Container engine | Docker + Docker Compose | Dev & prod deployment | `docker-compose.dev.yml`, `docker-compose.production.yml` in each repo |
| Reverse proxy | Nginx (external) | TLS termination, routing | `TRUST_PROXY=true` recognised in `app.ts:64` |
| Database | MongoDB | Primary store | Connection string via env |
| Cache | Redis | Sessions, locks, ephemeral data | Optional — backend boots without it |
| Object storage | Local disk `/uploads` | User uploads | `UPLOAD_PATH` env override |
| Process manager | Docker `restart: unless-stopped` (typical) | Crash recovery | Per compose file |
| CI/CD | Manual + `scripts/auto-version.sh` | Semver bumps + tags | `npm run release:*` |
## External services
| Service | Purpose | Touchpoint in code |
|---|---|---|
| **SHKeeper** | Self-hosted crypto payment processor — issues wallets, watches for incoming USDT, pays out | `backend/src/services/payment/shkeeper/` |
| **DePay** | Drop-in Web3 widget for wallet-to-wallet payment | `@depay/widgets` on frontend |
| **EVM chains** (BSC, Ethereum mainnet, Sepolia, Polygon) | Settlement layer for stablecoin transfers | `frontend/src/web3/config.ts`, backend `blockchain/` |
| **Alchemy RPC** | Hosted EVM RPC + transaction lookup | Frontend `alchemy-sdk`, backend `blockchainTxFetcher.ts` |
| **MetaMask / WalletConnect** | Wallet connectors via Wagmi | `web3/config.ts` (WalletConnect commented out pending SSR fix) |
| **OpenAI** | LLM for drafting / summarising | `backend/src/services/ai/` |
| **Google OAuth** | Federated login | `googleOAuthService.ts` |
| **SMTP** (provider configured per env) | Transactional email | `services/email/` |
| **Sentry** | Error + performance monitoring | Both repos |
| **BSCScan / explorers** | Link-out for tx visualisation | Payment UI |
| **Mapbox** | Maps for address selection | `frontend/src/sections/address/` |
> [!tip] How to upgrade
> Always upgrade frontend and backend together when they share a wire protocol — chat events, Socket.IO room schemas, and the `Payment` model are the three areas most sensitive to drift. After bumping a major version, run both `yarn typecheck` and the full test suites (`yarn test` in backend, `yarn test` and `yarn test:e2e` in frontend) before tagging a release.
## See also
- [[System Overview]] — how all these pieces talk to each other.
- [[Roles & Personas]] — who consumes each part of the stack.
- [[01 - Architecture/Deployment Topology]] — production layout.
- [[07 - Development/Local Setup]] — getting the stack running on your machine.