14 KiB
14 KiB
title, tags, created
| title | tags | created | ||||
|---|---|---|---|---|---|---|
| Tech Stack |
|
2026-05-23 |
Tech Stack
[!info] Versions Versions below are pulled from the current integration worktrees. Backend baseline:
integrate-main-into-development@3a50dc4, package version2.6.79. Frontend integration worktree observed at2.7.19. Where a^range is declared in package.json, the declared minimum is shown — the lockfile may have resolved a newer patch.
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 current integration package observed locally is amn-frontend@2.7.19 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.79, an Express 5 server in TypeScript backed by MongoDB (Mongoose), Redis, Socket.IO, and a Postgres/Drizzle migration layer. MongoDB remains the primary runtime store; Postgres is currently used for migrations/backfill tooling and conditional oracle quote persistence. It owns all integrations with Request Network, AMN scanner, EVM chains, OpenAI, Google OAuth, Telegram, SMTP, and custody/signing controls.
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 | Active — auth 10/15min, payment 30/15min, AI 20/15min, global 100/15min |
| 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 (Request Network, blockchain/RPC helpers) | Integration calls |
| @babel/runtime | ^7.27.6 | Babel runtime helpers | Compiled output |
[!warning] React in backend dependencies
reactandreact-domare listed inbackend/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; seebackend/TODO.md.
Database & cache
| Tool | Version | Purpose | Where used |
|---|---|---|---|
| mongoose | ^8.16.4 | MongoDB ODM | backend/src/models/** |
| pg | ^8.16.0 | PostgreSQL driver | backend/src/db/client.ts, Drizzle runtime |
| drizzle-orm | ^0.44.1 | Type-safe SQL ORM | backend/src/db/schema/**, repositories |
| drizzle-kit | ^0.31.1 | Migration CLI | backend/src/db/migrations/**, drizzle.config.ts |
| decimal.js | ^10.5.0 | Decimal-exact money/oracle math | payment quote engine |
| 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 runtime store | Connection string via env |
| Database | PostgreSQL 18 + Drizzle | Migration target, backfill/verify store, conditional payment_quotes |
PG_URL / MIGRATION_PG_URL; not a full cutover yet |
| 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 |
|---|---|---|
| Request Network | On-chain payment request protocol -- creates payment requests, supports in-house checkout metadata, signs webhooks | backend/src/services/payment/requestNetwork/ + adapters |
| Derived destination wallets | Per-(buyer, sellerOffer, chainId) receiving addresses plus sweep orchestration |
backend/src/services/payment/wallets/ |
| Transaction Safety Provider | Confirms tx hash, recipient, token, amount, confirmation depth, and future AML result before escrow credit | backend/src/services/payment/safety/ |
| Trezor / future Safe multisig | Hardware-backed admin signing today; Safe multisig target in custody roadmap | backend/src/services/trezor/, PRD - Decentralized Custody and Smart-Contract Escrow Roadmap |
| SHKeeper | Historical payment rail retained in documentation for migration context | legacy docs only |
| DePay | Historical/drop-in Web3 widget docs retained for context | frontend historical docs |
| 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) |
| Telegram Bot API + Mini App | Bot commands, inline keyboards, webhook updates, Mini App launch surface, Login Widget | backend/src/services/telegram/, frontend/src/app/telegram/, frontend/src/utils/telegram-webapp.ts |
| 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
Paymentmodel are the three areas most sensitive to drift. After bumping a major version, run bothyarn typecheckand the full test suites (yarn testin backend,yarn testandyarn test:e2ein 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.