nick-doc/02 - Data Models/PurchaseRequest.md

title, tags, aliases

title	tags	aliases
PurchaseRequest	data-model mongoose postgres drizzle	Purchase Request Buy Request IPurchaseRequest

PurchaseRequest

Last updated: 2026-06-03 — added Postgres / Drizzle schema section, child-table breakdowns, migration status, and dispute/escrow hold fields present in both Mongo and PG schemas.

The central buyer-side document. A PurchaseRequest captures what a buyer wants to acquire (physical product, digital product, service, or consultation), the budget envelope, urgency, delivery details, and the entire lifecycle from creation through payment, delivery, and completion. Sellers respond by attaching SellerOffer documents; the buyer accepts one, a Payment is opened, and delivery is verified by a 6-digit code.

[!note] Sources Mongo model: backend/src/models/PurchaseRequest.ts:95 — schema definition; :387 — model export Drizzle schema: backend/src/db/schema/purchaseRequest.ts

Migration Status

DUAL-WRITE active — part of DualWriteMarketplaceRepo. Writes go to both Mongo and Postgres; reads still come from Mongo. Backfill and read-cutover are human-gated and not yet executed.

---

Mongo Schema

Fields

Field	Type	Required	Default	Validation	Index	Description
buyerId	ObjectId → User	yes	—	—	yes	Buyer that owns the request.
title	String	yes	—	trim, maxlength 200	—	Short headline.
description	String	yes	—	trim, minlength 5 (frontend), maxlength 2000	—	Long form description. Frontend enforces a 5-character minimum; the field is optional in the raw schema but the form will reject shorter values.
categoryId	ObjectId → Category	yes	—	—	yes	Category the request belongs to.
productType	String	no	physical_product	enum: physical_product / digital_product / service / consultation	yes	What kind of fulfilment is expected.
productLink	String	no	—	trim, must match /^https?:\/\/.+/	—	Reference URL for the desired product.
size	String	no	—	trim, maxlength 100	—	Product size.
color	String	no	—	trim, maxlength 100	—	Product color.
brand	String	no	—	trim, maxlength 100	—	Brand preference.
preferredSellerIds[]	ObjectId → User	no	[]	—	—	Targeted sellers for a private request.
quantity	Number	no	1	min 1	—	Unit count.
budget.min	Number	no	—	min 0	—	Lower bound.
budget.max	Number	no	—	min 0	—	Upper bound.
budget.currency	String	no	USDT	enum: USD / EUR / IRR / USDT / USDC	—	Budget currency. Runtime Mongoose validation, request-template validation, and the PG budget_currency enum now share these values.
urgency	String	no	medium	enum: low / medium / high / urgent	yes	Buyer urgency.
status	String	no	pending	enum (13 values — see State Transitions below)	yes	Lifecycle state.
isPublic	Boolean	no	true	—	—	Public marketplace listing vs. private request.
tags[]	String[]	no	—	trim	—	Free-form tags.
specifications[].key	String	yes	—	trim	—	Spec key.
specifications[].value	String	yes	—	trim	—	Spec value.
specifications[].label	String	no	—	trim	—	Human label.
deliveryInfo.deliveryType	String	yes	physical	enum: physical / online	—	Delivery channel. Direct requests are buyer-selected; template checkout inherits the seller-selected RequestTemplate delivery mode.
deliveryInfo.address	String	no	—	—	—	Physical address. In template checkout this is built from the buyer's selected billing address only when the template requires physical delivery.
deliveryInfo.preferredDate	Date	no	—	—	—	Buyer's target date.
deliveryInfo.notes	String	no	—	—	—	Free-form notes.
deliveryInfo.deliveryAddress.name	String	no	—	—	—	Recipient name.
deliveryInfo.deliveryAddress.phoneNumber	String	no	—	—	—	Recipient phone.
deliveryInfo.deliveryAddress.fullAddress	String	no	—	—	—	Full address string copied from checkout billing for physical template orders.
deliveryInfo.deliveryAddress.addressType	String	no	—	—	—	e.g. Home / Office.
deliveryInfo.email	String	no	—	email regex	—	Buyer receiving email for digital/online template delivery.
deliveryInfo.sellerDeliveryInfo.estimatedDeliveryDate	Date	no	—	—	—	Seller's ETA date.
deliveryInfo.sellerDeliveryInfo.estimatedDeliveryTime	String	no	—	—	—	Seller's ETA time.
deliveryInfo.sellerDeliveryInfo.trackingNumber	String	no	—	—	—	Carrier tracking.
deliveryInfo.sellerDeliveryInfo.deliveryNotes	String	no	—	—	—	Notes from seller.
deliveryInfo.sellerDeliveryInfo.shippingMethod	String	no	—	—	—	Method label.
deliveryInfo.sellerDeliveryInfo.downloadLink	String	no	—	—	—	Download URL for digital products.
deliveryInfo.sellerDeliveryInfo.digitalFiles[]	String[]	no	—	—	—	Digital file URLs.
deliveryInfo.deliveryDateTime	Date	no	—	—	—	Confirmed delivery datetime.
deliveryInfo.deliveryDate	Date	no	—	—	—	Confirmed delivery date.
deliveryInfo.shippedAt	Date	no	—	—	—	Timestamp of shipment.
deliveryInfo.deliveryCode	String	no	—	trim, length 6	—	6-digit handoff code.
deliveryInfo.deliveryCodeGeneratedAt	Date	no	—	—	—	When code was issued.
deliveryInfo.deliveryCodeExpiresAt	Date	no	—	—	—	When code expires.
deliveryInfo.deliveryCodeUsed	Boolean	no	false	—	—	Whether the code has been redeemed.
deliveryInfo.deliveryCodeUsedAt	Date	no	—	—	—	When it was redeemed.
deliveryInfo.deliveryCodeUsedBy	ObjectId → User	no	—	—	—	Seller that redeemed.
deliveryInfo.deliveredAt	Date	no	—	—	—	Final delivery timestamp.
deliveryInfo.deliveryAttempts[].sellerId	ObjectId → User	yes	—	—	—	Seller making the attempt.
deliveryInfo.deliveryAttempts[].attemptedAt	Date	no	Date.now	—	—	When attempted.
deliveryInfo.deliveryAttempts[].success	Boolean	yes	—	—	—	Whether it succeeded.
deliveryInfo.deliveryAttempts[].code	String	no	—	—	—	Code entered (only stored on success).
serviceInfo.duration	Number	no	—	min 0.5	—	Hours, only for service/consultation.
serviceInfo.sessionType	String	no	—	enum: online / in_person / hybrid	—	Service session type.
serviceInfo.location	String	no	—	trim, maxlength 200	—	Service location.
serviceInfo.requirements[]	String[]	no	—	trim	—	Pre-requisites.
attachments[]	String[]	no	—	—	—	Attached file URLs.
offers[]	ObjectId → SellerOffer	no	—	—	—	Offers received. Dropped in PG — query SellerOffer WHERE purchase_request_id = ? instead.
selectedOfferId	ObjectId → SellerOffer	no	null	—	—	Accepted offer.
rating	Number	no	null	min 1, max 5	—	Buyer's post-delivery rating.
feedback	String	no	null	maxlength 1000	—	Buyer's feedback text.
deliveryConfirmed	Boolean	no	false	—	—	Buyer confirmation flag.
deliveryConfirmedAt	Date	no	null	—	—	Confirmation timestamp.
disputeRaised	Boolean	no	false	—	—	Escrow: whether a dispute has been raised.
disputeRaisedAt	Date	no	null	—	—	When the dispute was raised.
disputeResolved	Boolean	no	false	—	—	Escrow: whether dispute is resolved.
disputeResolvedAt	Date	no	null	—	—	When it was resolved.
disputeHoldReason	String	no	null	—	—	Human-readable hold reason.
holdUntil	Date	no	null	—	—	Escrow hold expiry; partial index in PG for expiry sweeps.
metadata.source	String	no	manual	enum: manual / template / api	—	Where the request came from.
metadata.templateId	String	no	—	trim	—	Originating RequestTemplate id.
metadata.version	String	no	—	trim	—	Schema version.
createdAt	Date	auto	—	—	yes (desc)	Mongoose timestamp.
updatedAt	Date	auto	—	—	—	Mongoose timestamp.

