--- title: Amn Marketplace — Documentation Vault tags: [moc, index] created: 2026-05-23 --- # 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]] | | **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.