---
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 | 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 (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/` |
| **Request Network** | On-chain payment request protocol — creates invoices, generates Secure Payment Pages, signs webhooks | `backend/src/services/payment/requestNetwork/` + adapters |
| **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) |
| **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.