72 lines
6.6 KiB
Markdown
72 lines
6.6 KiB
Markdown
---
|
|
title: Introduction
|
|
tags: [overview, introduction, mission, product]
|
|
created: 2026-05-23
|
|
---
|
|
|
|
# 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 supports both fiat-style stablecoin escrow (via [[SHKeeper]]) and direct on-chain settlement (via [[DePay]] and the user's own wallet) — meaning the buyer can keep custody of their crypto until the literal moment of release.
|
|
|
|
> [!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. **Dual payment rails.** Every order can be paid through SHKeeper (a self-hosted crypto payment processor that issues a fresh wallet per invoice) *or* through a Web3 wallet connect flow (DePay + Wagmi/Viem + MetaMask). The buyer picks; the escrow logic is identical downstream. See [[Payments Overview]].
|
|
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** across both repositories, on the `development` branch, and tagged "production-ready with minor enhancements" by the project leads. The core escrow loop, real-time chat, multi-language UI, dispute system, points programme, and blog are all live. Active work focuses on UX polish, admin analytics, and a more granular permissions matrix — see `backend/TODO.md` and `frontend/VERSION_0_PREPARATION_TODO.md` for the rolling task list, and [[Roadmap]] (forthcoming) for the strategic view.
|