System Architecture
Topology
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.
Multi-Tenancy & White-Label
Model: per-tenant deployment
Polyglot Data Stores
Two primary databases, each doing what it is best at, plus Redis and object storage. The golden rule:
Eventing & Integration
The platform is event-driven: Medusa and the NestJS domains stay coherent by exchanging domain events, not by sharing tables. This is the seam that makes the polyglot split safe.
Auth, RBAC & Data-Scoping
The platform serves five persona families with very different rights, plus a data-scoping requirement from the notes: "managers see across vendors, or only the vendor assigned to them." RBAC alone (what actions) is not enough — we also enforce row-level scope (which records).
Eventing Reliability & Operations Runbook
How the event/notification pipeline behaves under load and failure, what it
Security (OWASP & 12-Factor)
Security baseline for every service and every tenant. Two reference frames: OWASP ASVS / Top 10 (application security) and 12-Factor (config/operations hygiene).
Internationalization (i18n) Strategy
Requirement (notes #3): the entire website and app are multilingual. India-first means English + major vernaculars (Hindi, Tamil, Telugu, Marathi, Bengali, …), configurable per tenant.
Frontend & Design System
The web frontend (Next.js) is built on TailwindCSS + shadcn/ui + Tailwind UI. This page defines what each is for, how they compose, and — crucially — how they deliver per-tenant runtime branding without code changes.
Media Storage & CDN (S3/B2 + KeyCDN)
All platform media — product images (Medusa), CMS media / blog images / 360° frames (Payload), and generated invoice PDFs (API) — is stored in one S3/B2 bucket and served through a KeyCDN pull zone. Public assets resolve to CDN URLs; private assets (invoices) use short‑lived signed URLs. Every integration is gated on S3_BUCKET, so local dev with no credentials falls back to on‑disk storage and the app keeps working.