Status enum — all valid values

pending_payment · pending · active · received_offers · in_negotiation · payment · processing · delivery · delivered · confirming · completed · seller_paid · cancelled

Note: finalized and archived are not valid status values and do not appear in the IPurchaseRequest frontend type or the Mongoose schema enum. Using either would cause a validation error.

Virtuals

None defined.

Mongo Indexes

Single-field — backend/src/models/PurchaseRequest.ts:414-419:

• { buyerId: 1 }
• { categoryId: 1 }
• { productType: 1 }
• { status: 1 }
• { createdAt: -1 }
• { urgency: 1 }

Compound — backend/src/models/PurchaseRequest.ts:422-423:

• { productType: 1, status: 1 }
• { categoryId: 1, productType: 1 }

Pre/Post Hooks

None declared at the schema level.

Instance Methods

None defined.

Static Methods

None defined.

---

Postgres / Drizzle Schema

Source: backend/src/db/schema/purchaseRequest.ts

The PG model normalises the embedded Mongo subdocuments into 7 tables. The offers[] array is dropped; SellerOffer holds purchase_request_id as a back-reference.

Enums (PG-level)

Enum name	Values
purchase_request_status	pending_payment, pending, active, received_offers, in_negotiation, payment, processing, delivery, delivered, confirming, completed, cancelled, seller_paid
product_type	physical_product, digital_product, service, consultation
request_urgency	low, medium, high, urgent
delivery_type	physical, online
service_session_type	online, in_person, hybrid
pr_metadata_source	manual, template, api
budget_currency	USD, EUR, IRR, USDT, USDC

