How nandakishore-github/hurryuptimer-shopify works
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: index.js Server · timers.js Timers API · widget.js Widget API · analytics.js Analytics API
Components 24
Backend API
Node/Express app that owns auth, APIs, persistence, and Shopify integration.
- Server · App entrypoint that wires middleware, routes, static assets, and startup behavior.
web/index.js - Shopify app · Configures Shopify app credentials, OAuth flow, and session integration.
web/shopify.js - Timers API · Admin CRUD endpoints for creating, updating, listing, and deleting timers.
web/routes/timers.js - Analytics API · Endpoints for impression analytics writes and aggregated reads.
web/routes/analytics.js - Widget API · Public storefront endpoint that resolves the active timer for a shop and product.
web/routes/widget.js - HMAC guard · Verifies webhook authenticity and protects platform callbacks.
web/middleware/verifyHmac.js - Rate limiter · Throttles public and admin-mounted requests.
web/middleware/rateLimiter.js - Session shop · Resolves the merchant shop from the authenticated Shopify session.
web/helpers/sessionShop.js - Timer logic · 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 · Embedded admin application shell for Shopify Admin.
web/frontend/App.jsx - Dashboard · Lists timers and status for the merchant.
web/frontend/pages/Dashboard.jsx - Timer form · Create and edit flows for timer configuration.
web/frontend/pages/TimerForm.jsx - Use timers · Fetches timer data and manages UI state.
web/frontend/hooks/useTimers.js - API client · Frontend wrapper for backend requests.
web/frontend/services/client.js - Status badge · 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 · Theme app extension block that embeds the countdown timer.
extensions/countdown-timer/blocks/timer.liquid - Storefront JS · Fetches widget data and drives countdown behavior in the theme.
extensions/countdown-timer/assets/timer.js - Storefront styles · Styling for the storefront timer display.
extensions/countdown-timer/assets/timer.css - Locales · Localized storefront strings.
extensions/countdown-timer/locales/en.default.json
Persistence
Business data in MongoDB and Shopify session storage.
- Timer model · Timer configuration and ownership records.
web/models/Timer.js - Analytics model · Impression events and daily rollups.
web/models/Analytics.js - Store model · Store-level metadata and install-related state.
web/models/Store.js - MongoDB · Database connection used by the backend data models.
web/db.js
Shopify Platform
OAuth, Admin API, and webhook boundaries.
- Shopify · Identity, installation, Admin API, and webhook source.
Connections 33
- 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.