# nandakishore-github/hurryuptimer-shopify architecture

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

- Interactive diagram: https://gitdiagram.com/nandakishore-github/hurryuptimer-shopify
- Repository: https://github.com/nandakishore-github/hurryuptimer-shopify

## Overview

This repository is a Shopify countdown-timer app with three main runtime surfaces:

1. A backend API in Node/Express.
2. An embedded admin UI built with React.
3. A storefront theme app extension that renders the timer inside the merchant’s theme.

The core architectural split is between:
- the merchant/admin side, which is authenticated through Shopify sessions, and
- the storefront/public side, which must be fast, cacheable, and protected by rate limits plus ownership checks.

#### High-level system shape

The backend is the hub of the system. It:
- handles Shopify OAuth and webhook processing,
- exposes REST endpoints for admin CRUD and analytics,
- serves the admin frontend bundle,
- queries and writes MongoDB documents for timers, stores, and analytics,
- and calls the Shopify Admin API when needed.

The storefront extension does not talk directly to MongoDB or Shopify Admin APIs. Instead, it calls the backend for timer data and sends impression events back to the backend.

#### Main subsystems

##### 1) Express backend (`web/`)
This is the server-side application entry point and API layer.

Key pieces:
- `web/index.js`: server bootstrap and route wiring.
- `web/shopify.js`: Shopify app setup, auth/session integration, and API credentials.
- `web/routes/`: REST endpoints split by domain:
  - `timers.js` for timer CRUD,
  - `analytics.js` for impression/analytics reads,
  - `widget.js` for storefront widget data.
- `web/middleware/`:
  - `verifyHmac.js` for Shopify webhook signature verification,
  - `rateLimiter.js` for throttling public and admin-mounted routes.
- `web/helpers/`:
  - `sessionShop.js` resolves the shop from the authenticated Shopify session,
  - `timerHelper.js` contains the timer business logic, including active-state and evergreen/fixed resolution.
- `web/models/`:
  - `Timer.js`
  - `Analytics.js`
  - `Store.js`

This backend is the main trust boundary. Admin routes do not trust a client-supplied shop domain; they derive ownership from the authenticated Shopify session. That matters because it prevents one merchant from querying or editing another merchant’s timers.

##### 2) Embedded admin frontend (`web/frontend/`)
This is the merchant-facing app embedded inside Shopify Admin.

It is a React/Vite application with:
- `App.jsx` as the shell,
- `pages/Dashboard.jsx` for listing timers and status,
- `pages/TimerForm.jsx` for create/edit flows,
- `components/StatusBadge.jsx` for visual state,
- `hooks/useTimers.js` for data fetching and state management,
- `services/client.js` for API calls.

The admin UI is built separately and shipped as static assets under `web/public/`, which the Express app serves. The UI appears to be designed around Shopify Admin conventions, using App Bridge/Polaris as described in the README.

##### 3) Storefront theme extension (`extensions/countdown-timer/`)
This is the shopper-facing piece installed into the merchant’s theme.

It includes:
- `blocks/timer.liquid`: the block that embeds the timer in the theme,
- `assets/timer.js` and `timer.css`: storefront behavior and styling,
- `locales/en.default.json`: localized strings,
- `shopify.extension.toml`: extension metadata.

This extension is responsible for rendering the countdown on the storefront and interacting with the public widget API. It is intentionally separate from the admin app so the storefront can stay lightweight and independently deployed as a Shopify theme extension.

#### Data layer and persistence

MongoDB stores the app’s business data. The models indicate three document types:
- `Timer`: timer configuration and ownership,
- `Analytics`: impression counts and daily rollups,
- `Store`: store-level metadata or install-related state.

The README states that timer and analytics documents are keyed by `shopDomain` derived from the OAuth session. That means tenant separation is enforced at the data model layer, not by client input.

Shopify sessions are stored separately from MongoDB, using the Shopify app session storage configured in `web/shopify.js` and described as SQLite-backed in the README. So there are two persistence concerns:
- Shopify auth/session state in SQLite,
- app business data in MongoDB.

#### Important request/data flows

