System Overview & Architecture Index

The master blueprint and navigation hub for the Reshma-Core Backend.

---

1. Core Architectural Philosophy

Reshma-Core is built to scale gracefully while handling highly diverse e-commerce requirements. The backend enforces the following technical standards:

1. Domain-Driven Design (DDD): Code is logically grouped by business feature (Users, Auth, Products) rather than technical layers.
2. Strict Type Safety: Zod enforces runtime payload validation at the Controller boundary, while strict TypeScript ensures compile-time safety.
3. Fail-Fast Initialization: The system refuses to boot if critical environment variables are missing or malformed.
4. Polymorphic Database Strategy: Using Mongoose discriminators, disparate items (e.g., Glass Bangles and Unstitched Fabrics) share a common Products collection while enforcing strictly unique validation rules.

---

2. Master Documentation Index

Use the links below to navigate the internal documentation of the Reshma-Core system.

Architecture Diagrams & Security

High-level system design, security protocols, and database schemas.

• Authentication & Security Architecture – Two‑token JWT, Google OAuth, OTP flows.
• Database Design & Polymorphic Catalog – Single‑collection polymorphism, discriminators, indexes.
• Product Catalog Schema – Field‑by‑field mapping for bangles, apparel, fabrics, etc.
• Security Hardening – Helmet, rate limiting, Zod firewalls, CodeQL mitigations.
• Middleware & Validation – Request lifecycle, sanitisation, distributed rate limiting.
• Payment Integration (Razorpay) – HMAC‑SHA256, ACID transactions, webhooks.
• Legal & Tax Compliance – Dynamic Indian GST, proportional discounting, DPDP/GDPR.
• Edge Cache – Redis proxy pattern, cache invalidation, thundering herd protection.
• Background Jobs & Cron – BullMQ queues, email/invoice/export workers, Redis distributed locks.
• Logistics & Shipping – Shiprocket integration, rolling JWT, webhook state machine.
• Media & Storage – Cloudinary memory‑stream uploads, orphan cleanup.
• DevOps & Infrastructure – Horizontal scaling, graceful shutdown, Docker, logging.

Domain Modules

Deep dives into specific business logic, DTOs, and services.

• User Module – Identity, RBAC, password hashing, address book.
• Authentication Module – Login, registration, token issuance.
• Notification Engine – BullMQ workers, SMTP, in‑app alerts.
• Product Module – Catalog engine, Cloudinary rollbacks, discriminators.
• Cart Module – Dynamic pricing, attribute hashing, guest merging.
• Order Module – Atomic checkout, payment webhooks, Shiprocket dispatch.
• Return Module – RMA state machine, Razorpay refunds, atomic restocks.
• Interaction Module – Threaded comments, async aggregation, verified purchases.
• Coupon Module – Temporal firewalls, cart auto‑recalculation, TOCTOU defence.
• Wishlist Module – Lazy initialisation, atomic arrays, move‑to‑cart pipeline.
• Search Module – Typesense RAM cluster, eventual consistency, faceted discovery.
• Dashboard Module – MongoDB $facet aggregations, financial reporting.
• Support Module – Polymorphic ticketing, threaded conversations, privacy anonymisation.
• Health Module – Deep liveness probes, dependency checks.

API Standards & Testing

Rules for RESTful communication and manual runbooks.

• API Design Standards – Frontend integration & payload shapes.
• Global Error Codes – Standardised HTTP responses.
• Auth Runbook – Manual integration testing.
• Product Runbook – Polymorphic creation and image uploads.
• (Other runbooks are available under docs/api/thunder-tests/)

Setup & Deployment

Guides for local development and production.

• Local Development Setup – Node, MongoDB, Redis boot guide.
• Environment Variables Guide – Zod validation & .env mapping.
• Database Seeding – Generating 500 realistic products.

---

3. Implementation Roadmap

The development of Reshma-Core is divided into five major phases (all completed).

Phase 1: The Foundation (Completed)

• Environment validation & fail‑fast server boot.
• Global error handling & Zod interceptors.
• User domain schema & RBAC.
• Two‑token authentication (JWT + HttpOnly cookies).
• Google OAuth (client‑side token flow).
• Background notification engine (BullMQ + Redis).

Phase 2: The Core Catalog Engine (Completed)

• Base Product schema.
• Mongoose discriminators for bangles, apparel, fabrics, etc.
• Cloudinary image pipeline (memory buffers & rollbacks).
• Category & inventory tracking.

Phase 3: The Transaction Pipeline (Completed)

• Cart management (guest merge, live pricing).
• Dynamic checkout math (GST, shipping).
• Razorpay payment gateway integration.
• Order generation & status webhooks.

Phase 4: Operations & Analytics (Completed)

• Return arbitration engine.
• Interaction engine (reviews, comments, voting).
• Admin dashboard aggregations (sales, top products).

Phase 5: Production Hardening & Scalability (Completed)

• Legal & financial compliance (line‑item GST, immutable snapshots).
• Edge cache & workers (Redis proxy, BullMQ PDF generation).
• DevOps & infrastructure (distributed rate limiting, deep health checks, NoSQL defence).

---

Maintained by Md Afzal Ansari | The Reshma-Core Team