82 lines
8.0 KiB
Markdown
82 lines
8.0 KiB
Markdown
---
|
|
title: Introduction
|
|
tags: [overview, introduction, mission, product]
|
|
created: 2026-05-23
|
|
---
|
|
|
|
> [!note] 2026-05-24 Audit Remediation
|
|
> A platform-wide security and documentation alignment audit was completed on 2026-05-24 (Subtask 2.7). Key changes reflected in this vault:
|
|
> - **Authentication enforced** on all financial and marketplace endpoints; previously unauthenticated decentralized payment routes now require Bearer JWT.
|
|
> - **Rate limiting restored** in `backend/src/app.ts` with four tiers (global 100/15 min, auth 10/15 min, payment 30/15 min, AI 20/15 min).
|
|
> - **Passkeys hardened** — challenge consumption is now single-use with immediate deletion, 5-minute expiry, and replay-attack protection.
|
|
> - **Web3 verification real** — `BSCTransactionVerifier` performs on-chain `eth_getTransactionReceipt` validation with confirmation counting.
|
|
> - **Socket.IO auth enforced** — all socket connections require a valid JWT; room joins enforce strict ownership/participation checks.
|
|
> - **Dispute holds** now exist in the backend through the dispute/release-hold service; remaining work is canonical state-machine alignment and stronger release/refund policy enforcement.
|
|
> - **Data model docs aligned** with actual Mongoose schemas (Payment provider/escrowState enums, User model omissions documented).
|
|
|
|
# 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 now routes primary stablecoin pay-in through Request Network with an Amanat-rendered wallet checkout. The buyer keeps custody of their crypto until they sign the on-chain payment, while the platform keeps settlement, safety checks, and dispute resolution in one auditable flow.
|
|
|
|
> [!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. **Request Network in-house checkout.** Every order can be paid through an Amanat-rendered Web3 checkout that builds Request Network-compatible transactions directly in the buyer's wallet. The hosted Request Network page remains a fallback, while the app keeps Rabby/MetaMask UX, chain choice, transaction safety checks, and escrow state in-house.
|
|
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/2.7.x** across the integration worktrees, with backend `integrate-main-into-development@3a50dc4` at `2.6.79`. The core escrow loop, real-time chat, multi-language UI, dispute system, points programme, and blog are all live. Active work focuses on Request Network/AMN scanner hardening, Postgres migration readiness, oracle/depeg quote protection, durable webhook ingress, derived-destination custody, admin signing, and a more granular permissions matrix. The Postgres status lives in [[Postgres Runtime Cutover Status]]; the custody/smart-contract strategy lives in [[PRD - Decentralized Custody and Smart-Contract Escrow Roadmap]].
|