Skip to main content

Tech Stack & Rationale

Every choice below is fixed by decisions in the plan. This page records why, so future contributors don't relitigate settled trade-offs.

At a glance​

LayerChoiceWhy
WebNext.js (App Router)SSR/ISR for SEO + performance + accessibility; mature i18n via next-intl
Web styling/UITailwindCSS + shadcn/ui + Tailwind UIUtility CSS; shadcn/ui (Radix-based, accessible, owned components) for app/dashboard; Tailwind UI blocks for marketing/storefront; CSS-variable theming = per-tenant runtime branding
MobileReact Native (monorepo)One codebase → Customer / Technician / Dealer apps; offline support for field
CommerceMedusaJS v2Headless commerce engine: cart/checkout/promotions/order-lifecycle/inventory/admin out of the box
Domain servicesNestJS (TypeScript)Structured DI/modules; same language as front + Medusa; easy hiring
Commerce DBPostgreSQLRequired by Medusa (MikroORM); strong integrity for money/orders/inventory
Domain/content DBMongoDBDocument shape fits service tickets, AMC, asset history, CMS content
Cache/queueRedis + BullMQCaching, sessions, event fan-out, delayed jobs (e.g. 7-day testimonial)
CMSPayload CMSDIY WYSIWYG, built-in localization, media, REST+GraphQL, runs on Mongo
NewsletterListmonk (self-hosted)Open-source bulk email; content authored in Payload
PaymentsHyperswitch (self-hosted)Payment orchestration → Razorpay / CCAvenue / Cashfree
CourierShiprocketIndia multi-courier aggregation via a Medusa fulfillment provider
Automationn8n (self-hosted) + Zapier + Pabblyn8n for internal orchestration (in-cluster, no per-task cost); Zapier/Pabbly for SaaS no-code
Object storageVultr Object Storage (S3-compatible)Per-tenant media + branding
OrchestrationKubernetes on VultrPer-tenant namespace isolation, templated deploys
DocsDocusaurusThis site; supports video tutorials via MDX
TestingPlaywright + Cypress + Lighthouse CIe2e + performance gates

Why Medusa (decision: keep)​

We evaluated building commerce ourselves on the polyglot stack vs. keeping Medusa (full comparison archived in the decision log). Verdict: keep Medusa. It provides the commerce internals most expensive to rebuild correctly — totals/tax math, promotions, order lifecycle, concurrency-safe inventory, and the admin UI — giving a weeks-not-months path to a rich D2C MVP.

The accepted cost is the Postgres↔Mongo bridge (see Eventing) and Medusa's D2C-leaning model, which we adapt for B2B/dealer/quote flows via custom pricing + the DMS service.

Why polyglot (Postgres + Mongo), not one DB​

  • Postgres is mandatory for Medusa and is the right home for money, orders, inventory reservations, and ledgers (ACID, relational integrity).
  • Mongo fits the document-shaped domains: a service ticket with nested visits/photos/parts, an asset with an open-ended event history, localized CMS blocks. Forcing these into rigid relational tables adds friction.
  • The boundary is deliberate and event-mediated. See Polyglot Data Stores.

Why NestJS for domains​

  • Same TypeScript across front-end, Medusa, and services → shared types, one hiring pool.
  • First-class modules/DI/guards/interceptors → clean RBAC + data-scoping.
  • Plays well with BullMQ, Mongoose, and OpenAPI generation.

Why Payload over Ghost (CMS/blog)​

  • Multilingual is a hard requirement (site + app + content). Payload has built-in localization; Ghost's i18n is weak.
  • Payload integrates with our auth/RBAC and per-tenant model; Ghost is a separate app/DB/admin.
  • Payload's block-based WYSIWYG matches the "DIY editor" requirement.
  • Newsletters are handled by Listmonk (Ghost's main extra) — so Ghost brings little we need. See Newsletter.

Why Hyperswitch (self-hosted)​

  • One orchestration layer in front of multiple Indian gateways (Razorpay/CCAvenue/Cashfree) → routing, retries, failover, unified reconciliation.
  • Self-hosting keeps card/payment data and routing rules under tenant control. See Payments.

Why per-tenant on Kubernetes​

  • Strong data isolation per brand (separate DBs/buckets).
  • Independent scaling and blast-radius containment.
  • One templated pipeline keeps code/config identical across tenants. See Deployment.

Notable constraints to remember​

  • Medusa = Postgres only. Never attempt Medusa on Mongo.
  • Money/ledgers belong in Postgres, even when a NestJS domain owns the workflow (e.g. dealer ledger): keep financial truth relational.
  • Domains never write Medusa tables — they react to events and store references.