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

title, tags, aliases

title	tags	aliases
User	data-model mongoose	User Model IUser Account

User

The core identity document for every actor in the marketplace: buyers, sellers, and admins. Stores credentials (password + WebAuthn passkeys), profile/preference data, referral bookkeeping, point balances, and a soft-delete status flag. Almost every other model carries an ObjectId reference back to User, so this collection is the relational hub of the system.

[!note] Source backend/src/models/User.ts:70 — schema definition backend/src/models/User.ts:257 — model export

Schema

Field	Type	Required	Default	Validation	Index	Description
email	String	yes	—	lowercase, trim	unique	Primary login identifier.
password	String	no	—	minlength 6	—	Hashed password. Optional to support passkey-only accounts.
firstName	String	no	"کاربر"	trim	—	Persian default ("user").
lastName	String	no	"جدید"	trim	—	Persian default ("new").
role	String	yes	"buyer"	enum: admin / buyer / seller	yes	Authorisation tier.
isEmailVerified	Boolean	no	false	—	—	Set to true after TempVerification is consumed.
emailVerificationToken	String	no	—	—	—	Legacy token-based email verification.
emailVerificationCode	String	no	—	—	—	OTP code for email verification.
emailVerificationCodeExpires	Date	no	—	—	—	Expiry for emailVerificationCode.
passwordResetToken	String	no	—	—	—	Token for reset link flow.
passwordResetExpires	Date	no	—	—	—	Expiry of passwordResetToken.
passwordResetCode	String	no	—	—	—	OTP reset code.
passwordResetCodeExpires	Date	no	—	—	—	Expiry for OTP reset code.
passkeys[]	Subdocument array	no	[]	—	—	WebAuthn credentials (see below).
passkeys[].id	String	yes	—	—	—	Credential ID.
passkeys[].publicKey	String	yes	—	—	—	Stored public key.
passkeys[].counter	Number	yes	0	—	—	Signature counter.
passkeys[].deviceType	String	yes	—	enum: platform / cross-platform	—	Authenticator class.
passkeys[].deviceName	String	no	—	—	—	Optional human label.
passkeys[].createdAt	Date	no	Date.now	—	—	Registration timestamp.
profile.avatar	String	no	—	—	—	Avatar URL.
profile.photoURL	String	no	—	—	—	Alternative photo URL.
profile.phone	String	no	—	—	—	Contact phone.
profile.address.street	String	no	—	—	—	Inline address (separate from Address book).
profile.address.city	String	no	—	—	—	—
profile.address.state	String	no	—	—	—	—
profile.address.zipCode	String	no	—	—	—	—
profile.address.country	String	no	—	—	—	—
profile.bio	String	no	—	—	—	Free-form bio.
profile.website	String	no	—	—	—	Personal website URL.
profile.walletAddress	String	no	—	—	—	On-chain wallet address.
profile.isPublic	Boolean	no	false	—	—	Whether the profile is publicly visible.
preferences.language	String	no	"en"	—	—	UI language.
preferences.currency	String	no	"USD"	—	—	Display currency.
preferences.notifications.email	Boolean	no	true	—	—	Opt-in for email notifications.
preferences.notifications.sms	Boolean	no	false	—	—	Opt-in for SMS notifications.
preferences.notifications.push	Boolean	no	true	—	—	Opt-in for push notifications.
status	String	no	"active"	enum: active / suspended / deleted	yes	Soft-delete and moderation flag.
lastLoginAt	Date	no	—	—	—	Updated by auth middleware.
refreshTokens[]	String[]	no	[]	—	—	Outstanding JWT refresh tokens.
referralCode	String	no	—	—	unique, sparse	Not yet implemented in User.ts — planned for referral programme.
referredBy	ObjectId → User	no	—	—	yes	Not yet implemented in User.ts — planned for referral programme.
points.total	Number	no	0	—	—	Not yet implemented in User.ts — planned for loyalty system.
points.available	Number	no	0	—	—	Not yet implemented in User.ts.
points.used	Number	no	0	—	—	Not yet implemented in User.ts.
points.level	Number	no	1	—	yes (points.level)	Not yet implemented in User.ts — planned for LevelConfig lookup.
referralStats.totalReferrals	Number	no	0	—	—	Not yet implemented in User.ts.
referralStats.activeReferrals	Number	no	0	—	—	Not yet implemented in User.ts.
referralStats.totalEarned	Number	no	0	—	—	Not yet implemented in User.ts.
createdAt	Date	auto	—	—	—	Mongoose timestamp.
updatedAt	Date	auto	—	—	—	Mongoose timestamp.

Virtuals

Virtual	Returns	Definition
fullName	${firstName} ${lastName}	backend/src/models/User.ts:238

Indexes

Defined explicitly (in addition to the implicit email unique index):

• { role: 1 } — backend/src/models/User.ts:178
• { status: 1 } — backend/src/models/User.ts:179

[!warning] Missing indexes The schema currently defines only role and status indexes. The referralCode, referredBy, and points.level indexes documented below are not yet present in User.ts:

Pre/Post Hooks

None declared at the schema level.

Instance Methods

Signature	Purpose
toJSON(): object	Strips password, refreshTokens, all emailVerification* and passwordReset* fields before serialisation. Defined at backend/src/models/User.ts:243.

Static Methods

None defined on the schema.

Relationships

• References: User (self, via referredBy).
• Referenced by: PurchaseRequest (buyerId, preferredSellerIds, deliveryInfo.deliveryCodeUsedBy, deliveryInfo.deliveryAttempts[].sellerId), SellerOffer (sellerId), Payment (buyerId, sellerId), Chat (participants[].userId, messages[].senderId, metadata.createdBy), Notification (userId as string), RequestTemplate (sellerId), Dispute (buyerId, sellerId, adminId), BlogPost (author.id), Address (userId), Review (sellerId, reviewerId), PointTransaction (user, referredUser), ShopSettings (sellerId).

State Transitions

stateDiagram-v2
    [*] --> active : signup verified
    active --> suspended : admin action
    suspended --> active : admin restore
    active --> deleted : self-delete
    suspended --> deleted : admin purge
    deleted --> [*]

Common Queries

// Find by email (login)
User.findOne({ email: email.toLowerCase() });

// Active sellers
User.find({ role: 'seller', status: 'active' });

// Validate referral
User.findOne({ referralCode: code });

// Leaderboard by points
User.find({ status: 'active' }).sort({ 'points.total': -1 }).limit(10);

// Promote level
User.updateOne({ _id: id }, { $set: { 'points.level': newLevel } });

Related: TempVerification, LevelConfig, PointTransaction, ShopSettings.