nick/nick-doc
3
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: sync from backend 8fc2309 — M43/M44 missing FKs + H37 dispute enums

Browse Source
This commit is contained in:
Siavash Sameni
2026-06-07 07:16:02 +04:00
parent a2967ec594
commit 0bb60dbc98
24 changed files with 3428 additions and 906 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
07 - Development/Coding Standards.md
View File

@@ -117,8 +117,7 @@ Both repos use Prettier defaults from the local config:
| React component | PascalCase | `RequestCard` |
| Hook | camelCase starting with `use` | `useSocket`, `useAuthContext` |
| Constant | SCREAMING_SNAKE | `MAX_FILE_SIZE` |
| Mongoose model | PascalCase singular | `User`, `PurchaseRequest` |
| Mongo collection | lowercase plural (auto) | `users`, `purchaserequests` |
| Drizzle table | camelCase (schema) / snake_case (SQL) | `purchaseRequests` / `purchase_requests` |
| Route handler | `<verb><Noun>` | `getRequestById`, `createOffer` |
| Express route file | `<domain>Routes.ts` | `paymentRoutes.ts` |
@@ -133,8 +132,7 @@ src/services/marketplace/
├── index.ts # Barrel — only public exports
├── marketplaceRoutes.ts # Router (express.Router) — auth middleware, validation, controller calls
├── marketplaceController.ts # HTTP layer — parses req, calls service, formats response envelope
├── marketplaceService.ts # Business logic — talks to models, throws domain errors
└── marketplaceRepository.ts # Optional Mongoose query helpers (when service grows)
└── marketplaceService.ts # Business logic — calls repository layer, throws domain errors
```
### Response envelope
@@ -195,6 +193,44 @@ logError("Request Network webhook verification failed", err);
Never use raw `console.error` in service code — it bypasses Sentry breadcrumbs.
### Database access
PostgreSQL + Drizzle ORM is the **only** database layer. MongoDB and Mongoose have been completely removed from the runtime.
Rules:
- Always access data through the repository layer (`src/db/repositories/`). Call `getXxxRepo()` from the factory (`src/db/repositories/factory.ts`).
- Never import `mongoose` or reference Mongoose models — they no longer exist. All `src/models/` Mongoose model files have been deleted.
- Never use raw Drizzle `db` queries in service or controller code; wrap them in a repository method.
- `PG_URL` is a required environment variable. The old `MONGO_URI` / `MONGODB_URI` / `MONGO_CONNECT_MODE` vars are obsolete and must not be added back.
```ts
// ✅ Correct
import { getOfferRepo } from "@db/repositories/factory";
const repo = getOfferRepo();
const offer = await repo.findById(offerId);
// ❌ Wrong — Mongoose is gone
import { Offer } from "@models/offer";
const offer = await Offer.findById(offerId);
```
### ID conventions
All primary keys are **PostgreSQL UUIDs** (`string`).
- Use `.id` to read an entity's primary key — never `._id`.
- The `users` table retains a `legacy_object_id` column (the old MongoDB ObjectId string) for backward compatibility only. Do not use `legacy_object_id` in new code; use `user.pgId` (UUID) for foreign-key references to users (e.g. `offer.sellerId`).
- Marketplace FKs such as `offer.sellerId` are `user.pgId` (UUID), **not** `user._id` (legacy ObjectId).
```ts
// ✅ Correct
const id: string = entity.id; // Postgres UUID
// ❌ Wrong — _id is a legacy ObjectId string, not a Postgres UUID
const id = entity._id;
```
---
## 5. Frontend — UI standards
@@ -377,4 +413,7 @@ Before requesting review:
| `useState` for global state that 3+ components need | a context in `src/contexts/` or a custom hook |
| Direct `axios.create` calls in components | use `src/lib/axios.ts` or an action in `src/actions/` |
| Hard-coded URLs | constants in `src/routes/paths.ts` (frontend) or env vars (backend) |
| Schema changes without a migration | add a migration script in `src/scripts/` and document it |
| Schema changes without a migration | add a Drizzle migration (`drizzle-kit generate`) and document it |
| `import mongoose` / Mongoose models | `getXxxRepo()` from `src/db/repositories/factory` |
| `entity._id` for Postgres entities | `entity.id` (UUID string) |
| `MONGO_URI` / `MONGO_CONNECT_MODE` env vars | `PG_URL` (required) |

28
07 - Development/Environment Variables.md
View File

@@ -32,15 +32,14 @@ Next.js auto-loads `.env`, `.env.local`, `.env.development`, `.env.production` i
| Name | Repo | Required | Default | Example | Purpose |
|------|------|----------|---------|---------|---------|
| `MONGODB_URI` | backend | ✅ | — | `mongodb://mongodb:27017` | Mongo connection string (no auth in dev) |
| `DB_NAME` | backend | ✅ | — | `marketplace` | Database name appended to the URI |
| `PG_URL` | backend | conditional | — | `postgres://amanat:...@postgres:5432/amanat_dev` | Drizzle runtime DSN. Required before importing PG-backed code such as `quoteRepo`; does not cut over app domains by itself. |
| ~~`MONGODB_URI`~~ | ~~backend~~ | **REMOVED** | — | — | **REMOVED** — MongoDB has been completely removed from the backend (v2.9.12). Do not set this variable. |
| ~~`DB_NAME`~~ | ~~backend~~ | **REMOVED** | — | — | **REMOVED** — Was the Mongo database name; no longer used. |
| `PG_URL` | backend | ✅ **REQUIRED** | — | `postgres://amanat:...@postgres:5432/amanat_dev` | Drizzle runtime DSN. PostgreSQL is the only database layer; this must be set for the backend to start. |
| `MIGRATION_PG_URL` | backend | migration only | — | `postgres://amanat:...@postgres:5432/amanat_dev` | DSN used by backfill/migration scripts. Guarded by non-prod host allowlist. |
In `docker-compose.production.yml` the Mongo service is `mongodb` and is reachable as `mongodb://mongodb:27017` from the backend container.
PostgreSQL (Drizzle ORM) is the **only** database layer as of v2.9.12. MongoDB and Mongoose have been completely removed. 19 migrations (0000–0019) have landed covering 32 tables.
> [!warning] Postgres cutover flags
> `REPO_*` flags exist in the backend repository factory, but broad services still call Mongoose models directly on `integrate-main-into-development@3a50dc4`. Do not assume setting `REPO_DEFAULT=pg` or `REPO_PAYMENT=pg` fully moves live traffic to Postgres without service wiring and verification. See [[Postgres Runtime Cutover Status]].
The following variables are also **REMOVED** and must not be set: `MONGO_CONNECT_MODE`, `MONGO_URL`, `MONGODB_URI`. Any `.env` file referencing them can have those lines deleted.
---
@@ -165,13 +164,15 @@ Direct-address balance checks and watches currently support EVM ERC-20 only. Bac
## Repository Mode Flags (Migration Layer)
> [!warning] These flags are **obsolete** as of v2.9.12. MongoDB and Mongoose have been completely removed. The repository factory returns Drizzle (PostgreSQL) repos exclusively. All domain stores are Postgres-only. The values `mongo`, `dual`, and `DualWrite*` are no longer valid — **only `postgres` is valid**, and it is the hardcoded default. These env vars are ignored at runtime and should not be set.
| Name | Repo | Required | Default | Example | Purpose |
|------|------|----------|---------|---------|---------|
| `REPO_DEFAULT` | backend | optional | `mongo` | `dual` | Fallback repository mode for domains that do not set their own flag. Current broad runtime services are not yet wired through the factory. |
| `REPO_USER` | backend | optional | `REPO_DEFAULT` or `mongo` | `dual` | Intended user/auth repository mode. Requires service wiring before it affects normal requests. |
| `REPO_PAYMENT` | backend | optional | `REPO_DEFAULT` or `mongo` | `dual` | Intended payment/ledger repository mode. Current payment APIs still call Mongoose directly. |
| `REPO_POINTS` | backend | optional | `REPO_DEFAULT` or `mongo` | `dual` | Intended points/referral repository mode. Current points service still calls Mongoose directly. |
| `REPO_MARKETPLACE` | backend | optional | `REPO_DEFAULT` or `mongo` | `dual` | Intended purchase request / seller offer repository mode. Current marketplace services still call Mongoose directly. |
| ~~`REPO_DEFAULT`~~ | ~~backend~~ | **OBSOLETE** | — | — | **REMOVED** — Only `postgres` is valid; the factory always returns Drizzle repos. |
| ~~`REPO_USER`~~ | ~~backend~~ | **OBSOLETE** | — | — | **REMOVED** — `mongo` and `dual` modes no longer exist. |
| ~~`REPO_PAYMENT`~~ | ~~backend~~ | **OBSOLETE** | — | — | **REMOVED** — `mongo` and `dual` modes no longer exist. |
| ~~`REPO_POINTS`~~ | ~~backend~~ | **OBSOLETE** | — | — | **REMOVED** — `mongo` and `dual` modes no longer exist. |
| ~~`REPO_MARKETPLACE`~~ | ~~backend~~ | **OBSOLETE** | — | — | **REMOVED** — `mongo` and `dual` modes no longer exist. |
---
@@ -307,9 +308,8 @@ NODE_ENV=development
PORT=5001
TRUST_PROXY=false
# Database
MONGODB_URI=mongodb://mongodb:27017
DB_NAME=marketplace
# Database (PostgreSQL only — MongoDB removed in v2.9.12)
PG_URL=postgres://amanat:secret@postgres:5432/amanat_dev
# Cache
REDIS_URI=redis://redis:6379