Table: purchase_requests (main)

Column	PG type	Nullable	Default	Notes
id	uuid PK	no	gen_random_uuid()
legacy_object_id	text	yes	—	24-char Mongo ObjectId; partial-unique index
buyer_id	uuid	no	—	FK → users(id)
category_id	uuid	no	—	FK → categories(id)
title	varchar(200)	no	—
description	text	no	—
product_type	enum	yes	physical_product
product_link	varchar(2000)	yes	—	CHECK: ^https?://.+
size	varchar(100)	yes	—
color	varchar(100)	yes	—
brand	varchar(100)	yes	—
quantity	integer	yes	1	CHECK ≥ 1
budget_min	numeric(38,18)	yes	—	CHECK ≥ 0
budget_max	numeric(38,18)	yes	—	CHECK ≥ 0
budget_currency	enum	yes	USDT
urgency	enum	no	medium
status	enum	no	pending	13-value escrow-critical enum
is_public	boolean	yes	true
tags	text[]	yes	'{}'
attachments	text[]	yes	'{}'
selected_offer_id	uuid	yes	—	FK → seller_offers(id)
rating	smallint	yes	—	CHECK 1–5 or NULL
feedback	text	yes	—	CHECK length ≤ 1000 or NULL
delivery_confirmed	boolean	yes	false
delivery_confirmed_at	timestamptz	yes	—
dispute_raised	boolean	no	false
dispute_raised_at	timestamptz	yes	—
dispute_resolved	boolean	no	false
dispute_resolved_at	timestamptz	yes	—
dispute_hold_reason	text	yes	—
hold_until	timestamptz	yes	—	Partial index WHERE NOT NULL
metadata_source	enum	yes	manual
metadata_template_id	varchar(100)	yes	—
metadata_version	varchar(50)	yes	—
created_at	timestamptz	no	now()
updated_at	timestamptz	no	now()

Indexes on purchase_requests:

Index	Type	Columns / condition
idx_pr_buyer_id	btree	buyer_id
idx_pr_category_id	btree	category_id
idx_pr_product_type	btree	product_type
idx_pr_status	btree	status
idx_pr_created_at	btree	created_at
idx_pr_urgency	btree	urgency
purchase_requests_legacy_object_id_uq	partial-unique	legacy_object_id WHERE NOT NULL
idx_pr_product_type_status	btree	(product_type, status)
idx_pr_category_product_type	btree	(category_id, product_type)
idx_pr_hold_until	partial btree	hold_until WHERE NOT NULL
idx_pr_dispute_raised	partial btree	dispute_raised WHERE dispute_raised = true

CHECK constraints on purchase_requests:

Name	Expression
pr_rating_ck	rating IS NULL OR (rating >= 1 AND rating <= 5)
pr_feedback_len_ck	feedback IS NULL OR length(feedback) <= 1000
pr_quantity_min_ck	quantity IS NULL OR quantity >= 1
pr_budget_min_ck	budget_min IS NULL OR budget_min >= 0
pr_budget_max_ck	budget_max IS NULL OR budget_max >= 0
pr_product_link_ck	product_link IS NULL OR product_link ~ '^https?://.+'

