232 lines
9.7 KiB
Markdown
232 lines
9.7 KiB
Markdown
---
|
|
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]] |
|
|
| **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.
|
|
|
|
---
|
|
|
|
## 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.
|