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
| Concern | Approach |
|---|---|
| Performance / SEO | SSR/ISR, CDN, Lighthouse CI gate (Testing) |
| Reliability | Event outbox, idempotent consumers, retries/DLQ |
| Security | OWASP ASVS + 12-factor (Security) |
| Observability | Central logs/metrics/traces, audit log on writes |
| i18n | Site + app + content multilingual (i18n Strategy) |