45
07 - Development/Local Setup.md
View File

@@ -7,10 +7,10 @@ tags: [development]
This guide walks you through running both repositories of the marketplace stack on your workstation. The platform is split into two services:
- **Backend** — Node.js 22+ / Express 5 / MongoDB 8 / Redis 8 / Socket.IO, served on port `5001`.
- **Backend** — Node.js 22+ / Express 5 / PostgreSQL 16 / Redis 8 / Socket.IO, served on port `5001`.
- **Frontend** — Next.js 16 / React 19 / MUI v7, served on port `8083` (or `3000` in Docker dev).
By the end of this page you will have the API running locally with MongoDB + Redis containers, a seeded set of test accounts, and the Next.js dashboard talking to it through your browser. For ongoing reference see [[Environment Variables]], [[Project Structure]], and [[Scripts]].
By the end of this page you will have the API running locally with PostgreSQL + Redis containers, a seeded set of test accounts, and the Next.js dashboard talking to it through your browser. For ongoing reference see [[Environment Variables]], [[Project Structure]], and [[Scripts]].
---
@@ -22,7 +22,7 @@ Install the following before you start:
|------|---------|-----|
| Node.js | `>= 22` (backend), `>= 20` (frontend) | Runtime |
| Yarn | `1.22.22` (Classic) | Pinned via `packageManager` field |
| Docker Desktop | latest | Runs MongoDB + Redis + (optionally) backend/frontend |
| Docker Desktop | latest | Runs PostgreSQL + Redis + (optionally) backend/frontend |
| Git | `>= 2.40` | SSH-based clone from Gitea |
| OpenSSL | system default | For generating local secrets |
| `ngrok` (optional) | latest | For webhook testing — see [[Scripts#start-ngrok-sh]] |
@@ -100,8 +100,7 @@ Each repo ships example files. Copy them and fill in secrets — full reference
```bash
NODE_ENV=development
PORT=5001
MONGODB_URI=mongodb://mongodb:27017
DB_NAME=marketplace
PG_URL=postgresql://postgres:postgres@postgres:5432/marketplace
REDIS_URI=redis://redis:6379
JWT_SECRET=$(openssl rand -hex 32)
JWT_EXPIRES_IN=1h
@@ -113,6 +112,8 @@ RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100
```
> [!note] `MONGODB_URI` / `MONGO_URI` / `MONGO_CONNECT_MODE` are **no longer used**. MongoDB has been fully removed from the backend runtime (v2.9.12+). The only database layer is PostgreSQL + Drizzle ORM. `PG_URL` is required.
For payments, OpenAI, SMTP, etc., refer to [[Environment Variables]].
### Frontend
@@ -135,7 +136,7 @@ You have two equivalent paths.
### Option A — All-in-Docker (recommended)
Builds the backend image, brings up MongoDB + Redis + backend on `nickapp-network`, and mounts `./src` for hot reload:
Builds the backend image, brings up PostgreSQL + Redis + backend on `nickapp-network`, and mounts `./src` for hot reload:
```bash
cd ~/code/backend
@@ -160,19 +161,34 @@ Run only the datastores in Docker and the API on the host:
```bash
cd ~/code/backend
docker compose -f docker-compose.dev.yml up -d mongodb redis
docker compose -f docker-compose.dev.yml up -d postgres redis
npm run dev # ts-node + nodemon on port 5001
```
Override `MONGODB_URI=mongodb://localhost:27017` in `.env` if you take this route, since `mongodb` only resolves inside the compose network.
Override `PG_URL=postgresql://postgres:postgres@localhost:5432/marketplace` in `.env` if you take this route, since `postgres` only resolves inside the compose network.
> [!tip] If port `5001` is already in use, set `PORT=5002` in `.env.local` and update `NEXT_PUBLIC_API_URL` in the frontend env to match.
---
## 5a. Apply database migrations
After starting the PostgreSQL container (and before seeding), apply all Drizzle migrations to create the 32-table schema:
```bash
cd ~/code/backend
npx drizzle-kit migrate
```
This runs the 19 migration files (0000–0019) and brings the database schema up to date. You only need to run this once on a fresh database, or after pulling commits that include new migration files.
> [!note] If you are using Option A (All-in-Docker), run this from the host after the `postgres` container is healthy but before the backend service connects.
---
## 6. Seed test data
Once MongoDB is healthy, populate it with default users, categories, addresses, and templates:
Once PostgreSQL is healthy and migrations have been applied, populate it with default users, categories, addresses, and templates:
```bash
cd ~/code/backend
@@ -189,7 +205,7 @@ npm run seed:categories # marketplace taxonomy
| Seller | `seller@marketplace.com` |
| Seller (alt) | `seller2@marketplace.com` |
You can also enable auto-seeding on container start by adding `AUTO_SEED_ON_START=true` to `.env.local`. Auto-seed runs only when the `users` collection has no non-admin entries — safe to leave on.
You can also enable auto-seeding on container start by adding `AUTO_SEED_ON_START=true` to `.env.local`. Auto-seed runs only when the `users` table has no non-admin entries — safe to leave on.
See [[Scripts#seed-scripts]] for the full list (`seed:users`, `seed:addresses`, `seed:categories`, `seed:all`, plus `createSupportUser.ts`, `createTestRequest.ts`, etc.).
@@ -231,7 +247,7 @@ curl -s -X POST http://localhost:5001/api/auth/login \
In the browser, open http://localhost:8083, log in with `admin@marketplace.com / Moji6364`, and confirm the dashboard loads. If chat or notification badges show up, sockets connected too.
> [!tip] Tail backend logs in a separate terminal: `npm run docker:dev:logs`. Look for `✅ Connected to MongoDB`, `🔌 User connected`, and `🚀 Server running on port 5001`.
> [!tip] Tail backend logs in a separate terminal: `npm run docker:dev:logs`. Look for `Connected to PostgreSQL`, `User connected`, and `Server running on port 5001`.
---
@@ -240,8 +256,9 @@ In the browser, open http://localhost:8083, log in with `admin@marketplace.com /
| Symptom | Fix |
|---------|-----|
| `EADDRINUSE :::5001` | Another process owns the port — `lsof -i :5001` then `kill`, or change `PORT`. |
| `MongoServerError: Authentication failed` | The compose file does **not** set Mongo auth in dev; remove any `user:pass@` prefix from `MONGODB_URI`. |
| `ECONNREFUSED 127.0.0.1:5432` | PostgreSQL container is down — `docker compose -f docker-compose.dev.yml ps` to check. |
| `ECONNREFUSED 127.0.0.1:6379` | Redis container is down — `docker compose -f docker-compose.dev.yml ps` to check. |
| `relation "users" does not exist` | Migrations have not been applied — run `npx drizzle-kit migrate` from the backend folder. |
| CORS errors in the browser | `FRONTEND_URL` in backend `.env.local` must exactly match the origin you open in the browser (scheme + host + port). |
| `yarn install` hangs on `sharp` | Run `yarn config set network-timeout 600000` and retry. |
| `next dev` fails with module-not-found after a `git pull` | Run `yarn install` again — Next 16 is sensitive to drift in `react`/`react-dom`. |
@@ -258,9 +275,9 @@ cd ~/code/backend
./scripts/reset-server.sh
```
This stops the dev compose stack, restarts it, runs health checks against MongoDB / Redis / `/health`, and probes the login endpoint with the seeded admin user. Output is colourised and ends with the canonical test credentials. See [[Scripts#reset-server-sh]] for details.
This stops the dev compose stack, restarts it, runs health checks against PostgreSQL / Redis / `/health`, and probes the login endpoint with the seeded admin user. Output is colourised and ends with the canonical test credentials. See [[Scripts#reset-server-sh]] for details.
> [!warning] `reset-server.sh` does **not** drop volumes by default. To wipe the database, uncomment the `down -v` line in the script or run `docker compose -f docker-compose.dev.yml down -v` first.
> [!warning] `reset-server.sh` does **not** drop volumes by default. To wipe the database, uncomment the `down -v` line in the script or run `docker compose -f docker-compose.dev.yml down -v` first. You will need to re-run `npx drizzle-kit migrate` and `npm run seed:all` after a volume wipe.
---

34
07 - Development/Project Structure.md
View File

@@ -11,7 +11,7 @@ A bird's-eye view of both repos. For deep dives, follow the cross-links to [[Bac
## Backend — `/Users/mojtabaheidari/code/backend`
A service-oriented Express 5 app. Each business domain owns a folder under `src/services/` containing its routes, controllers, services, and (sometimes) its own models. Cross-cutting concerns live in `src/shared/` and `src/infrastructure/`.
A service-oriented Express 5 app. Each business domain owns a folder under `src/services/` containing its routes, controllers, services, and repositories. Cross-cutting concerns live in `src/shared/` and `src/infrastructure/`. PostgreSQL + Drizzle ORM is the sole database layer as of v2.9.12 (Mongoose fully removed).
```
backend/
@@ -20,9 +20,13 @@ backend/
│ ├── config/ # Sentry init (loaded before anything else)
│ ├── controllers/ # Thin HTTP controllers for orphan endpoints (disputes, points)
│ ├── routes/ # Router exports for orphan controllers above
│ ├── models/ # Mongoose schemas (single source of truth for data)
│ ├── models/ # (removed — Mongoose models deleted; schemas now in src/db/schema/)
│ ├── db/ # PostgreSQL + Drizzle ORM — SOLE database layer (19 migrations, 32 tables)
│ │ ├── schema/ # Drizzle table definitions (single source of truth for data)
│ │ ├── migrations/ # SQL migration files (0000–0019)
│ │ └── repositories/ # Drizzle-backed repository implementations
│ ├── infrastructure/
│ │ ├── database/ # Mongo connection + admin bootstrap
│ │ ├── database/ # (removed — Mongoose connection code deleted)
│ │ └── socket/ # Socket.IO server adapter & emitter helpers
│ ├── services/ # Domain services — see breakdown below
│ ├── shared/
@@ -36,12 +40,11 @@ backend/
├── __tests__/ # Jest suites (see Testing)
├── scripts/ # Shell scripts (build/push, version, ngrok, reset)
├── nginx/ # Nginx conf (production compose)
├── mongo-init/ # Mongo initdb.d JS (one-time bootstrap)
├── uploads/ # User uploads — mounted as volume
├── Dockerfile.dev # Hot-reload image (ts-node + nodemon)
├── Dockerfile.prod # Multi-stage build image (compiled JS, non-root user)
├── docker-compose.dev.yml # Local stack: backend + mongo + redis
├── docker-compose.production.yml # Prod stack: nginx + backend + frontend + mongo + redis
├── docker-compose.dev.yml # Local stack: backend + postgres + redis
├── docker-compose.production.yml # Prod stack: nginx + backend + frontend + postgres + redis
├── .gitea/workflows/ # Gitea Actions CI
├── healthcheck.js # Container HEALTHCHECK probe
├── eslint.config.js # Flat ESLint config (TS strict)
@@ -73,14 +76,19 @@ Each service folder follows the same shape: `<service>Routes.ts`, `<service>Cont
| `redis/` | Redis client wrapper (caching, rate counters) |
| `user/` | Profile, settings, role management |
### `src/models/`
### `src/models/` (removed)
Each `.ts` file is a Mongoose model — see [[Data Models]] for full schema docs. Highlights:
This directory no longer exists. All Mongoose models have been deleted. Data schemas are now defined as Drizzle table objects in `src/db/schema/`. See [[Data Models]] for the current PostgreSQL schema docs.
- `User`, `Address`, `Category` — identity & taxonomy
- `PurchaseRequest`, `SellerOffer`, `RequestTemplate` — marketplace core
- `Payment`, `PointTransaction`, `LevelConfig` — money + reputation
- `Chat`, `Notification`, `Dispute`, `Review`, `BlogPost`, `ShopSettings`, `TempVerification` — supporting domains
### `src/db/`
PostgreSQL + Drizzle ORM — the **sole** database layer (no Mongoose, no dual-write, no Mongo fallback). Highlights:
- `schema/` — Drizzle table definitions covering all 32 tables across 19 migrations (0000–0019)
- `migrations/` — SQL migration files applied via `drizzle-kit`
- `repositories/` — Drizzle-backed repository implementations returned exclusively by the repository factory
- All domain stores use `PG_URL` (required); `MONGO_URI` / `MONGODB_URI` / `MONGO_CONNECT_MODE` are obsolete
- IDs are PostgreSQL UUIDs (`.id` string field); `legacy_object_id` column preserves the original MongoDB ObjectId for `User` only
### `src/seeds/`
@@ -189,7 +197,7 @@ The production `docker-compose.yml` lives in `backend/` but references `../front
| You want to add… | Put it under… |
|---|---|
| A new public API route | `backend/src/services/<domain>/<domain>Routes.ts` (or a new domain folder) |
| A new Mongo schema | `backend/src/models/<Name>.ts` + export from `models/index.ts` |
| A new database table | `backend/src/db/schema/<name>.ts` (Drizzle) + add a migration via `drizzle-kit generate` |
| A reusable UI component | `frontend/src/components/<kebab-name>/` with `index.ts` + `component.tsx` + `types.ts` |
| A page-specific block | `frontend/src/sections/<domain>/` |
| A new dashboard page | `frontend/src/app/dashboard/<route>/page.tsx` |