##### A) Merchant install and authentication
1. Merchant installs the app in Shopify.
2. Shopify OAuth completes through `/api/auth` and `/api/auth/callback`.
3. The app stores the Shopify session.
4. The backend can now identify the merchant’s shop and act on its behalf, including Shopify Admin API calls.

This is the trust anchor for all admin operations.

##### B) Admin timer management
1. The embedded React app loads inside Shopify Admin.
2. It calls backend timer endpoints through `services/client.js`.
3. The backend resolves the shop from the authenticated session via `sessionShop.js`.
4. The backend reads/writes `Timer` documents in MongoDB.
5. The dashboard shows timer status, and the form supports timer create/update/delete.

The key boundary here is that the admin UI does not own data access directly; it is just a client for the API.

##### C) Storefront timer rendering
1. The theme extension renders the liquid block on a product page.
2. The widget requests timer JSON from `GET /api/widget/:shopDomain/:productId`.
3. The backend selects the applicable active timer for that shop/product combination.
4. The widget renders the countdown locally, using the fetched configuration.
5. For evergreen timers, the client-side logic uses browser storage so the countdown can be per-visitor/session rather than shared globally.

This is a hybrid model:
- the server determines which timer applies,
- the browser performs the actual countdown display and evergreen behavior.

##### D) Impression analytics
1. The storefront widget posts an impression event to `POST /api/analytics/impression`.
2. The backend rate-limits the request.
3. It verifies that the timer ID matches the shop on the timer record before counting the impression.
4. Analytics are written to MongoDB and later aggregated for the admin dashboard.

This prevents a client from spoofing impressions for another store.

##### E) Analytics viewing
1. The admin dashboard requests analytics for a timer through `/api/analytics/:timerId`.
2. The backend again uses the authenticated session shop to scope access.
3. The response includes daily rows and a total, which the UI uses in the analytics modal.

#### Security and boundary controls

Several architectural safeguards are explicit in the repo:

- **Shop ownership is derived from Shopify session**, not from a query parameter or client-submitted `shopDomain`.
- **Webhook authenticity is enforced with HMAC verification** in middleware.
- **Public endpoints are rate-limited** to protect the widget and impression endpoints.
- **Impression writes validate timer ownership** before incrementing counts.
- **Server-side sanitization** is noted in the README for user-entered text fields.

These controls are important diagrammatically because they mark where the app trusts Shopify versus where it trusts its own database.

#### Build and deployment topology

The project includes:
- a root `Dockerfile`,
- GitHub Actions workflows for CI and dependency automation,
- Shopify CLI configuration files at the root and under `web/` and `extensions/`.

The frontend is built separately by Vite and served as static assets by the backend. The storefront extension is packaged through Shopify’s extension pipeline, not bundled into the admin SPA.

#### What to emphasize in an architecture diagram

If you’re drawing this system, the most important boxes and arrows are:

- Shopify Storefront → theme extension → backend widget API
- Theme extension → backend impression endpoint
- Embedded Shopify Admin app → backend admin APIs
- Backend → MongoDB
- Backend → Shopify Admin API / OAuth / webhooks
- Backend → session store for Shopify auth
- Middleware boundary around HMAC, rate limiting, and session-based shop resolution

The clean separation is:
- **admin app for configuration and reporting**,
- **backend for auth, validation, and persistence**,
- **storefront extension for display**,
- **MongoDB for app state**,
- **Shopify for identity, installation, and platform integration**.