---

Table: purchase_request_delivery_info (1:1)

Child of purchase_requests. Holds all delivery logistics.

Column	PG type	Nullable	Default	Notes
id	uuid PK	no	random
legacy_object_id	text	yes	—	Parent PR's legacy ObjectId for traceability
purchase_request_id	uuid UNIQUE	no	—	FK → purchase_requests(id) CASCADE
delivery_type	enum	no	physical
address	varchar(500)	yes	—
preferred_date	timestamptz	yes	—
notes	text	yes	—
email	varchar(255)	yes	—	CHECK: email regex or NULL
delivery_date_time	timestamptz	yes	—
delivery_date	date	yes	—
shipped_at	timestamptz	yes	—
delivery_code	varchar(6)	yes	—	CHECK: length = 6 or NULL
delivery_code_generated_at	timestamptz	yes	—
delivery_code_expires_at	timestamptz	yes	—
delivery_code_used	boolean	yes	false
delivery_code_used_at	timestamptz	yes	—
delivery_code_used_by	uuid	yes	—	FK → users(id)
delivered_at	timestamptz	yes	—
created_at	timestamptz	no	now()
updated_at	timestamptz	no	now()

Indexes: idx_pr_delivery_info_pr_id on purchase_request_id

CHECK constraints: pr_di_delivery_code_len_ck (length = 6 or NULL), pr_di_email_fmt_ck (email regex)

---

Table: purchase_request_delivery_address (1:1 under delivery_info)

Column	PG type	Nullable	Notes
id	uuid PK	no
legacy_object_id	text	yes
delivery_info_id	uuid UNIQUE	no	FK → purchase_request_delivery_info(id) CASCADE
recipient_name	varchar(200)	yes
phone_number	varchar(20)	yes
full_address	text	yes
address_type	varchar(50)	yes	e.g. Home / Office

Index: idx_pr_delivery_addr_info_id on delivery_info_id

---

Table: purchase_request_seller_delivery_info (1:1 under delivery_info)

Column	PG type	Nullable	Default	Notes
id	uuid PK	no	random
legacy_object_id	text	yes	—
delivery_info_id	uuid UNIQUE	no	—	FK → purchase_request_delivery_info(id) CASCADE
estimated_delivery_date	timestamptz	yes	—
estimated_delivery_time	varchar(50)	yes	—
tracking_number	varchar(100)	yes	—
delivery_notes	text	yes	—
shipping_method	varchar(100)	yes	—
download_link	varchar(2000)	yes	—
digital_files	text[]	yes	'{}'
created_at	timestamptz	no	now()
updated_at	timestamptz	no	now()

Index: idx_pr_seller_di_info_id on delivery_info_id

---

Table: delivery_attempts (1:N under delivery_info)

Append-only audit log of code-entry attempts.

Column	PG type	Nullable	Default	Notes
id	uuid PK	no	random
delivery_info_id	uuid	no	—	FK → purchase_request_delivery_info(id) CASCADE
seller_id	uuid	no	—	FK → users(id)
attempted_at	timestamptz	no	now()
success	boolean	no	—
code	varchar(100)	yes	—	Only stored on successful attempts

Indexes: idx_delivery_attempts_info_id, idx_delivery_attempts_seller_id, idx_delivery_attempts_success

---

Table: purchase_request_service_info (1:1)

Only populated for service / consultation product types.

Column	PG type	Nullable	Default	Notes
id	uuid PK	no	random
legacy_object_id	text	yes	—
purchase_request_id	uuid UNIQUE	no	—	FK → purchase_requests(id) CASCADE
duration	numeric(5,2)	yes	—	CHECK ≥ 0.5
session_type	enum	yes	—	online / in_person / hybrid
location	varchar(200)	yes	—
requirements	text[]	yes	'{}'
created_at	timestamptz	no	now()
updated_at	timestamptz	no	now()

Index: idx_pr_service_info_pr_id CHECK: pr_si_duration_min_ck (duration IS NULL OR duration >= 0.5)

---

Table: purchase_request_specifications (1:N)

Queryable {key, value, label} specs extracted from the Mongo embedded array.

Column	PG type	Nullable	Default	Notes
id	uuid PK	no	random
purchase_request_id	uuid	no	—	FK → purchase_requests(id) CASCADE
key	varchar(255)	no	—
value	text	no	—
label	varchar(255)	yes	—
position	integer	no	0	Preserves array order for round-trip fidelity

