Polyglot Data Stores
Two primary databases, each doing what it is best at, plus Redis and object storage. The golden rule:
Money, orders, inventory, ledgers → PostgreSQL. Documents, history, content → MongoDB. Each fact has exactly one owner.
Ownership map
| Store | Owner | Holds |
|---|---|---|
| PostgreSQL | Medusa | products, variants, options, kits, categories, pricing/price-lists, carts/orders, promotions, inventory + reservations, sales channels, payments, fulfillment, customers, customer groups, tax |
| PostgreSQL | Finance (NestJS, see note) | dealer ledgers, GST documents, payouts, reconciliation — relational financial truth |
| MongoDB | FSM | service tickets, jobs/visits, AMC contracts, SLA timers, technician profiles |
| MongoDB | Warranty | assets (serial lifecycle), registrations, warranty claims, external assets |
| MongoDB | DMS | channel partners, tiers, KYC, targets, schemes, beat plans |
| MongoDB | Loyalty | points ledgers (non-financial), tiers, affiliate links/attribution |
| MongoDB | CRM | customer 360 projections, segments |
| MongoDB | Payload | posts, pages, testimonials, FAQ, media metadata |
| MongoDB | Tenant Config | branding + feature flags + behavior |
| Redis | shared | cache, sessions, BullMQ queues + delayed jobs |
| Object Storage | shared | media, branding assets, generated PDFs |
Note on financial data in NestJS: even though the dealer-ledger workflow lives in a NestJS domain, the ledger itself is stored in Postgres for ACID + auditability. NestJS domains may therefore use both Mongo (operational/document data) and a Postgres schema (financial records). Mongo is the default; Postgres is used wherever money correctness matters.
What crosses the boundary (and how)
Domain services frequently need commerce facts (which order, which product, which customer). They get them by reference + denormalized snapshot, never by querying Medusa's tables directly.
- Each domain document stores the Medusa IDs it relates to (
medusaOrderId,medusaProductId,medusaCustomerId). - It also stores a snapshot of the fields it needs to display/reason about, so it is not coupled to live Medusa reads.
- If fuller commerce data is needed on demand, the BFF composes it by calling Medusa's API — but transactional logic in a domain never depends on a synchronous Medusa call.
Consistency model
- Source of truth for a fact is its owner store only.
- Cross-store updates are eventually consistent via events (see Eventing).
- Consumers are idempotent (dedupe on event id) and use an outbox on the producing side so an event is never lost if a write commits.
Anti-patterns (do not do)
- ❌ A NestJS service writing into Medusa's Postgres tables.
- ❌ Storing money/inventory truth in Mongo "for convenience."
- ❌ Two stores both claiming to own the same fact.
- ❌ Synchronous cross-store joins inside a transaction.
Backups & migration
- Postgres and Mongo each have independent backup schedules per tenant.
- Migrations: Medusa migrations (Postgres) run via Medusa CLI; Mongo schema evolution is handled by versioned migration scripts in each NestJS service.