# kinngh/shopify-node-express-mongodb-app architecture

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

- Interactive diagram: https://gitdiagram.com/kinngh/shopify-node-express-mongodb-app
- Repository: https://github.com/kinngh/shopify-node-express-mongodb-app

## Overview

This is an embedded Shopify app starter: a merchant uses its React admin UI, while Express authenticates app requests, manages Shopify sessions and API clients, and exposes proxy, checkout, GDPR, webhook, and event endpoints. MongoDB persists sessions and store status. A separate developer-tooling branch provides webhook, event, declarative-metafield, and TOML generation; the README also describes subscription-ready boilerplate. Some generator and event wiring is not shown in the excerpts, so those relationships are omitted rather than inferred.

Main entry points: [`server/index.js`](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/server/index.js) (Express server), [`server/webhooks/app_uninstalled.js`](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/server/webhooks/app_uninstalled.js) (Uninstall handler), [`utils/shopify.js`](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/utils/shopify.js) (Shopify configuration), [`_developer/declarativeWriter.js`](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/_developer/declarativeWriter.js) (Metafield generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Embedded admin UI"]
  node_app_ui["Admin interface<br/>[App.jsx]"]
  node_ui_routes["UI routes<br/>[Routes.jsx]"]
end

subgraph group_server["Request handling"]
  node_main_server["Express server<br/>[index.js]"]
  node_app_routes["App API routes<br/>[index.js]"]
  node_proxy_routes["App proxy routes<br/>[index.js]"]
  node_checkout_routes["Checkout routes<br/>[index.js]"]
  node_gdpr["GDPR handlers<br/>[gdpr.js]"]
  node_auth_middleware["Request verification<br/>[verifyRequest.js]"]
  node_webhook_dispatch["Webhook dispatch<br/>[_index.js]"]
  node_uninstall["Uninstall handler<br/>[app_uninstalled.js]"]
  node_event_dispatch["Event dispatch<br/>[_index.js]"]
end

subgraph group_shopify["Shopify integration"]
  node_shopify_config["Shopify configuration<br/>[shopify.js]"]
  node_api_clients["Shopify API clients<br/>[clientProvider.js]"]
end

subgraph group_state["Persistent state"]
  node_session_service["Session handling<br/>[sessionHandler.js]"]
  node_session_store[("Session records<br/>[SessionModel.js]")]
  node_store_records[("Store records<br/>[StoreModel.js]")]
end

subgraph group_tooling["App configuration tools"]
  node_webhook_writer["Webhook generator<br/>[webhookWriter.js]"]
  node_event_writer["Event generator<br/>[eventWriter.js]"]
  node_declarative_writer["Metafield generator"]
  node_toml_writer["TOML generator<br/>[tomlWriter.js]"]
  node_webhook_types["Webhook payload types<br/>[webhooks.js]"]
  node_webhook_topics["Webhook topic types<br/>[webhookTopics.js]"]
  node_event_topics["Event topic types<br/>[eventTopics.js]"]
  node_declarative_types["Metafield types<br/>[declarative.js]"]
  node_toml_types["TOML types<br/>[toml.js]"]
end

node_merchant(("Merchant"))
node_shopify_service["Shopify platform"]
node_mongodb[("MongoDB")]

node_merchant -->|"uses"| node_app_ui
node_app_ui -->|"routes through"| node_ui_routes
node_app_ui -.->|"calls API"| node_main_server
node_main_server -->|"mounts"| node_app_routes
node_main_server -->|"mounts"| node_proxy_routes
node_main_server -->|"mounts"| node_checkout_routes
node_main_server -->|"verifies requests"| node_auth_middleware
node_main_server -->|"dispatches GDPR"| node_gdpr
node_main_server -->|"routes webhooks"| node_webhook_dispatch
node_main_server -->|"routes events"| node_event_dispatch
node_webhook_dispatch -->|"dispatches handler"| node_uninstall
node_uninstall -->|"deletes sessions"| node_session_store
node_uninstall -->|"marks inactive"| node_store_records
node_app_routes -->|"creates clients"| node_api_clients
node_api_clients -->|"loads sessions"| node_session_service
node_session_service -->|"reads and writes"| node_session_store
node_main_server -->|"loads session"| node_session_service
node_shopify_config -->|"configures"| node_shopify_service
node_api_clients -->|"creates clients"| node_shopify_service
node_main_server -->|"connects"| node_mongodb
node_webhook_writer -->|"reads configuration"| node_shopify_config
node_declarative_writer -->|"reads configuration"| node_shopify_config
node_event_writer -->|"reads configuration"| node_shopify_config
node_declarative_writer -->|"uses types"| node_declarative_types
node_declarative_writer -->|"uses types"| node_toml_types
node_toml_writer -->|"uses types"| node_toml_types
node_uninstall -->|"types payload"| node_webhook_types

click node_app_ui "https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/client/App.jsx"
click node_ui_routes "https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/client/Routes.jsx"
click node_main_server "https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/server/index.js"
click node_app_routes "https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/server/routes/index.js"
click node_proxy_routes "https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/server/routes/app_proxy/index.js"
click node_checkout_routes "https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/server/routes/checkout/index.js"
click node_gdpr "https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/server/controllers/gdpr.js"
click node_auth_middleware "https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/server/middleware/verifyRequest.js"
click node_webhook_dispatch "https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/server/webhooks/_index.js"
click node_uninstall "https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/server/webhooks/app_uninstalled.js"
click node_event_dispatch "https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/server/events/_index.js"
click node_shopify_config "https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/utils/shopify.js"
click node_api_clients "https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/utils/clientProvider.js"
click node_session_service "https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/utils/sessionHandler.js"
click node_session_store "https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/utils/models/SessionModel.js"
click node_store_records "https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/utils/models/StoreModel.js"
click node_webhook_writer "https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/_developer/webhookWriter.js"
click node_event_writer "https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/_developer/eventWriter.js"
click node_declarative_writer "https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/_developer/declarativeWriter.js"
click node_toml_writer "https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/_developer/tomlWriter.js"
click node_webhook_types "https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/_developer/types/2026-07/webhooks.js"
click node_webhook_topics "https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/_developer/types/webhookTopics.js"
click node_event_topics "https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/_developer/types/eventTopics.js"
click node_declarative_types "https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/_developer/types/declarative.js"
click node_toml_types "https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/_developer/types/toml.js"

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_app_ui,node_ui_routes toneBlue
class node_main_server,node_app_routes,node_proxy_routes,node_checkout_routes,node_gdpr,node_auth_middleware,node_webhook_dispatch,node_uninstall,node_event_dispatch,node_mongodb toneAmber
class node_shopify_config,node_api_clients toneMint
class node_session_service,node_session_store,node_store_records toneRose
class node_webhook_writer,node_event_writer,node_declarative_writer,node_toml_writer,node_webhook_types,node_webhook_topics,node_event_topics,node_declarative_types,node_toml_types,node_merchant,node_shopify_service toneIndigo
```

## Components

### Embedded admin UI

- [Admin interface](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/client/App.jsx): `client/App.jsx`
- [UI routes](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/client/Routes.jsx): `client/Routes.jsx`

### Request handling

- [Express server](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/server/index.js): `server/index.js`
- [App API routes](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/server/routes/index.js): `server/routes/index.js`
- [App proxy routes](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/server/routes/app_proxy/index.js): `server/routes/app_proxy/index.js`
- [Checkout routes](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/server/routes/checkout/index.js): `server/routes/checkout/index.js`
- [GDPR handlers](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/server/controllers/gdpr.js): `server/controllers/gdpr.js`
- [Request verification](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/server/middleware/verifyRequest.js): `server/middleware/verifyRequest.js`
- [Webhook dispatch](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/server/webhooks/_index.js): `server/webhooks/_index.js`
- [Uninstall handler](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/server/webhooks/app_uninstalled.js): `server/webhooks/app_uninstalled.js`
- [Event dispatch](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/server/events/_index.js): `server/events/_index.js`

### Shopify integration

- [Shopify configuration](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/utils/shopify.js): `utils/shopify.js`
- [Shopify API clients](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/utils/clientProvider.js): `utils/clientProvider.js`

### Persistent state

- [Session handling](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/utils/sessionHandler.js): `utils/sessionHandler.js`
- [Session records](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/utils/models/SessionModel.js): `utils/models/SessionModel.js`
- [Store records](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/utils/models/StoreModel.js): `utils/models/StoreModel.js`

### App configuration tools

- [Webhook generator](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/_developer/webhookWriter.js): `_developer/webhookWriter.js`
- [Event generator](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/_developer/eventWriter.js): `_developer/eventWriter.js`
- [Metafield generator](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/_developer/declarativeWriter.js): `_developer/declarativeWriter.js`
- [TOML generator](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/_developer/tomlWriter.js): `_developer/tomlWriter.js`
- [Webhook payload types](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/_developer/types/2026-07/webhooks.js): `_developer/types/2026-07/webhooks.js`
- [Webhook topic types](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/_developer/types/webhookTopics.js): `_developer/types/webhookTopics.js`
- [Event topic types](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/_developer/types/eventTopics.js): `_developer/types/eventTopics.js`
- [Metafield types](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/_developer/types/declarative.js): `_developer/types/declarative.js`
- [TOML types](https://github.com/kinngh/shopify-node-express-mongodb-app/blob/main/_developer/types/toml.js): `_developer/types/toml.js`

### Other components

- **Merchant**
- **Shopify platform**
- **MongoDB**

## Connections

- Merchant → Admin interface: uses
- Admin interface → UI routes: routes through (evidence: `client/App.jsx`)
- Admin interface → Express server: calls API
- Express server → App API routes: mounts (evidence: `server/index.js`)
- Express server → App proxy routes: mounts (evidence: `server/index.js`)
- Express server → Checkout routes: mounts (evidence: `server/index.js`)
- Express server → Request verification: verifies requests (evidence: `server/index.js`)
- Express server → GDPR handlers: dispatches GDPR (evidence: `server/index.js`)
- Express server → Webhook dispatch: routes webhooks (evidence: `server/index.js`)
- Express server → Event dispatch: routes events (evidence: `server/index.js`)
- Webhook dispatch → Uninstall handler: dispatches handler (evidence: `server/webhooks/_index.js`)
- Uninstall handler → Session records: deletes sessions (evidence: `server/webhooks/app_uninstalled.js`)
- Uninstall handler → Store records: marks inactive (evidence: `server/webhooks/app_uninstalled.js`)
- App API routes → Shopify API clients: creates clients (evidence: `server/routes/index.js`)
- Shopify API clients → Session handling: loads sessions (evidence: `utils/clientProvider.js`)
- Session handling → Session records: reads and writes (evidence: `utils/sessionHandler.js`)
- Express server → Session handling: loads session (evidence: `server/index.js`)
- Shopify configuration → Shopify platform: configures (evidence: `utils/shopify.js`)
- Shopify API clients → Shopify platform: creates clients (evidence: `utils/clientProvider.js`)
- Express server → MongoDB: connects (evidence: `server/index.js`)
- Webhook generator → Shopify configuration: reads configuration (evidence: `_developer/webhookWriter.js`)
- Metafield generator → Shopify configuration: reads configuration (evidence: `_developer/declarativeWriter.js`)
- Event generator → Shopify configuration: reads configuration (evidence: `_developer/eventWriter.js`)
- Metafield generator → Metafield types: uses types (evidence: `_developer/declarativeWriter.js`)
- Metafield generator → TOML types: uses types (evidence: `_developer/declarativeWriter.js`)
- TOML generator → TOML types: uses types (evidence: `_developer/tomlWriter.js`)
- Uninstall handler → Webhook payload types: types payload (evidence: `server/webhooks/app_uninstalled.js`)
