@pintahub/database-schemas

Shared Mongoose schema definitions for PintaHub microservices. This package is the single source of truth for all MongoDB data models — services import schemas from here to ensure consistency.

Installation

yarn add @pintahub/database-schemas

Peer dependencies (must be installed by the consumer):

• mongoose ^9.1.3
• schemis ^2.0.2

Usage

This package does not work standalone — it ships raw schemas that are registered through the schemis library.

1. Set up the database store

// src/connections/database.js
const {createConnection, createStore} = require('schemis')
const schemas = require('@pintahub/database-schemas')

const uri = process.env.MONGODB_URI || 'mongodb://localhost:27017/dev'
const connection = createConnection(uri)

const store = createStore({
    connection,
    schemas
})

module.exports = store

2. Use models in actions

const {getModel} = require('../../connections/database')

const Product = getModel('Product')

const product = await Product.findOne({_id: productId, store: storeId}).lean()
await Product.updateOne(
    {_id: productId},
    {$set: {status: 'active', updated_at: Date.now()}}
)

3. Populate references with explicit model

const {getModel} = require('../../connections/database')

const TransferJob = getModel('TransferJob')
const Product = getModel('Product')
const Store = getModel('Store')

const items = await TransferJob
    .find({store: storeId})
    .populate({path: 'product', model: Product, select: {title: 1, code: 1}})
    .populate({path: 'destination_store', model: Store, select: {name: 1}})
    .lean()

Directory Structure

schemas/              # Main schema files (~60 schemas)
schemas/types/        # Embedded sub-document types (BrandSettings, FacebookObject, …)
schemas/products/     # Product-specific embedded types (MediaObject, SeoObject, VideoObject)
index.js              # Exports the absolute path to schemas/ for schemis to load

Schema Catalog

Field-level documentation lives in JSDoc comments inside each schema file. This catalog is a quick map.

Accounts & Auth

Account, User, Store, Shop, ShopifyAPI

Products

Product, ProductFeature, ProductImage, ProductRaw, ProductType, ProductTag, ProductImport, Customize, CustomField, FieldSetting

Collections & Groups

Collection, Group, GroupItem, GroupArtwork

Orders & Fulfillment

Order, OrderItem, Fulfillment, Payout

Content & Pages

Post, Menu, MenuItem, AnnouncementBar

Media & Assets

Image, Artwork, Media, MediaUpload, TempUpload

Analytics & Tracking

StoreEvent, LatestEvent, RecentView, SearchTerm, FavoriteItem, TrackPage, MarketingCost

Short URLs

ShortUrl, ShortDomain, ShortLog, LogURL

Jobs & Events

ExportJob, TransferJob, WebhookEvent

Settings & Config

StoreSetting, BlockedLocation, Publication, ShopifyObject

Reports

CreatorReport, ProductReport

Reviews

Review

Embedded Types

schemas/types/: BrandSettings, DMCASetting, FacebookObject, FooterSetting, FreeShippingSetting, GoogleAnalytics, KlaviyoObject, MerchizeSettings, SocialsObject, TopBarSettings, TrustpilotObject

schemas/products/: MediaObject, SeoObject, VideoObject

schemas/ (root, embedded): MoneyObject, ImageObject, DimensionObject, PriceRange, FieldSetting

Conventions

• Each schema file exports a Mongoose Schema (not a Model) — consumers register models themselves via schemis.
• Multi-tenancy: most domain schemas include a store ObjectId ref, indexed for query performance.
• Timestamps: schemas use explicit created_at / updated_at Date fields (not Mongoose's timestamps option).
• Status fields use string enums (e.g. 'active'|'inactive', 'pending'|'completed'|'failed').
• Embedded types in schemas/types/ and schemas/products/ are declared with {_id: false}.
• TTL indexes are used for ephemeral data (events, webhooks, page tracking).
• Text indexes exist on Product (title, alternative_title, code, tags) and Order (name, id, email, phone).
• The Product schema also exposes a precomputed display_title field (alternative_title || title) for storefront search/display. Consumer services are responsible for setting it at write time.

Querying Tips

• Use .lean() for read-only queries — returns plain objects instead of Mongoose documents.
• Use .populate() with an explicit model parameter when crossing collections.
• Use Promise.all() for independent queries (e.g. find + countDocuments).
• Always filter by store for multi-tenant data.

Versioning

This package follows semver:

• Patch — JSDoc / docs only.
• Minor — new fields, new schemas, new indexes (backward compatible).
• Major — removing/renaming fields or schemas, changing field types, breaking index changes.

Bump the version in package.json whenever a schema change is committed.