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.

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.

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
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.

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.