Indexes: idx_pr_specs_pr_id, idx_pr_specs_key, partial-unique purchase_request_specifications_request_key_uq on (purchase_request_id, key)

---

Table: purchase_request_preferred_sellers (N:M junction)

Column	PG type	Nullable	Notes
purchase_request_id	uuid	no	FK → purchase_requests(id)
seller_id	uuid	no	FK → users(id)

Indexes: composite unique idx_pr_preferred_sellers_uq on (purchase_request_id, seller_id); idx_pr_preferred_sellers_seller_id on seller_id

---

Design Notes

• offers[] dropped in PG. The Mongo offers[] array is not migrated. Query SellerOffer WHERE purchase_request_id = ? instead.
• Money scale. budget_min / budget_max use numeric(38,18) (project-wide crypto convention) rather than the numeric(15,8) suggested in the migration guide, for consistency with Payment and FundsLedgerEntry.
• tags / attachments stored as text[] (not JSONB) to enable ANY() array queries without a child table.
• legacy_object_id on every table uses a partial-unique index (WHERE NOT NULL) for idempotent backfill upserts.
• Dispute / escrow hold fields (dispute_raised, dispute_raised_at, dispute_resolved, dispute_resolved_at, dispute_hold_reason, hold_until) are present in both the Mongo interface (IPurchaseRequest) and the PG main table. They were added to the Mongo schema before the PG migration and are considered escrow-critical.

---

Relationships

• References: User (buyerId, preferredSellerIds[], deliveryInfo.deliveryCodeUsedBy, deliveryInfo.deliveryAttempts[].sellerId), Category (categoryId), SellerOffer (offers[] Mongo only, selectedOfferId).
• Referenced by: SellerOffer (purchaseRequestId), Payment (purchaseRequestId), Dispute (purchaseRequestId), Chat (relatedTo.id when relatedTo.type === 'PurchaseRequest'), Review (purchaseRequestId).

Template Checkout Mapping

When a buyer converts a RequestTemplate, the seller's template remains authoritative for delivery mode:

• physical templates require a buyer billing/delivery address in checkout. The generated request stores both deliveryInfo.address and deliveryInfo.deliveryAddress.
• online templates require a buyer email in checkout. The generated request stores it in deliveryInfo.email.
• Mixed carts can produce multiple requests with different delivery modes; the checkout UI asks for the union of required buyer details.

State Transitions

stateDiagram-v2
    [*] --> pending_payment
    [*] --> pending
    pending_payment --> pending : payment confirmed
    pending --> active : published
    active --> received_offers : first offer
    received_offers --> in_negotiation : buyer engages
    in_negotiation --> payment : offer accepted
    payment --> processing : payment captured
    processing --> delivery : shipped
    delivery --> delivered : handed over
    delivered --> confirming : code redeemed
    confirming --> completed : buyer confirms
    completed --> seller_paid : payout released
    pending --> cancelled
    active --> cancelled
    received_offers --> cancelled
    in_negotiation --> cancelled
    completed --> [*]
    seller_paid --> [*]
    cancelled --> [*]

Common Queries

// Buyer's open requests
PurchaseRequest.find({ buyerId, status: { $in: ['pending', 'active', 'received_offers'] } });

// Public marketplace feed
PurchaseRequest.find({ isPublic: true, status: 'active' }).sort({ createdAt: -1 });

// Sellers' eligible queue
PurchaseRequest.find({ productType, status: 'active', categoryId });

// Populate offers (Mongo only — offers[] array is not in PG)
PurchaseRequest.findById(id).populate('offers').populate('selectedOfferId');

// Redeem delivery code
PurchaseRequest.findOneAndUpdate(
  { _id: id, 'deliveryInfo.deliveryCode': code, 'deliveryInfo.deliveryCodeUsed': false },
  { $set: { 'deliveryInfo.deliveryCodeUsed': true, 'deliveryInfo.deliveryCodeUsedAt': new Date() } }
);

// PG: offers for a request
// SELECT * FROM seller_offers WHERE purchase_request_id = $1;

// PG: find requests with live escrow hold
// SELECT * FROM purchase_requests WHERE hold_until IS NOT NULL AND hold_until > now();

Related: SellerOffer, Payment, Chat, Dispute, Review, RequestTemplate, Category.