Data models: User, Product, and Cart schemas

The shirt-store API is built on three Mongoose models: User, Product, and Cart. Each model maps directly to a MongoDB collection, and together they capture everything from account credentials to purchase history. Understanding these schemas — and the embedded-document pattern that connects them — will help you build against the API with confidence.

User model

The User document represents every registered account, whether a shopper or an admin. Authentication state, personal details, and role assignments all live here.

// src/models/User.js (simplified)
const UserSchema = new Schema({
  googleId:               { type: String,  default: "" },
  token:                  { type: String,  default: "" },
  firstName:              String,
  lastName:               String,
  email:                  { type: String,  lowercase: true },
  password:               { type: String,  default: "" },
  phone:                  { type: Number,  default: 0 },
  sex:                    { type: String,  enum: ["Masculino", "Femenino", "Otro"],          required: true },
  document:               { type: Number,  default: 0 },
  documentType:           { type: String,  enum: ["CC", "CE", "Pasaporte"],                  required: true },
  birthdate:              String,
  roles:                  [{ name: String, value: String }],
  activate:               [{ name: String, value: String }],
  login_code:             { type: String,  default: "" },
  login_code_confirmed:   { type: String,  default: "" },
  code_newpass:           { type: String,  default: "" },
  code_confirm_pass:      { type: String,  default: "" },
}, { timestamps: true });

timestamps: true instructs Mongoose to automatically manage createdAt and updatedAt fields on every document. You do not need to set these manually.

Field reference

googleId

string

default:"\"\""

OAuth 2.0 subject identifier returned by Google Sign-In. Empty string for email/password accounts.

token

string

default:"\"\""

Current session or refresh token issued to the user. Rotated on each login.

firstName

string

User’s given name.

lastName

string

User’s family name.

string

Email address. Stored in lowercase regardless of how it was submitted.

password

string

default:"\"\""

Hashed password. Empty string for Google OAuth accounts.

phone

number

default:"0"

Contact phone number stored as a plain integer.

sex

string

required

Gender selection. One of "Masculino", "Femenino", or "Otro".

document

number

default:"0"

Government-issued ID number (numeric portion).

documentType

string

required

Type of identity document. One of "CC" (Cédula de Ciudadanía), "CE" (Cédula de Extranjería), or "Pasaporte".

birthdate

string

Date of birth stored as a free-form string (e.g., "1990-06-15").

roles

array

Array of { name, value } objects that grant access levels.

Show Role values

`value`	`name`	Meaning
`"1"`	`"Usuario"`	Standard shopper account
`"2"`	`"Admin"`	Store administrator

activate

array

Array of { name, value } objects that describe account status.

Show Activate values

`value`	`name`	Meaning
`"1"`	`"Activado"`	Account is active
`"2"`	`"Inactivo"`	Account is disabled

One-time code sent during a passwordless or two-step login flow.

Confirmation token set once login_code has been verified.

code_newpass

string

default:"\"\""

Temporary code issued when a password-reset request is initiated.

code_confirm_pass

string

default:"\"\""

Confirmation token set once the password-reset code has been consumed.

createdAt

Date

Timestamp of document creation, managed automatically by Mongoose (timestamps: true).

updatedAt

Date

Timestamp of the last document update, managed automatically by Mongoose (timestamps: true).

Product model

A Product document represents a single shirt listing. It holds merchandising data, size availability, pricing, stock count, and references to four image variants generated at upload time.

// src/models/Product.js (simplified)
const ProductSchema = new Schema({
  user:          { _id: String, firstName: String, lastName: String, roles: [...] },
  title:         String,
  description:   String,
  sizes:         [{ type: String, enum: ["XS", "S", "M", "L", "XL", "XXL"] }],
  price:         Number,
  imageUrlIp:    Array,   // Principal image  — 1500×2000 px  (3:4)
  imageUrlMn:    Array,   // Thumbnail        — 500×666 px    (3:4)
  imageUrlIdz:   Array,   // Detail/zoom      — 2000×2667 px  (3:4)
  imageUrlIc:    Array,   // Square catalog   — 1080×1080 px  (1:1)
  discount:      { type: String, default: "Sin descuento" },
  discountPrice: { type: String, default: "" },
  minCant:       Number,
  date:          { type: Date, default: Date.now },
}, { timestamps: true });

Field reference

user

object

Snapshot of the admin who created the listing. Embedding prevents the listing from breaking if the admin account is later modified.

Show Embedded user fields

user._id

string

MongoDB ObjectId of the creating admin.

user.firstName

string

Admin’s given name at time of creation.

user.lastName

string

Admin’s family name at time of creation.

user.roles

array

Role array copied from the admin’s User document.

title

string

Display name of the shirt (e.g., "Classic Oxford Shirt").

description

string

Long-form product description shown on the detail page.

sizes

array

Available sizes for this listing. Each entry is one of "XS", "S", "M", "L", "XL", or "XXL".

price

number

Base price in the store’s local currency (integer or float).

imageUrlIp

array

Principal image — full-size portrait (1500×2000 px, 3:4 ratio). Used as the primary product photo on listing and detail pages. See Image Processing for the full pipeline.

imageUrlMn

array

