Skip to main content

System Architecture

Topology​

Layers​

1. Clients​

  • Next.js storefront — SEO/accessibility/Lighthouse-tuned; resolves tenant by domain; localized via next-intl.
  • React Native apps (monorepo): Customer, Technician (offline-first), Dealer.
  • Admin — Medusa Admin (commerce ops) + custom Next.js team dashboards (marketing / finance / technician-head) with role-scoped BI.

2. Edge​

  • CDN + WAF for assets and protection.
  • API Gateway / BFF — single entry; handles auth (JWT/session), tenant resolution, routing to Medusa vs domain services, rate-limiting, request shaping for each client.

3. Commerce core — MedusaJS (PostgreSQL)​

Owns everything transactional-commerce: catalog/PIM, orders/OMS, sales channels (self + Amazon + Flipkart), tiered pricing, promotions, payments, fulfillment, inventory. See Tech-Stack Rationale and Polyglot Data Stores.

4. Domain services — NestJS (MongoDB)​

Bespoke business that Medusa does not model: FSM/Service, Warranty & Assets, DMS, Loyalty/Affiliate, CRM, Notifications, Tenant Config, Analytics/BI. Each is a module with its own collections; they never write Medusa's tables — they react to events.

5. Content​

  • Payload CMS (Mongo) — blog, pages, testimonials, FAQ, case studies; DIY WYSIWYG + localization.
  • Listmonk — bulk newsletters.

6. Integrations​

  • Hyperswitch (self-hosted) → Razorpay / CCAvenue / Cashfree.
  • Shiprocket → courier fulfillment (Medusa provider).
  • Amazon SP-API / Flipkart Seller API → channel sync (custom).
  • Zapier / Pabbly Connect → outward automation webhooks for no-code workflows. See Automation.

7. Data​

  • PostgreSQL — Medusa.
  • MongoDB — NestJS domains + Payload.
  • Redis — cache, sessions, BullMQ queues.
  • Object Storage (Vultr S3-compatible) — media + per-tenant branding assets.

Commerce ↔ Domain boundary (the most important seam)​

Commerce data (orders, products, customers) lives in Medusa/Postgres. Service/warranty/DMS data lives in NestJS/Mongo. They are kept coherent by an event bridge, not by shared tables:

  • Medusa emits events (order.placed, order.delivered, customer.created, …).
  • A subscriber publishes them to BullMQ (Redis).
  • Domain services consume and maintain their own read-side references (e.g. the Warranty service stores medusaOrderId, medusaProductId, denormalized snapshots).

This keeps a clean dependency direction and lets each side scale and deploy independently. Full detail in Eventing & Integration.

Per-tenant isolation​

Each tenant is a dedicated namespace with its own Medusa, NestJS, Payload, Postgres, Mongo, Redis, and bucket — deployed from one templated pipeline. See Multi-Tenancy & White-Label and Deployment.

Non-functionals​

ConcernApproach
Performance / SEOSSR/ISR, CDN, Lighthouse CI gate (Testing)
ReliabilityEvent outbox, idempotent consumers, retries/DLQ
SecurityOWASP ASVS + 12-factor (Security)
ObservabilityCentral logs/metrics/traces, audit log on writes
i18nSite + app + content multilingual (i18n Strategy)