# tushank99/shopify-app architecture

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

- Interactive diagram: https://gitdiagram.com/tushank99/shopify-app
- Repository: https://github.com/tushank99/shopify-app

## Overview

This is an event-driven e-commerce storefront with personalized recommendations and an order ledger. Customers browse and authenticate in the React app, submit orders through the Node API, and receive asynchronously processed stock and recommendation work. Checkout also writes an outbox record atomically; a relay publishes it to Kafka for idempotent ledger ingestion and query. The README documents these service boundaries; several UI/API details and ML internals are represented at subsystem level because their implementation was not sampled.

Main entry points: [`backend/config/db.js`](https://github.com/tushank99/shopify-app/blob/main/backend/config/db.js) (MongoDB), [`backend/controllers/orderController.js`](https://github.com/tushank99/shopify-app/blob/main/backend/controllers/orderController.js) (Order checkout), [`backend/index.js`](https://github.com/tushank99/shopify-app/blob/main/backend/index.js) (Express API), [`backend/controllers/productController.js`](https://github.com/tushank99/shopify-app/blob/main/backend/controllers/productController.js) (Catalog and recs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_storefront["Storefront"]
  node_web["React storefront<br/>[main.jsx]"]
  node_webapi["API client"]
  node_orderui["Checkout UI"]
end

subgraph group_commerce["Commerce API"]
  node_api["Express API<br/>[index.js]"]
  node_users["User accounts<br/>[userController.js]"]
  node_products["Catalog and recs"]
  node_orders["Order checkout<br/>[orderController.js]"]
  node_mongo[("MongoDB<br/>[db.js]")]
end

subgraph group_async["Async Work"]
  node_redis[("Cache and queue<br/>[redis.js]")]
  node_stock["Stock worker"]
  node_recqueue["Recommendation queue"]
  node_mlqueue["ML queue"]
  node_outbox["Transactional outbox<br/>[orderOutbox.js]"]
  node_relay["Outbox relay<br/>[outboxRelay.js]"]
  node_kafka["Kafka"]
end

subgraph group_recommend["Recommendations"]
  node_mlapi["SVD inference<br/>[main.py]"]
end

subgraph group_ledger["Order Ledger"]
  node_listener["Order event consumer"]
  node_ingest["Ledger ingestion<br/>[LedgerService.java]"]
  node_ledgerdb[("PostgreSQL ledger")]
  node_query["Ledger queries"]
  node_ledgerapi["Ledger API"]
end

node_shopper(("Shopper"))

node_shopper -->|"browses and checks out"| node_web
node_web -->|"routes to"| node_orderui
node_web -.->|"uses API slices"| node_webapi
node_webapi -.->|"calls"| node_api
node_api -->|"routes requests"| node_users
node_api -->|"routes requests"| node_products
node_api -->|"routes requests"| node_orders
node_users -.->|"reads and writes"| node_mongo
node_products -->|"reads and writes"| node_mongo
node_orders -.->|"commits order"| node_mongo
node_orders -->|"writes atomically"| node_outbox
node_orders -->|"enqueues decrement"| node_stock
node_orders -->|"enqueues work"| node_mlqueue
node_stock -->|"updates stock"| node_mongo
node_stock -->|"uses connections"| node_redis
node_recqueue -->|"uses connections"| node_redis
node_mlqueue -->|"uses connections"| node_redis
node_products -->|"reads recommendation cache"| node_redis
node_products -->|"requests inference"| node_mlapi
node_outbox -->|"stores with order"| node_mongo
node_relay -->|"claims outbox rows"| node_mongo
node_relay -->|"publishes events"| node_kafka
node_kafka -->|"delivers events"| node_listener
node_listener -.->|"dispatches ingestion"| node_ingest
node_ingest -->|"inserts idempotently"| node_ledgerdb
node_ledgerapi -->|"delegates queries"| node_query
node_query -->|"reads entries and items"| node_ledgerdb

click node_web "https://github.com/tushank99/shopify-app/blob/main/frontend/src/main.jsx"
click node_webapi "https://github.com/tushank99/shopify-app/tree/main/frontend/src/redux/api"
click node_orderui "https://github.com/tushank99/shopify-app/tree/main/frontend/src/pages/Orders"
click node_api "https://github.com/tushank99/shopify-app/blob/main/backend/index.js"
click node_users "https://github.com/tushank99/shopify-app/blob/main/backend/controllers/userController.js"
click node_products "https://github.com/tushank99/shopify-app/blob/main/backend/controllers/productController.js"
click node_orders "https://github.com/tushank99/shopify-app/blob/main/backend/controllers/orderController.js"
click node_mongo "https://github.com/tushank99/shopify-app/blob/main/backend/config/db.js"
click node_redis "https://github.com/tushank99/shopify-app/blob/main/backend/config/redis.js"
click node_stock "https://github.com/tushank99/shopify-app/blob/main/backend/queues/stockDecrementQueue.js"
click node_recqueue "https://github.com/tushank99/shopify-app/blob/main/backend/queues/recommendationQueue.js"
click node_mlqueue "https://github.com/tushank99/shopify-app/blob/main/backend/queues/mlRecommendationQueue.js"
click node_mlapi "https://github.com/tushank99/shopify-app/blob/main/ml-backend/main.py"
click node_outbox "https://github.com/tushank99/shopify-app/blob/main/backend/outbox/orderOutbox.js"
click node_relay "https://github.com/tushank99/shopify-app/blob/main/backend/workers/outboxRelay.js"
click node_listener "https://github.com/tushank99/shopify-app/blob/main/ledger-service/src/main/java/com/shopify/ledger/kafka/OrderPlacedListener.java"
click node_ingest "https://github.com/tushank99/shopify-app/blob/main/ledger-service/src/main/java/com/shopify/ledger/service/LedgerService.java"
click node_ledgerdb "https://github.com/tushank99/shopify-app/blob/main/ledger-service/src/main/java/com/shopify/ledger/repository/LedgerEntryRepository.java"
click node_query "https://github.com/tushank99/shopify-app/blob/main/ledger-service/src/main/java/com/shopify/ledger/service/LedgerQueryService.java"
click node_ledgerapi "https://github.com/tushank99/shopify-app/blob/main/ledger-service/src/main/java/com/shopify/ledger/api/LedgerController.java"

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_webapi,node_orderui toneBlue
class node_api,node_users,node_products,node_orders,node_mongo toneAmber
class node_redis,node_stock,node_recqueue,node_mlqueue,node_outbox,node_relay,node_kafka toneMint
class node_mlapi toneRose
class node_listener,node_ingest,node_ledgerdb,node_query,node_ledgerapi,node_shopper toneIndigo
```

## Components

### Storefront

- [React storefront](https://github.com/tushank99/shopify-app/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`
- [API client](https://github.com/tushank99/shopify-app/tree/main/frontend/src/redux/api): `frontend/src/redux/api`
- [Checkout UI](https://github.com/tushank99/shopify-app/tree/main/frontend/src/pages/Orders): `frontend/src/pages/Orders`

### Commerce API

- [Express API](https://github.com/tushank99/shopify-app/blob/main/backend/index.js): `backend/index.js`
- [User accounts](https://github.com/tushank99/shopify-app/blob/main/backend/controllers/userController.js): `backend/controllers/userController.js`
- [Catalog and recs](https://github.com/tushank99/shopify-app/blob/main/backend/controllers/productController.js): `backend/controllers/productController.js`
- [Order checkout](https://github.com/tushank99/shopify-app/blob/main/backend/controllers/orderController.js): `backend/controllers/orderController.js`
- [MongoDB](https://github.com/tushank99/shopify-app/blob/main/backend/config/db.js): `backend/config/db.js`

### Async Work

- [Cache and queue](https://github.com/tushank99/shopify-app/blob/main/backend/config/redis.js): `backend/config/redis.js`
- [Stock worker](https://github.com/tushank99/shopify-app/blob/main/backend/queues/stockDecrementQueue.js): `backend/queues/stockDecrementQueue.js`
- [Recommendation queue](https://github.com/tushank99/shopify-app/blob/main/backend/queues/recommendationQueue.js): `backend/queues/recommendationQueue.js`
- [ML queue](https://github.com/tushank99/shopify-app/blob/main/backend/queues/mlRecommendationQueue.js): `backend/queues/mlRecommendationQueue.js`
- [Transactional outbox](https://github.com/tushank99/shopify-app/blob/main/backend/outbox/orderOutbox.js): `backend/outbox/orderOutbox.js`
- [Outbox relay](https://github.com/tushank99/shopify-app/blob/main/backend/workers/outboxRelay.js): `backend/workers/outboxRelay.js`
- **Kafka**

### Recommendations

- [SVD inference](https://github.com/tushank99/shopify-app/blob/main/ml-backend/main.py): `ml-backend/main.py`

### Order Ledger

- [Order event consumer](https://github.com/tushank99/shopify-app/blob/main/ledger-service/src/main/java/com/shopify/ledger/kafka/OrderPlacedListener.java): `ledger-service/src/main/java/com/shopify/ledger/kafka/OrderPlacedListener.java`
- [Ledger ingestion](https://github.com/tushank99/shopify-app/blob/main/ledger-service/src/main/java/com/shopify/ledger/service/LedgerService.java): `ledger-service/src/main/java/com/shopify/ledger/service/LedgerService.java`
- [PostgreSQL ledger](https://github.com/tushank99/shopify-app/blob/main/ledger-service/src/main/java/com/shopify/ledger/repository/LedgerEntryRepository.java): `ledger-service/src/main/java/com/shopify/ledger/repository/LedgerEntryRepository.java`
- [Ledger queries](https://github.com/tushank99/shopify-app/blob/main/ledger-service/src/main/java/com/shopify/ledger/service/LedgerQueryService.java): `ledger-service/src/main/java/com/shopify/ledger/service/LedgerQueryService.java`
- [Ledger API](https://github.com/tushank99/shopify-app/blob/main/ledger-service/src/main/java/com/shopify/ledger/api/LedgerController.java): `ledger-service/src/main/java/com/shopify/ledger/api/LedgerController.java`

### Other components

- **Shopper**

## Connections

- Shopper → React storefront: browses and checks out (evidence: `frontend/src/main.jsx`)
- React storefront → Checkout UI: routes to (evidence: `frontend/src/main.jsx`)
- React storefront → API client: uses API slices
- API client → Express API: calls
- Express API → User accounts: routes requests (evidence: `backend/index.js`)
- Express API → Catalog and recs: routes requests (evidence: `backend/index.js`)
- Express API → Order checkout: routes requests (evidence: `backend/index.js`)
- User accounts → MongoDB: reads and writes
- Catalog and recs → MongoDB: reads and writes (evidence: `backend/controllers/productController.js`)
- Order checkout → MongoDB: commits order
- Order checkout → Transactional outbox: writes atomically (evidence: `backend/controllers/orderController.js`)
- Order checkout → Stock worker: enqueues decrement (evidence: `backend/controllers/orderController.js`)
- Order checkout → ML queue: enqueues work (evidence: `backend/controllers/orderController.js`)
- Stock worker → MongoDB: updates stock (evidence: `backend/queues/stockDecrementQueue.js`)
- Stock worker → Cache and queue: uses connections (evidence: `backend/queues/stockDecrementQueue.js`)
- Recommendation queue → Cache and queue: uses connections (evidence: `backend/queues/recommendationQueue.js`)
- ML queue → Cache and queue: uses connections (evidence: `backend/queues/mlRecommendationQueue.js`)
- Catalog and recs → Cache and queue: reads recommendation cache (evidence: `backend/controllers/productController.js`)
- Catalog and recs → SVD inference: requests inference (evidence: `backend/controllers/productController.js`)
- Transactional outbox → MongoDB: stores with order
- Outbox relay → MongoDB: claims outbox rows
- Outbox relay → Kafka: publishes events
- Kafka → Order event consumer: delivers events
- Order event consumer → Ledger ingestion: dispatches ingestion
- Ledger ingestion → PostgreSQL ledger: inserts idempotently (evidence: `ledger-service/src/main/java/com/shopify/ledger/service/LedgerService.java`)
- Ledger API → Ledger queries: delegates queries (evidence: `ledger-service/src/main/java/com/shopify/ledger/api/LedgerController.java`)
- Ledger queries → PostgreSQL ledger: reads entries and items (evidence: `ledger-service/src/main/java/com/shopify/ledger/service/LedgerQueryService.java`)
