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
| Layer | Choice | Why |
|---|---|---|
| Web | Next.js (App Router) | SSR/ISR for SEO + performance + accessibility; mature i18n via next-intl |
| Web styling/UI | TailwindCSS + shadcn/ui + Tailwind UI | Utility CSS; shadcn/ui (Radix-based, accessible, owned components) for app/dashboard; Tailwind UI blocks for marketing/storefront; CSS-variable theming = per-tenant runtime branding |
| Mobile | React Native (monorepo) | One codebase → Customer / Technician / Dealer apps; offline support for field |
| Commerce | MedusaJS v2 | Headless commerce engine: cart/checkout/promotions/order-lifecycle/inventory/admin out of the box |
| Domain services | NestJS (TypeScript) | Structured DI/modules; same language as front + Medusa; easy hiring |
| Commerce DB | PostgreSQL | Required by Medusa (MikroORM); strong integrity for money/orders/inventory |
| Domain/content DB | MongoDB | Document shape fits service tickets, AMC, asset history, CMS content |
| Cache/queue | Redis + BullMQ | Caching, sessions, event fan-out, delayed jobs (e.g. 7-day testimonial) |
| CMS | Payload CMS | DIY WYSIWYG, built-in localization, media, REST+GraphQL, runs on Mongo |
| Newsletter | Listmonk (self-hosted) | Open-source bulk email; content authored in Payload |
| Payments | Hyperswitch (self-hosted) | Payment orchestration → Razorpay / CCAvenue / Cashfree |
| Courier | Shiprocket | India multi-courier aggregation via a Medusa fulfillment provider |
| Automation | n8n (self-hosted) + Zapier + Pabbly | n8n for internal orchestration (in-cluster, no per-task cost); Zapier/Pabbly for SaaS no-code |
| Object storage | Vultr Object Storage (S3-compatible) | Per-tenant media + branding |
| Orchestration | Kubernetes on Vultr | Per-tenant namespace isolation, templated deploys |
| Docs | Docusaurus | This site; supports video tutorials via MDX |
| Testing | Playwright + Cypress + Lighthouse CI | e2e + 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.