---
title: Amn Marketplace — Documentation Vault
tags: [moc, index]
created: 2026-05-23
---
 vase in app mikham
 
# Amn Marketplace — Documentation Vault

Complete technical & operational documentation for the **Amn** (a.k.a. "nick app") crypto-escrow marketplace platform. This vault is exhaustive enough to **re-implement the system from scratch** with no access to the source code.

> [!info]
> **Repos:** `git@git.manko.yoga:222/nick/{backend,frontend}.git` · **Active backend integration branch:** `integrate-main-into-development` · **Current backend baseline:** `2.6.79` at `3a50dc4` · **Vault generated:** 2026-05-23

---

## How to read this vault

Open this folder in **Obsidian** for the best experience (graph view + wikilinks + Mermaid rendering). It also reads as plain Markdown anywhere.

Suggested reading paths:

- **New developer** → `00 Overview` → `01 Architecture` → `07 Development/Local Setup` → start coding.
- **Re-implementer** → `00 Overview` → `02 Data Models` → `03 API Reference` → `04 Flows` → `01 Architecture` for plumbing details.
- **Designer** → `00 Overview` → `05 Design System` → `01 Architecture/Frontend Architecture`.
- **Product / PM** → `00 Overview` → `04 Flows` → `06 Usage`.
- **Operator / DevOps** → `00 Overview` → `01 Architecture/Infrastructure` → `08 Operations`.
- **Support staff** → `06 Usage/Support Guide` + `00 Overview/Glossary` + relevant flow docs.

---

## 00 — Overview

Project context, the cast of characters, and shared vocabulary.

- [[Introduction]] — mission, problem, distinctive design choices
- [[System Overview]] — bird's-eye system map with Mermaid diagram
- [[Tech Stack]] — every dependency with version + role
- [[Roles & Personas]] — Buyer / Seller / Admin / Support and what each does
- [[Glossary]] — 38 alphabetised terms

## 01 — Architecture

How the system is composed at every layer.

- [[System Architecture]] — end-to-end topology + request lifecycle
- [[Backend Architecture]] — Express 5 + Mongoose + Socket.IO module map, plus current Postgres migration layer status
- [[Database Strategy - Mongo vs Postgres Assessment]] — current Mongo primary posture and Postgres cutover assessment
- [[Frontend Architecture]] — Next.js 16 App Router + provider tree
- [[Request Network Integration Constraints]] — current RN integration constraints and rollout gates
- [[PRD - Decentralized Custody and Smart-Contract Escrow Roadmap]] — custody decentralization and smart-contract decision roadmap
- [[Infrastructure]] — Docker images, compose stacks, registry, Watchtower
- [[Real-time Layer]] — Socket.IO rooms, events, scaling notes
- [[Security Architecture]] — auth layers, RBAC, HMAC, hardening checklist

## 02 — Data Models

Per-entity Mongoose schemas — fields, relationships, state machines.

- [[Data Model Overview]] — ER-style map + reading order
- [[Postgres Runtime Cutover Status]] — what is actually using Postgres vs still Mongo-backed on `integrate-main-into-development`
- Core entities: [[User]] · [[PurchaseRequest]] · [[SellerOffer]] · [[Payment]] · [[Chat]] · [[Notification]] · [[Dispute]]
- Marketplace extras: [[RequestTemplate]] · [[ShopSettings]] · [[Category]] · [[Review]]
- User extras: [[Address]] · [[TempVerification]]
- Loyalty: [[PointTransaction]] · [[LevelConfig]]
- Content: [[BlogPost]]

## 03 — API Reference

Every endpoint, grouped by service. Auth, request/response shapes, errors, socket events.

- [[API Overview]] — base URLs, envelope, pagination, conventions
- Auth & users: [[Authentication API]] · [[User API]]
- Marketplace: [[Marketplace API]]
- Payments: [[Payment API]]
- Real-time / messaging: [[Chat API]] · [[Notification API]] · [[Socket Events]]
- Disputes & ratings: [[Dispute API]]
- Content: [[Blog API]]
- Admin & ops: [[Admin API]]
- Loyalty: [[Points API]]
- Utility: [[File API]] · [[AI API]]
- Errors: [[Error Codes]]

