Initial commit: nick docs
This commit is contained in:
moojttaba
229
README.md
Normal file
229
README.md
Normal file
@@ -0,0 +1,229 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user