Thumbnail — small portrait (500×666 px, 3:4 ratio). Used in search results, carousels, and anywhere a compact image is needed.

imageUrlIdz

array

Detail/zoom — high-resolution portrait (2000×2667 px, 3:4 ratio). Loaded on demand when the shopper activates the zoom viewer.

imageUrlIc

array

Square catalog — square crop (1080×1080 px, 1:1 ratio). Used in grid-layout catalog views and social-media sharing cards.

discount

string

default:"\"Sin descuento\""

Human-readable discount label (e.g., "10% OFF"). Defaults to "Sin descuento" when no promotion is active.

discountPrice

string

default:"\"\""

The promotional price as a string when a discount is active. Empty string when discount is "Sin descuento".

minCant

number

Available stock count. Decremented when units are purchased. A value of 0 indicates the product is out of stock.

date

Date

Listing creation date. Defaults to Date.now at insert time. Distinct from createdAt — kept for legacy compatibility.

createdAt

Date

Automatic Mongoose timestamp for document creation.

updatedAt

Date

Automatic Mongoose timestamp for the last update.

Cart model

A Cart document represents one shopping session or historical order for a user. Rather than referencing products by ID, the cart embeds full product snapshots at the moment items are added. This means price changes, stock updates, or product deletions after the item was added to the cart will never silently alter what the customer sees at checkout.

// src/models/Carts.js (simplified)
const CartsSchema = new Schema({
  products: [{ /* full product snapshot + quantity fields */ }],
  user:     { /* buyer snapshot */ },
  cantBuy:  Number,
  subtotal: Number,
  date_creation_cart_client: { type: Date, default: Date.now },
}, { timestamps: true });

Field reference

products

array

Array of product snapshot objects. Each entry is a copy of the product’s fields at add-to-cart time, augmented with purchase-specific fields.

Show Embedded product snapshot fields

products[].user

object

Snapshot of the admin who owns the product listing, including their _id, firstName, lastName, roles, and activate arrays.

products[]._id

string

Original Product document _id.

products[].title

string

Product title at time of add.

products[].description

string

Product description at time of add.

products[].sizes

array

Size options copied from the product at time of add.

products[].price

number

Unit price at time of add.

products[].imageUrlIp

array

Principal image URLs copied from the product.

products[].discount

string

Discount label at time of add.

products[].discountPrice

string

Promotional price at time of add.

products[].minCant

number

Stock count at time of add.

products[].cantBuy

number

default:"0"

Quantity the buyer selected for this line item.

products[].subtotal

number

Line total: price × cantBuy (or discountPrice × cantBuy when applicable).

products[].date

Date

Original product listing date.

user

object

Snapshot of the buyer’s profile at the time the cart was created or last updated.

Show Embedded buyer fields

user._id

string

Buyer’s User document _id.

user.firstName

string

Buyer’s given name.

user.lastName

string

Buyer’s family name.

user.email

string

Buyer’s email address.

user.phone

number

Buyer’s phone number.

user.sex

string

Buyer’s gender.

user.document

string

Buyer’s ID number.

user.documentType

string

Buyer’s ID document type.

user.activate

array

Buyer’s activation status array.

cantBuy

number

Total number of individual units across all line items in the cart.

subtotal

number

Grand total for the entire cart — the sum of all products[].subtotal values.

date_creation_cart_client

Date

Timestamp recorded when the cart was first created on the client side. Defaults to Date.now.

createdAt

Date

Automatic Mongoose timestamp for document creation.

updatedAt

Date

Automatic Mongoose timestamp for the last update.

The embedded-document pattern

All three models make deliberate use of embedded documents rather than foreign-key references (ObjectId + populate).

Data consistency at a point in time

When a product is snapshotted into a cart, or when an admin’s identity is embedded inside a product, those values are frozen. Future edits to the source document do not cascade — the historical record stays intact.

Fewer round-trips

A single MongoDB read returns the cart complete with all product and buyer data. There are no secondary queries needed to resolve references, which reduces latency on hot paths like checkout and order history.

Simpler queries for analytics

Aggregation pipelines operating on the carts collection have direct access to product titles, prices, and buyer info without $lookup joins, making sales reports straightforward to write.

Trade-off: storage vs. flexibility

Embedding increases document size and means edits (e.g., correcting a product title) don’t propagate to existing carts. This is intentional for order integrity but should be considered when designing admin tooling.

When building admin dashboards that display live product data, always read from the products collection directly. The snapshots inside carts reflect what the customer saw at purchase time, not the current catalog state.

Getting Started

Authentication

Core Concepts

Data models: User, Product, and Cart schemas

User model

Field reference

Product model

Field reference

Cart model

Field reference

The embedded-document pattern

Data consistency at a point in time

Fewer round-trips

Simpler queries for analytics

Trade-off: storage vs. flexibility

Build docs developers (and LLMs) love

Getting Started

Authentication

Core Concepts

Documentation Index

​User model

​Field reference

​Product model

​Field reference

​Cart model

​Field reference

​The embedded-document pattern

Data consistency at a point in time

Fewer round-trips

Simpler queries for analytics

Trade-off: storage vs. flexibility

Build docs developers (and LLMs) love

User model

Field reference

Product model

Field reference

Cart model

Field reference

The embedded-document pattern