## 04 — Flows

End-to-end narratives for every user-visible interaction, with Mermaid sequence/state diagrams.

**Identity**
- [[Authentication Flow]] · [[Registration Flow]] · [[Google OAuth Flow]] · [[Passkey (WebAuthn) Flow]] · [[Password Reset Flow]]

**Marketplace**
- [[Purchase Request Flow]] · [[Seller Offer Flow]] · [[Negotiation Flow]]

**Money**
- [[PRD - Request Network In-House Checkout]] · [[Payment Flow - DePay & Web3]] · [[Escrow Flow]] · [[Payout Flow]] · [[PRD - Decentralized Custody and Smart-Contract Escrow Roadmap]]

**Resolution**
- [[Dispute Flow]] · [[Delivery Confirmation Flow]] · [[Rating Flow]]

**Engagement**
- [[Chat Flow]] · [[Notification Flow]] · [[Referral Flow]]

## 05 — Design System

The visual & UX language of the frontend.

- [[Design System Overview]] — philosophy, tokens, layering
- [[Theme Configuration]] — MUI theme structure
- [[Typography]] — type scale & font loading
- [[Colors]] — palette tokens + contrast
- [[Components]] — inventory of reusable components
- [[Layouts]] — auth / dashboard / main layouts
- [[Internationalization & RTL]] — i18n + bidi rendering
- [[Iconography]] — Iconify usage rules
- [[Settings & Theming]] — user-controllable visual axes

## 06 — Usage

End-user guides — one per role.

- [[User Guide]] (Buyer)
- [[Seller Guide]] (Owner)
- [[Admin Guide]]
- [[Support Guide]]

## 07 — Development

For engineers contributing to the codebase.

- [[Local Setup]] — get the system running on your machine
- [[Environment Variables]] — unified env catalog (both repos)
- [[Project Structure]] — side-by-side folder map
- [[Coding Standards]] — cursor-rules summary + commit conventions
- [[Testing]] — Jest, RTL, Playwright
- [[Scripts]] — every CLI utility (seeds, build, deploy, repair)
- [[Git Workflow]] — branch model + tag strategy

## 08 — Operations

For engineers / SREs running the system in production.

- [[Deployment]] — first-deploy runbook
- [[Docker Setup]] — image & compose breakdown
- [[CI-CD Pipeline]] — Gitea workflows + secrets
- [[Database Operations]] — direct DB ops (Mongo, Redis)
- [[Monitoring]] — healthchecks, Sentry, metrics
- [[Backup & Recovery]] — dump/restore + DR
- [[Incident Response]] — common runbooks

---

## Cross-cutting indexes

### By topic

| Topic | Start here |
|---|---|
| **Payments** | [[PRD - Request Network In-House Checkout]] → [[Payment API]] → [[Payment]] → [[Payout Flow]] |
| **Custody / escrow strategy** | [[PRD - Decentralized Custody and Smart-Contract Escrow Roadmap]] → [[Escrow Flow]] → [[Funds Ledger and Escrow State Machine Specification]] |
| **Auth** | [[Authentication Flow]] → [[Authentication API]] → [[Security Architecture]] |
| **Backend security / refactor** | [[Backend Stack Security and Refactor Assessment - 2026-05-24]] → [[Platform Logical Audit - 2026-05-24]] → [[PRD - Platform Audit Remediation Plan (2026-05-24)]] |
| **Developer task queue** | `.taskmaster/README.md` → `.taskmaster/tasks/tasks.json` → root `PRD - *.md` files |
| **Real-time** | [[Real-time Layer]] → [[Socket Events]] → [[Chat Flow]] / [[Notification Flow]] |
| **Disputes** | [[Dispute Flow]] → [[Dispute API]] → [[Dispute]] → [[Admin Guide]] §5 |
| **Web3** | [[Payment Flow - DePay & Web3]] → [[Frontend Architecture]] §9 |
| **i18n / RTL** | [[Internationalization & RTL]] → [[Typography]] |
| **Theming** | [[Design System Overview]] → [[Theme Configuration]] → [[Settings & Theming]] |

