gram-backend

bysahil chouhan

# Gramyra Backend PRD — Scalable MERN System Site ref: gramyra-ghee-care.lovable.app (current: Lovable/React frontend + Shopify Storefront API). Goal: replace Shopify backend, own scalable MERN system. ## 1. Problem Shopify handle product+payment now. Limit: no control over data model, no custom logic (courier registry, SEO blog gen, loyalty later), vendor lock-in, cost scale with GMV. Need own backend, API-first, frontend stay React (swap Storefront calls to own API). ## 2. Goals - Product catalog + inventory own DB, not Shopify. - Checkout: Razorpay direct integration. - Shipping: Shadowfax via courier-registry pattern (pluggable, swap/add courier later — Delhivery, Shiprocket). - Order tracking page (`/orders`) backed by own order + shipment status. - Reviews (moderated, per product). - Newsletter signup. - Blog/SEO content, AI-generated via Claude API. - Scale target: launch small (Delhi NCR, low order volume), architecture must not need rewrite at 10x–100x order volume. ## 3. Non-Goals (v1) No multi-vendor marketplace. No native mobile app. No subscription/recurring orders yet (flag for v2). ## 4. High-Level Architecture ``` [React frontend (Lovable)] | [API Gateway / Express REST] | ------------------------------------------------- | | | | | Product Order Payment Shipping Content Service Service Service Service Service | | | | | MongoDB MongoDB Razorpay Shadowfax MongoDB webhook (+registry) + Claude API ``` Monolith first (single Node/Express app, modular by domain folder), NOT microservices day 1. Split into services later only when a domain outgrows shared deploy (order volume, team size). Premature microservice split = wasted effort at this stage. ## 5. Core Modules ### 5.1 Product Service - Mongo collection `products`, sub-doc `variants` (size, price, stock, SKU). - Inventory decrement on order confirm, not on cart add (avoid oversell/lock race — use atomic `findOneAndUpdate` with stock check). - Cache product listing + single product in Redis, TTL 5–10 min, invalidate on admin update. ### 5.2 Order Service - Order states: `created → payment_pending → paid → packed → shipped → delivered → cancelled/returned`. - Order doc: buyer info, items, amounts, paymentId, shipmentId, status history array (for audit + tracking page). - Idempotency key on order creation (prevent double order on client retry). ### 5.3 Payment Service (Razorpay) - Create order → Razorpay order → client checkout → webhook confirm (never trust client-side success callback alone). - Webhook signature verify mandatory. Webhook handler idempotent (Razorpay may retry). - Store raw webhook payload for audit/dispute. ### 5.4 Shipping Service (Courier Registry Pattern) - Interface: `createShipment()`, `trackShipment()`, `cancelShipment()`. - Registry map: `{ shadowfax: ShadowfaxAdapter, shiprocket: ShiprocketAdapter, ... }`. - Config-driven courier selection per order (pincode/weight rule later). - Adapter translate Gramyra order → courier-specific payload, normalize courier response back to common shape. - Scales: add courier = new adapter, zero change to Order Service. ### 5.5 Content/SEO Service - Blog posts collection, Claude API call for draft generation (async job, not blocking request — use queue). - Editor approval before publish (no auto-publish AI content). ### 5.6 Review Service - Reviews tied to `productId`, status `pending/approved/rejected`. - Rate limit review submission per IP/email (spam control). ## 6. Data Layer - MongoDB primary store (Atlas, managed — auto-scaling, replica set for read scale + failover). - Redis: cache layer (product listing, session, rate-limit counters) + BullMQ job queue (SEO gen, email, webhook retry). - Indexes: `products.slug`, `orders.userId+createdAt`, `orders.status`, `reviews.productId+status`. ## 7. API Design REST, versioned (`/api/v1/...`). JSON. Auth: JWT for admin/user, public GET endpoints unauthenticated (product list, single product). Key endpoints: - `GET /api/v1/products`, `GET /api/v1/products/:slug` - `POST /api/v1/orders`, `GET /api/v1/orders/:id/track` - `POST /api/v1/payments/webhook` - `POST /api/v1/reviews`, `GET /api/v1/reviews/:productId` - `POST /api/v1/newsletter/subscribe` - `POST /api/v1/admin/blog/generate` (internal, queued) ## 8. Scalability Plan - Stateless Express app → horizontal scale via multiple instances behind load balancer (Nginx / cloud LB). No in-memory session, JWT stateless. - Docker containerize each module now (even in monolith) — eases future split + matches Sahil existing Docker/Jenkins/ECR skill. - Deploy: ECR + EC2 (or ECS) + CI/CD via Jenkins (leverage existing redBus pipeline experience). - DB scale: start single Atlas cluster, add read replica when read QPS grow, shard only if truly needed (unlikely near-term at D2C scale). - Cache-aside pattern for product reads — biggest scale win, cheap. - Queue heavy/slow work (AI content gen, email, webhook retries) off request path via BullMQ + Redis. - Rate limiting (Redis-based) on public write endpoints — review, newsletter, order creation — prevent abuse. - Logging/monitoring: structured logs (pino/winston), ship to CloudWatch; add basic uptime + error alert (Sentry) before scale, not after. ## 9. Security - Env-based secrets (no key in code) — matches your existing `ROUTE_ENGINE_...` pattern learning from redBus work. - Razorpay webhook signature check mandatory. - Input validation (Zod/Joi) on every write endpoint. - HTTPS only, CORS locked to known frontend origin. ## 10. Tech Stack Summary Node.js + Express, MongoDB (Atlas), Redis (cache + BullMQ), Razorpay SDK, Shadowfax API (via adapter), Claude API (blog gen), Docker, Jenkins CI/CD, AWS (EC2/ECR/S3). ## 11. Milestones 1. Core: product + order + Razorpay payment (replace Shopify checkout). 2. Shadowfax shipping integration + order tracking page live. 3. Reviews + newsletter migrate off current forms. 4. Redis cache + queue layer harden. 5. SEO/blog tool go live. 6. Load test, add monitoring/alerting, then open scale (ads, higher traffic). ## 12. Open Questions - Expected order volume at launch vs 6-month target? (sizes infra choice — single EC2 vs ECS from day 1) - Multi-courier needed at launch, or Shadowfax-only v1 sufficient? - Admin panel: build custom or reuse a lightweight open-source admin (Retool/AdminJS) to save time? give me backend design using node and complete architecture