Credenza – Distributed Marketplace Platform

A modular, event‑driven e‑commerce marketplace built as a constellation of Node.js microservices (Auth, Product, Cart, Order, Payment, Notification, Seller Dashboard, AI Buddy). Designed for horizontal scalability, real‑time user experience, and future AI‑assisted seller insights.

---

✨ Core Highlights

• Microservices Architecture: Independent deployable services with clear domain boundaries.
• Event‑Driven Communication: Lightweight broker + pub/sub for decoupled workflows (order lifecycle, notifications, inventory updates).
• Real‑Time UX: WebSocket (Socket.io) channels for live cart changes, order status transitions, notifications.
• Secure AuthN/Z: JWT + refresh tokens + role checks (buyer vs seller) + request validation.
• Performance Conscious: Redis caching + selective MongoDB indexing (reduces repeated reads and inter‑service latency).
• Test Coverage: Jest integration tests across Auth, Product, Cart, Order critical flows.
• Container Ready: Each service has a dockerfile enabling isolated build & run.
• Extensible AI Layer: "AI Buddy" service scaffold for contextual assistance / future RAG enrichment.

---

🧱 Service Overview

Service	Purpose	Key Features
Auth	Identity & sessions	Register, login, JWT/refresh, role guards
Product	Catalog management	Create/update/list products, seller scoping
Cart	User cart state	Add/remove/update items, quantity validation
Order	Order processing	Create order, get by id, list user orders, cancel
Payment	(Placeholder)	Future payment orchestration & status events
Notification	Outbound alerts	Email / real‑time notifications (listeners)
Seller Dashboard	Seller insights	Aggregate view for sellers (extensible)
AI Buddy	Contextual assistant	Planned RAG / guidance for sellers & support

Naming note: Some folders use borker (typo of broker); can be standardized later.

---

🗂️ Tech Stack

• Runtime: Node.js, Express
• Data: MongoDB (per service DB models), Redis (cache, pub/sub, session adjunct)
• Messaging: Custom lightweight broker pattern (in‑repo) / Redis pub/sub
• Real‑Time: Socket.io (WebSockets)
• Testing: Jest
• Containerization: Docker (individual service Dockerfiles)
• Future: Kubernetes (structurally ready), AI (RAG, embeddings), Metrics/Tracing

---

🔄 High-Level Architecture

[ Client ]
    | REST + WebSockets
    v
[ API Gateways / Service Routes ]
    |---------------------- Event Bus / Broker (Redis pub/sub) ----------------------|
  Auth   Product   Cart   Order   Payment   Notification   Seller Dash   AI Buddy
    |        |        |       |        |          |              |          |
 MongoDB  MongoDB  MongoDB  MongoDB   TBD       MongoDB        MongoDB     TBD
            ^          |        ^                               |
          Redis Cache / Session / Hot Data ----------------------

---

🔐 Security & Validation

• JWT access tokens + refresh token rotation
• Role-based guards (buyer vs seller endpoints)
• Input validation middleware (reject malformed data early)
• Centralized auth middleware shares decoded user context downstream

---

🚀 Getting Started

Prerequisites

• Node.js (LTS recommended)
• Docker (optional but recommended for parity)
• MongoDB & Redis instances (local or containerized)

Quick Start (Local Dev – individual service)

# Install deps for a service (example: auth)
cd auth
npm install
npm run dev # or: node server.js / nodemon

Suggested Environment Variables

Create a .env per service (example for auth):

PORT=4001
MONGO_URI=mongodb://localhost:27017/credenza_auth
JWT_SECRET=replace_me
REFRESH_SECRET=replace_me_too
REDIS_URL=redis://localhost:6379

(Replicate with service‑specific DB names.)

Running Multiple Services (manual approach)

Open terminals per service or script it (future improvement: Docker Compose / Procfile).

(Optional) Docker Build

# From a service directory (e.g., product)
docker build -t credenza-product:dev .
docker run -p 4002:4002 --env-file .env credenza-product:dev

(Add Compose file future: orchestrate all containers + shared Redis + Mongo.)

---

🧪 Testing

Each domain service with tests:

• auth/__tests__/*.test.js
• cart/tests/*.test.js
• order/tests/orders/*.test.js
• product/tests/*.test.js

Run (example product):

cd product
npm install
npm test

Ensure test DB URIs differ from production/local dev DB to avoid data pollution.

---

📨 Event / Message Flows (Conceptual)

Event	Emitted By	Consumed By	Purpose
user.registered	Auth	Notification, AI Buddy	Welcome email / future personalization
product.updated	Product	Cart, Notification	Sync cart items / alert watchers
cart.updated	Cart	Order	Prepare order validation
order.created	Order	Payment, Notification	Trigger payment workflow & notify
order.canceled	Order	Notification, Inventory	Inform stakeholders / restock
payment.succeeded	Payment	Order, Notification	Mark order paid, send receipt
payment.failed	Payment	Order, Notification	Mark order failed, alert user

(Replace placeholders as Payment logic matures.)

---

📊 Performance Considerations

• Redis caching for hot product reads / session context
• MongoDB indexes on frequently queried fields (e.g., userId, productId, order status)
• Potential batching of notification events
• Horizontal scale by replicating stateless service containers

Future: Add metrics (Prometheus/OpenTelemetry) + circuit breaker around external/payment calls.

---

🧠 AI Buddy (Planned)

• Context retrieval from past user/shop interactions
• RAG pipeline (vector store for product descriptions & support FAQs)
• Seller optimization prompts (pricing suggestions, inventory alerts)

---

🗺️ Roadmap / Future Enhancements

• Add API Gateway / reverse proxy (e.g., Nginx / Traefik)
• Centralized logging & tracing
• Docker Compose orchestration (all services + infra)
• Production‑grade payment integration (Stripe/Razorpay)
• Rate limiting & audit logs
• Kubernetes Helm charts
• OpenAPI / Swagger documentation per service
• CI pipeline (lint + test + build + image push)
• Metrics & dashboards

---

🤝 Contributing

1. Fork & branch (feature/<name>)
2. Add/update tests for changes
3. Ensure lint/test passes
4. Open PR with description & screenshots/logs if UI/UX/DevTool changes

---

📁 Repository Structure (excerpt)

ai-buddy/
auth/
cart/
notification/
order/
payment/
product/
seller-dashboard/

Each folder = isolated Node.js service with its own package.json and server.js entrypoint.

---

🧪 Suggested Test Scenarios (Beyond Current)

• Auth token refresh rotation & expiry rejection
• Concurrent cart modifications (race safety)
• Order creation with stale cart items
• Payment success & failure event cascade
• Notification delivery fallback (retry / DLQ concept)

---

🙋 FAQ (Seed)

Why microservices so early? Educational focus on boundaries & scaling patterns. Why Redis? Low-latency cache + pub/sub for lightweight event fan‑out. How to add a new service? Scaffold folder, add server.js, connect to Mongo, register routes, hook into broker/events.

---

Replace placeholder secrets & metrics with real measured values once load tests are executed.