### By role

| If you are… | Start with |
|---|---|
| Buyer | [[User Guide]] |
| Seller / Owner | [[Seller Guide]] |
| Admin | [[Admin Guide]] |
| Support agent | [[Support Guide]] |
| Backend engineer | [[Backend Architecture]] · [[Data Model Overview]] |
| Frontend engineer | [[Frontend Architecture]] · [[Design System Overview]] |
| DevOps / SRE | [[Infrastructure]] · [[Deployment]] · [[Incident Response]] |
| Product / PM | [[Introduction]] · [[Roles & Personas]] · `04 Flows` |

---

## Vault conventions

- **Wikilinks** `[[Document Name]]` (no extension) — Obsidian resolves them automatically.
- **YAML frontmatter** at the top of every file — `title`, `tags`, `created`.
- **Callouts** `> [!note]`, `> [!warning]`, `> [!tip]`, `> [!info]`, `> [!important]`, `> [!example]`.
- **Mermaid** diagrams in fenced code blocks (`flowchart`, `sequenceDiagram`, `stateDiagram-v2`, `erDiagram`).
- **Citations** `file:lineNumber` whenever referring to specific code (e.g., `backend/src/app.ts:79-179`).
- **Tables** for structured data — env vars, endpoints, model fields, etc.

---

## Statistics

- **~85 markdown files** across 9 sections
- **~600 KB total** of documentation
- **~80,000 words** of prose
- **Mermaid diagrams** for every major flow and architecture view
- **Wikilinks** throughout for graph-view navigation

---

## Known limitations & roadmap items

These are documented in their respective sections but worth highlighting:

> [!warning]
> - Backend rate-limit middleware is currently **disabled** (`backend/src/app.ts:227`). Enable before any public traffic — see [[Security Architecture]].
> - Passkey service is partly **stubbed** — see [[Passkey (WebAuthn) Flow]] for production-hardening checklist.
> - Auto-release of escrow on delivery confirmation **not yet automated** — admin/custody operators run release flows. See [[Delivery Confirmation Flow]] + [[Payout Flow]].
> - Dispute holds exist in code, but the Dispute model/docs still need full canonical state-machine alignment. See [[Dispute Flow]] + [[Escrow Flow]].
> - Several development env values committed as public — see [[Environment Variables]] for rotation list.
> - Single-host deployment; horizontal scaling requires Redis adapter for Socket.IO — see [[Real-time Layer]] §8.
> - Request Network webhooks currently land on the main app. Roadmap: Cloudflare Worker durable ingress + replay, with backend Transaction Safety Provider checks before escrow is credited. See [[Request Network Integration Constraints]].

---

## Contributing to this vault

- Add files under the appropriate section folder.
- Use the conventions above (frontmatter, wikilinks, callouts).
- Run `git diff` on the source repo before updating docs — keep cited line numbers fresh.
- For new flows, follow the structure of [[Authentication Flow]] (Actors → Preconditions → Steps → Mermaid → API calls → DB writes → Socket events → Side effects → Errors → Related).
- For new models, follow the structure of [[User]] (purpose → schema table → virtuals/hooks → methods → relationships → state diagram → queries → related).

---

## License & ownership

The vault is the project's internal documentation. Treat all credentials, addresses, and operational details as **confidential**. Public-facing copies should redact the seed credentials, env values, and any production URLs/IDs that aren't already public.

---

## End

Welcome to the codebase. If anything here is unclear, the source is in the [[Backend Architecture]] / [[Frontend Architecture]] cited files — fix the docs as you go.

<!-- git sync test: 2026-05-23 -->
