# vinayak2006tech/shopsphere architecture

> Architecture diagram of the GitHub repository vinayak2006tech/shopsphere, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vinayak2006tech/shopsphere
- Repository: https://github.com/vinayak2006tech/shopsphere

## Overview

ShopSphere is a distributed e-commerce platform. A customer uses the React storefront to browse products, authenticate, manage a cart, and submit an order; the gateway routes requests to independent services. Order creation starts an asynchronous inventory-and-payment saga, while events also support notifications, search, recommendations, and review-driven catalog updates. The graph preserves README-documented capabilities where implementation excerpts are absent; dashed edges mark documented event relationships not directly shown in sampled caller code.

Main entry points: [`services/order-service/src/rabbitmq.ts`](https://github.com/vinayak2006tech/shopsphere/blob/main/services/order-service/src/rabbitmq.ts) (RabbitMQ events), [`gateway/src/index.ts`](https://github.com/vinayak2006tech/shopsphere/blob/main/gateway/src/index.ts) (API gateway), [`services/product-service/src/product.controller.ts`](https://github.com/vinayak2006tech/shopsphere/blob/main/services/product-service/src/product.controller.ts) (Product catalog), [`services/order-service/src/order.controller.ts`](https://github.com/vinayak2006tech/shopsphere/blob/main/services/order-service/src/order.controller.ts) (Order handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_storefront["Storefront"]
  node_web["React storefront<br/>[App.tsx]"]
  node_authui["Auth state &amp; UI<br/>[AuthContext.tsx]"]
  node_storeapi["Storefront API<br/>[api.ts]"]
end

subgraph group_edge["Gateway"]
  node_gateway["API gateway<br/>[index.ts]"]
end

subgraph group_commerce["Commerce Services"]
  node_authsvc["Authentication<br/>[auth.service.ts]"]
  node_authdb[("Auth PostgreSQL<br/>[db.ts]")]
  node_catalog["Product catalog"]
  node_catalogdb[("Product records<br/>[product.model.ts]")]
  node_orders["Order handling"]
  node_orderdb[("Order PostgreSQL<br/>[db.ts]")]
  node_payments["Payment processing<br/>[payment.service.ts]"]
  node_paymentdb[("Payment ledger<br/>[db.ts]")]
  node_notifications["Notifications &amp; mail<br/>[index.ts]"]
  node_mailer["SMTP mailer<br/>[mailer.ts]"]
end

subgraph group_discovery["Discovery &amp; Trust"]
  node_reviews[("Reviews &amp; ratings<br/>[review.model.ts]")]
  node_search["Typo-tolerant search<br/>[search-index.ts]"]
  node_recommendations["Recommendations<br/>[main.py]"]
end

subgraph group_messaging["Events &amp; State"]
  node_redis[("Redis cache<br/>[redis.ts]")]
  node_rabbit["RabbitMQ events<br/>[rabbitmq.ts]"]
end

node_customer(("Customer"))

node_customer -->|"browses and orders"| node_web
node_web -->|"requests data"| node_storeapi
node_web -->|"renders"| node_authui
node_authui -->|"authenticates via"| node_storeapi
node_storeapi -.->|"calls API"| node_gateway
node_gateway -->|"proxies auth"| node_authsvc
node_gateway -.->|"proxies catalog"| node_catalog
node_gateway -->|"proxies orders"| node_orders
node_gateway -.->|"proxies payments"| node_payments
node_gateway -->|"proxies notifications"| node_notifications
node_gateway -->|"proxies reviews"| node_reviews
node_gateway -.->|"proxies search"| node_search
node_gateway -.->|"proxies recommendations"| node_recommendations
node_authsvc -->|"reads and writes"| node_authdb
node_orders -->|"persists orders"| node_orderdb
node_orders -->|"publishes order.created"| node_rabbit
node_rabbit -.->|"delivers order events"| node_catalog
node_catalog -->|"reads and updates"| node_catalogdb
node_catalog -->|"caches and invalidates"| node_redis
node_catalog -->|"publishes stock events"| node_rabbit
node_rabbit -.->|"delivers inventory events"| node_payments
node_payments -->|"records payments"| node_paymentdb
node_payments -->|"publishes payment outcomes"| node_rabbit
node_rabbit -.->|"delivers payment outcomes"| node_orders
node_rabbit -.->|"delivers commerce events"| node_notifications
node_notifications -->|"sends email"| node_mailer
node_reviews -.->|"publishes review.created"| node_rabbit
node_rabbit -.->|"delivers review events"| node_catalog
node_rabbit -.->|"delivers stock events"| node_search
node_rabbit -.->|"delivers order events"| node_recommendations

click node_web "https://github.com/vinayak2006tech/shopsphere/blob/main/frontend/src/App.tsx"
click node_authui "https://github.com/vinayak2006tech/shopsphere/blob/main/frontend/src/context/AuthContext.tsx"
click node_storeapi "https://github.com/vinayak2006tech/shopsphere/blob/main/frontend/src/api.ts"
click node_gateway "https://github.com/vinayak2006tech/shopsphere/blob/main/gateway/src/index.ts"
click node_authsvc "https://github.com/vinayak2006tech/shopsphere/blob/main/services/auth-service/src/auth.service.ts"
click node_authdb "https://github.com/vinayak2006tech/shopsphere/blob/main/services/auth-service/src/db.ts"
click node_catalog "https://github.com/vinayak2006tech/shopsphere/blob/main/services/product-service/src/product.controller.ts"
click node_catalogdb "https://github.com/vinayak2006tech/shopsphere/blob/main/services/product-service/src/product.model.ts"
click node_orders "https://github.com/vinayak2006tech/shopsphere/blob/main/services/order-service/src/order.controller.ts"
click node_orderdb "https://github.com/vinayak2006tech/shopsphere/blob/main/services/order-service/src/db.ts"
click node_payments "https://github.com/vinayak2006tech/shopsphere/blob/main/services/payment-service/src/payment.service.ts"
click node_paymentdb "https://github.com/vinayak2006tech/shopsphere/blob/main/services/payment-service/src/db.ts"
click node_notifications "https://github.com/vinayak2006tech/shopsphere/blob/main/services/notification-service/src/index.ts"
click node_mailer "https://github.com/vinayak2006tech/shopsphere/blob/main/services/notification-service/src/mailer.ts"
click node_reviews "https://github.com/vinayak2006tech/shopsphere/blob/main/services/review-service/src/review.model.ts"
click node_search "https://github.com/vinayak2006tech/shopsphere/blob/main/services/search-service/src/search-index.ts"
click node_recommendations "https://github.com/vinayak2006tech/shopsphere/blob/main/services/recommendation-service/main.py"
click node_redis "https://github.com/vinayak2006tech/shopsphere/blob/main/services/product-service/src/redis.ts"
click node_rabbit "https://github.com/vinayak2006tech/shopsphere/blob/main/services/order-service/src/rabbitmq.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_authui,node_storeapi toneBlue
class node_gateway toneAmber
class node_authsvc,node_authdb,node_catalog,node_catalogdb,node_orders,node_orderdb,node_payments,node_paymentdb,node_notifications,node_mailer toneMint
class node_reviews,node_search,node_recommendations toneRose
class node_redis,node_rabbit,node_customer toneIndigo
```

## Components

### Storefront

- [React storefront](https://github.com/vinayak2006tech/shopsphere/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Auth state & UI](https://github.com/vinayak2006tech/shopsphere/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`
- [Storefront API](https://github.com/vinayak2006tech/shopsphere/blob/main/frontend/src/api.ts): `frontend/src/api.ts`

### Gateway

- [API gateway](https://github.com/vinayak2006tech/shopsphere/blob/main/gateway/src/index.ts): `gateway/src/index.ts`

### Commerce Services

- [Authentication](https://github.com/vinayak2006tech/shopsphere/blob/main/services/auth-service/src/auth.service.ts): `services/auth-service/src/auth.service.ts`
- [Auth PostgreSQL](https://github.com/vinayak2006tech/shopsphere/blob/main/services/auth-service/src/db.ts): `services/auth-service/src/db.ts`
- [Product catalog](https://github.com/vinayak2006tech/shopsphere/blob/main/services/product-service/src/product.controller.ts): `services/product-service/src/product.controller.ts`
- [Product records](https://github.com/vinayak2006tech/shopsphere/blob/main/services/product-service/src/product.model.ts): `services/product-service/src/product.model.ts`
- [Order handling](https://github.com/vinayak2006tech/shopsphere/blob/main/services/order-service/src/order.controller.ts): `services/order-service/src/order.controller.ts`
- [Order PostgreSQL](https://github.com/vinayak2006tech/shopsphere/blob/main/services/order-service/src/db.ts): `services/order-service/src/db.ts`
- [Payment processing](https://github.com/vinayak2006tech/shopsphere/blob/main/services/payment-service/src/payment.service.ts): `services/payment-service/src/payment.service.ts`
- [Payment ledger](https://github.com/vinayak2006tech/shopsphere/blob/main/services/payment-service/src/db.ts): `services/payment-service/src/db.ts`
- [Notifications & mail](https://github.com/vinayak2006tech/shopsphere/blob/main/services/notification-service/src/index.ts): `services/notification-service/src/index.ts`
- [SMTP mailer](https://github.com/vinayak2006tech/shopsphere/blob/main/services/notification-service/src/mailer.ts): `services/notification-service/src/mailer.ts`

### Discovery & Trust

- [Reviews & ratings](https://github.com/vinayak2006tech/shopsphere/blob/main/services/review-service/src/review.model.ts): `services/review-service/src/review.model.ts`
- [Typo-tolerant search](https://github.com/vinayak2006tech/shopsphere/blob/main/services/search-service/src/search-index.ts): `services/search-service/src/search-index.ts`
- [Recommendations](https://github.com/vinayak2006tech/shopsphere/blob/main/services/recommendation-service/main.py): `services/recommendation-service/main.py`

### Events & State

- [Redis cache](https://github.com/vinayak2006tech/shopsphere/blob/main/services/product-service/src/redis.ts): `services/product-service/src/redis.ts`
- [RabbitMQ events](https://github.com/vinayak2006tech/shopsphere/blob/main/services/order-service/src/rabbitmq.ts): `services/order-service/src/rabbitmq.ts`

### Other components

- **Customer**

## Connections

- Customer → React storefront: browses and orders
- React storefront → Storefront API: requests data (evidence: `frontend/src/App.tsx`)
- React storefront → Auth state & UI: renders (evidence: `frontend/src/App.tsx`)
- Auth state & UI → Storefront API: authenticates via (evidence: `frontend/src/context/AuthContext.tsx`)
- Storefront API → API gateway: calls API
- API gateway → Authentication: proxies auth (evidence: `gateway/src/index.ts`)
- API gateway → Product catalog: proxies catalog
- API gateway → Order handling: proxies orders (evidence: `gateway/src/index.ts`)
- API gateway → Payment processing: proxies payments
- API gateway → Notifications & mail: proxies notifications (evidence: `gateway/src/index.ts`)
- API gateway → Reviews & ratings: proxies reviews (evidence: `gateway/src/index.ts`)
- API gateway → Typo-tolerant search: proxies search
- API gateway → Recommendations: proxies recommendations
- Authentication → Auth PostgreSQL: reads and writes (evidence: `services/auth-service/src/auth.service.ts`)
- Order handling → Order PostgreSQL: persists orders (evidence: `services/order-service/src/order.controller.ts`)
- Order handling → RabbitMQ events: publishes order.created (evidence: `services/order-service/src/order.controller.ts`)
- RabbitMQ events → Product catalog: delivers order events
- Product catalog → Product records: reads and updates (evidence: `services/product-service/src/product.controller.ts`)
- Product catalog → Redis cache: caches and invalidates (evidence: `services/product-service/src/product.controller.ts`)
- Product catalog → RabbitMQ events: publishes stock events (evidence: `services/product-service/src/product.controller.ts`)
- RabbitMQ events → Payment processing: delivers inventory events
- Payment processing → Payment ledger: records payments (evidence: `services/payment-service/src/payment.service.ts`)
- Payment processing → RabbitMQ events: publishes payment outcomes (evidence: `services/payment-service/src/payment.service.ts`)
- RabbitMQ events → Order handling: delivers payment outcomes (evidence: `services/order-service/src/order.controller.ts`)
- RabbitMQ events → Notifications & mail: delivers commerce events
- Notifications & mail → SMTP mailer: sends email (evidence: `services/notification-service/src/index.ts`)
- Reviews & ratings → RabbitMQ events: publishes review.created
- RabbitMQ events → Product catalog: delivers review events
- RabbitMQ events → Typo-tolerant search: delivers stock events
- RabbitMQ events → Recommendations: delivers order events