title, tags, created

title	tags	created
Amn Marketplace — Documentation Vault	moc index	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 · Branch: development · 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
• Frontend Architecture — Next.js 16 App Router + provider tree
• 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
• 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

• Payment Flow - SHKeeper · Payment Flow - DePay & Web3 · Escrow Flow · Payout Flow

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	Payment Flow - SHKeeper → Payment API → Payment → Payout Flow
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 runs manual payouts. See Delivery Confirmation Flow + Payout Flow.
• Opening a dispute does not pause the escrow until admin intervention. 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.