Main entry points: [`web/index.js`](https://github.com/nandakishore-github/hurryuptimer-shopify/blob/HEAD/web/index.js) (Server), [`web/routes/timers.js`](https://github.com/nandakishore-github/hurryuptimer-shopify/blob/HEAD/web/routes/timers.js) (Timers API), [`web/routes/widget.js`](https://github.com/nandakishore-github/hurryuptimer-shopify/blob/HEAD/web/routes/widget.js) (Widget API), [`web/routes/analytics.js`](https://github.com/nandakishore-github/hurryuptimer-shopify/blob/HEAD/web/routes/analytics.js) (Analytics API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Backend API"
  web_index["Server<br/>Express bootstrap<br/>[index.js]"]
  web_shopify["Shopify app<br/>Auth/session setup<br/>[shopify.js]"]
  web_routes_timers["Timers API<br/>REST routes<br/>[timers.js]"]
  web_routes_analytics["Analytics API<br/>REST routes<br/>[analytics.js]"]
  web_routes_widget["Widget API<br/>REST routes<br/>[widget.js]"]
  web_mw_hmac["HMAC guard<br/>Middleware<br/>[verifyHmac.js]"]
  web_mw_rate["Rate limiter<br/>Middleware<br/>[rateLimiter.js]"]
  web_helper_session["Session shop<br/>Session helper<br/>[sessionShop.js]"]
  web_helper_timer["Timer logic<br/>Business helper<br/>[timerHelper.js]"]
end

subgraph "Admin UI"
  web_frontend_app["App shell<br/>React shell<br/>[App.jsx]"]
  web_frontend_dashboard["Dashboard<br/>Admin page<br/>[Dashboard.jsx]"]
  web_frontend_form["Timer form<br/>Admin page<br/>[TimerForm.jsx]"]
  web_frontend_hook["Use timers<br/>Data hook<br/>[useTimers.js]"]
  web_frontend_client["API client<br/>Service client<br/>[client.js]"]
  web_frontend_badge(("Status badge<br/>UI component<br/>[StatusBadge.jsx]"))
end

subgraph "Storefront Extension"
  ext_block["Timer block<br/>Liquid block<br/>[timer.liquid]"]
  ext_js["Storefront JS<br/>Browser script<br/>[timer.js]"]
  ext_css["Storefront styles<br/>Theme CSS<br/>[timer.css]"]
  ext_locale["Locales<br/>Translation file<br/>[en.default.json]"]
end

subgraph "Persistence"
  web_model_timer[("Timer model<br/>Mongo document<br/>[Timer.js]")]
  web_model_analytics[("Analytics model<br/>Mongo document<br/>[Analytics.js]")]
  web_model_store[("Store model<br/>Mongo document<br/>[Store.js]")]
  web_db[("MongoDB<br/>Database connector<br/>[db.js]")]
end

subgraph "Shopify Platform"
  shopify_platform{{"Shopify<br/>Platform"}}
end

web_index -->|"configures"| web_shopify
web_index -->|"mounts"| web_routes_timers
web_index -->|"mounts"| web_routes_analytics
web_index -->|"mounts"| web_routes_widget
web_index -->|"uses"| web_mw_hmac
web_index -->|"uses"| web_mw_rate
web_index -->|"connects"| web_db
web_shopify -->|"oauth/admin api"| shopify_platform
web_routes_timers -->|"scopes by shop"| web_helper_session
web_routes_timers -->|"applies rules"| web_helper_timer
web_routes_timers -->|"reads/writes"| web_model_timer
web_routes_analytics -->|"scopes by shop"| web_helper_session
web_routes_analytics -->|"reads/writes"| web_model_analytics
web_routes_widget -->|"selects timer"| web_helper_timer
web_routes_widget -->|"reads"| web_model_timer
web_routes_widget -->|"protected by"| web_mw_rate
web_mw_hmac -->|"verifies webhooks"| shopify_platform
web_model_timer -->|"stored in"| web_db
web_model_analytics -->|"stored in"| web_db
web_model_store -->|"stored in"| web_db
web_frontend_app -->|"navigates"| web_frontend_dashboard
web_frontend_app -->|"navigates"| web_frontend_form
web_frontend_dashboard -->|"fetches"| web_frontend_hook
web_frontend_form -->|"calls"| web_frontend_client
web_frontend_hook -->|"calls"| web_frontend_client
web_frontend_dashboard -->|"renders"| web_frontend_badge
web_frontend_client -->|"admin api"| web_routes_timers
web_frontend_client -->|"admin api"| web_routes_analytics
ext_block -->|"loads"| ext_js
ext_block -->|"styles"| ext_css
ext_js -->|"fetches"| web_routes_widget
ext_js -->|"posts impressions"| web_routes_analytics
ext_js -->|"uses"| ext_locale

click web_index "https://github.com/nandakishore-github/hurryuptimer-shopify/blob/main/web/index.js"
click web_shopify "https://github.com/nandakishore-github/hurryuptimer-shopify/blob/main/web/shopify.js"
click web_routes_timers "https://github.com/nandakishore-github/hurryuptimer-shopify/blob/main/web/routes/timers.js"
click web_routes_analytics "https://github.com/nandakishore-github/hurryuptimer-shopify/blob/main/web/routes/analytics.js"
click web_routes_widget "https://github.com/nandakishore-github/hurryuptimer-shopify/blob/main/web/routes/widget.js"
click web_mw_hmac "https://github.com/nandakishore-github/hurryuptimer-shopify/blob/main/web/middleware/verifyHmac.js"
click web_mw_rate "https://github.com/nandakishore-github/hurryuptimer-shopify/blob/main/web/middleware/rateLimiter.js"
click web_helper_session "https://github.com/nandakishore-github/hurryuptimer-shopify/blob/main/web/helpers/sessionShop.js"
click web_helper_timer "https://github.com/nandakishore-github/hurryuptimer-shopify/blob/main/web/helpers/timerHelper.js"
click web_model_timer "https://github.com/nandakishore-github/hurryuptimer-shopify/blob/main/web/models/Timer.js"
click web_model_analytics "https://github.com/nandakishore-github/hurryuptimer-shopify/blob/main/web/models/Analytics.js"
click web_model_store "https://github.com/nandakishore-github/hurryuptimer-shopify/blob/main/web/models/Store.js"
click web_db "https://github.com/nandakishore-github/hurryuptimer-shopify/blob/main/web/db.js"
click web_frontend_app "https://github.com/nandakishore-github/hurryuptimer-shopify/blob/main/web/frontend/App.jsx"
click web_frontend_dashboard "https://github.com/nandakishore-github/hurryuptimer-shopify/blob/main/web/frontend/pages/Dashboard.jsx"
click web_frontend_form "https://github.com/nandakishore-github/hurryuptimer-shopify/blob/main/web/frontend/pages/TimerForm.jsx"
click web_frontend_hook "https://github.com/nandakishore-github/hurryuptimer-shopify/blob/main/web/frontend/hooks/useTimers.js"
click web_frontend_client "https://github.com/nandakishore-github/hurryuptimer-shopify/blob/main/web/frontend/services/client.js"
click web_frontend_badge "https://github.com/nandakishore-github/hurryuptimer-shopify/blob/main/web/frontend/components/StatusBadge.jsx"
click ext_block "https://github.com/nandakishore-github/hurryuptimer-shopify/blob/main/extensions/countdown-timer/blocks/timer.liquid"
click ext_js "https://github.com/nandakishore-github/hurryuptimer-shopify/blob/main/extensions/countdown-timer/assets/timer.js"
click ext_css "https://github.com/nandakishore-github/hurryuptimer-shopify/blob/main/extensions/countdown-timer/assets/timer.css"
click ext_locale "https://github.com/nandakishore-github/hurryuptimer-shopify/blob/main/extensions/countdown-timer/locales/en.default.json"

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 web_index,web_shopify,web_routes_timers,web_routes_analytics,web_routes_widget,web_mw_hmac,web_mw_rate,web_helper_session,web_helper_timer toneBlue
class web_frontend_app,web_frontend_dashboard,web_frontend_form,web_frontend_hook,web_frontend_client,web_frontend_badge toneAmber
class ext_block,ext_js,ext_css,ext_locale toneMint
class web_model_timer,web_model_analytics,web_model_store,web_db toneRose
class shopify_platform toneIndigo
```

## Components

### Backend API

Node/Express app that owns auth, APIs, persistence, and Shopify integration.

- [Server](https://github.com/nandakishore-github/hurryuptimer-shopify/blob/HEAD/web/index.js): Express bootstrap · App entrypoint that wires middleware, routes, static assets, and startup behavior. · `web/index.js`
- [Shopify app](https://github.com/nandakishore-github/hurryuptimer-shopify/blob/HEAD/web/shopify.js): Auth/session setup · Configures Shopify app credentials, OAuth flow, and session integration. · `web/shopify.js`
- [Timers API](https://github.com/nandakishore-github/hurryuptimer-shopify/blob/HEAD/web/routes/timers.js): REST routes · Admin CRUD endpoints for creating, updating, listing, and deleting timers. · `web/routes/timers.js`
- [Analytics API](https://github.com/nandakishore-github/hurryuptimer-shopify/blob/HEAD/web/routes/analytics.js): REST routes · Endpoints for impression analytics writes and aggregated reads. · `web/routes/analytics.js`
- [Widget API](https://github.com/nandakishore-github/hurryuptimer-shopify/blob/HEAD/web/routes/widget.js): REST routes · Public storefront endpoint that resolves the active timer for a shop and product. · `web/routes/widget.js`
- [HMAC guard](https://github.com/nandakishore-github/hurryuptimer-shopify/blob/HEAD/web/middleware/verifyHmac.js): Middleware · Verifies webhook authenticity and protects platform callbacks. · `web/middleware/verifyHmac.js`
- [Rate limiter](https://github.com/nandakishore-github/hurryuptimer-shopify/blob/HEAD/web/middleware/rateLimiter.js): Middleware · Throttles public and admin-mounted requests. · `web/middleware/rateLimiter.js`
- [Session shop](https://github.com/nandakishore-github/hurryuptimer-shopify/blob/HEAD/web/helpers/sessionShop.js): Session helper · Resolves the merchant shop from the authenticated Shopify session. · `web/helpers/sessionShop.js`
- [Timer logic](https://github.com/nandakishore-github/hurryuptimer-shopify/blob/HEAD/web/helpers/timerHelper.js): Business helper · Determines active timers and evergreen versus fixed behavior. · `web/helpers/timerHelper.js`

### Admin UI

Embedded merchant-facing React app served by the backend.

- [App shell](https://github.com/nandakishore-github/hurryuptimer-shopify/blob/HEAD/web/frontend/App.jsx): React shell · Embedded admin application shell for Shopify Admin. · `web/frontend/App.jsx`
- [Dashboard](https://github.com/nandakishore-github/hurryuptimer-shopify/blob/HEAD/web/frontend/pages/Dashboard.jsx): Admin page · Lists timers and status for the merchant. · `web/frontend/pages/Dashboard.jsx`
- [Timer form](https://github.com/nandakishore-github/hurryuptimer-shopify/blob/HEAD/web/frontend/pages/TimerForm.jsx): Admin page · Create and edit flows for timer configuration. · `web/frontend/pages/TimerForm.jsx`
- [Use timers](https://github.com/nandakishore-github/hurryuptimer-shopify/blob/HEAD/web/frontend/hooks/useTimers.js): Data hook · Fetches timer data and manages UI state. · `web/frontend/hooks/useTimers.js`
- [API client](https://github.com/nandakishore-github/hurryuptimer-shopify/blob/HEAD/web/frontend/services/client.js): Service client · Frontend wrapper for backend requests. · `web/frontend/services/client.js`
- [Status badge](https://github.com/nandakishore-github/hurryuptimer-shopify/blob/HEAD/web/frontend/components/StatusBadge.jsx): UI component · Displays timer state in the admin UI. · `web/frontend/components/StatusBadge.jsx`

### Storefront Extension

Theme extension that renders the timer in the merchant storefront.

- [Timer block](https://github.com/nandakishore-github/hurryuptimer-shopify/blob/HEAD/extensions/countdown-timer/blocks/timer.liquid): Liquid block · Theme app extension block that embeds the countdown timer. · `extensions/countdown-timer/blocks/timer.liquid`
- [Storefront JS](https://github.com/nandakishore-github/hurryuptimer-shopify/blob/HEAD/extensions/countdown-timer/assets/timer.js): Browser script · Fetches widget data and drives countdown behavior in the theme. · `extensions/countdown-timer/assets/timer.js`
- [Storefront styles](https://github.com/nandakishore-github/hurryuptimer-shopify/blob/HEAD/extensions/countdown-timer/assets/timer.css): Theme CSS · Styling for the storefront timer display. · `extensions/countdown-timer/assets/timer.css`
- [Locales](https://github.com/nandakishore-github/hurryuptimer-shopify/blob/HEAD/extensions/countdown-timer/locales/en.default.json): Translation file · Localized storefront strings. · `extensions/countdown-timer/locales/en.default.json`

### Persistence

Business data in MongoDB and Shopify session storage.

- [Timer model](https://github.com/nandakishore-github/hurryuptimer-shopify/blob/HEAD/web/models/Timer.js): Mongo document · Timer configuration and ownership records. · `web/models/Timer.js`
- [Analytics model](https://github.com/nandakishore-github/hurryuptimer-shopify/blob/HEAD/web/models/Analytics.js): Mongo document · Impression events and daily rollups. · `web/models/Analytics.js`
- [Store model](https://github.com/nandakishore-github/hurryuptimer-shopify/blob/HEAD/web/models/Store.js): Mongo document · Store-level metadata and install-related state. · `web/models/Store.js`
- [MongoDB](https://github.com/nandakishore-github/hurryuptimer-shopify/blob/HEAD/web/db.js): Database connector · Database connection used by the backend data models. · `web/db.js`

### Shopify Platform

OAuth, Admin API, and webhook boundaries.

- **Shopify**: Platform · Identity, installation, Admin API, and webhook source.

## Connections

- Server → Shopify app: configures · Bootstraps the app with Shopify auth/session integration.
- Server → Timers API: mounts · Serves timer CRUD endpoints.
- Server → Analytics API: mounts · Serves analytics endpoints.
- Server → Widget API: mounts · Serves storefront widget endpoints.
- Server → HMAC guard: uses · Applies webhook authenticity protection.
- Server → Rate limiter: uses · Applies request throttling on public and admin routes.
- Server → MongoDB: connects · Initializes database access.
- Shopify app → Shopify: oauth/admin api · Integrates OAuth and Admin API access with Shopify.
- Timers API → Session shop: scopes by shop · Resolves merchant ownership from the authenticated session.
- Timers API → Timer logic: applies rules · Uses timer resolution and active-state logic.
- Timers API → Timer model: reads/writes · Persists timer records in MongoDB.
- Analytics API → Session shop: scopes by shop · Limits analytics access to the authenticated merchant.
- Analytics API → Analytics model: reads/writes · Stores impressions and rollups.
- Widget API → Timer logic: selects timer · Determines the active timer for a shop/product pair.
- Widget API → Timer model: reads · Looks up timer configuration.
- Widget API → Rate limiter: protected by · Public widget requests are rate-limited.
- HMAC guard → Shopify: verifies webhooks · Checks Shopify webhook signatures.
- Timer model → MongoDB: stored in · Timer documents live in MongoDB.
- Analytics model → MongoDB: stored in · Analytics documents live in MongoDB.
- Store model → MongoDB: stored in · Store records live in MongoDB.
- App shell → Dashboard: navigates · Hosts the timer list view.
- App shell → Timer form: navigates · Hosts create/edit flows.
- Dashboard → Use timers: fetches · Uses shared timer data/state.
- Timer form → API client: calls · Submits timer mutations to the backend.
- Use timers → API client: calls · Fetches timer data from backend APIs.
- Dashboard → Status badge: renders · Displays timer status indicators.
- API client → Timers API: admin api · Admin UI consumes timer endpoints.
- API client → Analytics API: admin api · Admin UI consumes analytics endpoints.
- Timer block → Storefront JS: loads · Block mounts the storefront behavior script.
- Timer block → Storefront styles: styles · Block uses storefront styling.
- Storefront JS → Widget API: fetches · Retrieves timer configuration for display.
- Storefront JS → Analytics API: posts impressions · Sends impression events back to the backend.
- Storefront JS → Locales: uses · Loads localized text.
