239 lines
14 KiB
Markdown
239 lines
14 KiB
Markdown
---
|
|
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 Request Network, 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
|
|
> `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 |
|
|
|---|---|---|
|
|
| **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 `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.
|