241 lines
14 KiB
Markdown
241 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 from the current integration worktrees. Backend baseline: `integrate-main-into-development@3a50dc4`, package version `2.9.12`. Frontend integration worktree observed at `2.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.9.12`, an Express 5 server in TypeScript backed by PostgreSQL (Drizzle ORM), Redis, and Socket.IO. MongoDB was fully removed in v2.9.x. PostgreSQL is the sole runtime database. 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
|
||
> `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 |
|
||
|---|---|---|---|
|
||
| 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` |
|
||
|
||
### 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 | PostgreSQL 18 + Drizzle | Sole runtime database | 32 tables, 19 migrations (0000–0019); PG_URL required |
|
||
| 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.
|