Verified end-to-end against the running production app (inventory-reload.fusenv.com)
by installing on a fresh dev store (discreload-demo.myshopify.com).
| Check | Result |
|---|---|
| Fresh install on a dev store (managed install, no OAuth screen) | ✅ app opens embedded in Shopify admin |
| Admin API call with expiring offline token | ✅ 200 (previously 403 on non-expiring token) |
| Embedded surface loads products via session token | ✅ 18 products listed, no cookies/localStorage auth |
| Billing gate — unsubscribed shop | ✅ shows "Choose your plan" |
| Plan approval (Shopify App Pricing, test charge) | ✅ approves and returns to app |
| Billing gate — after subscribing | ✅ app opens (cache no longer serves stale "none") |
| Privacy policy URL | ✅ https://inventory-reload.fusenv.com/privacy → 200 |
| Webhook endpoint with invalid HMAC | ✅ 401 |
Shopify AI self-review (/shopify-app-store-review) |
✅ no failing requirements |
| Shopify embedded app checks (App Bridge + session tokens) | ✅ passed |
| App Store submission | ✅ Submitted — awaiting reviewer |
Released app version: discreload-6. See docs/app-store/submission-guide.md
for the full submission state.
A complete CQRS + Event Sourcing system for managing disc golf inventory on Shopify. Built with Next.js, TypeScript, SQLite, and follows the Adam Dymitruk / Martin Dilger event sourcing approach.
The product detail screen after both background jobs have run: the disc has been centered on the light blue canvas by the image processing job, and its color has been estimated from the original photo and matched to an available Shopify color. Once a weight is entered, the variant can be created.
Screenshot taken against a throwaway database with sample data.
- NextJS Web Application - User interface and API endpoints
- Background Processor - Async jobs for color estimation and Shopify integration
- SQLite Databases - Event store per user + system database
- Event-sourced architecture with full event replay
- JWT-based authentication for users
- API key authentication for background processor
- Automatic color estimation from photos
- Unique variant generation with weight tracking
- Retry logic for failed Shopify operations (up to 5 attempts)
A merchant installs from the Shopify App Store; there is no OAuth redirect and no shop-domain prompt. The embedded page loads App Bridge, gets a session token, and exchanges it for an expiring offline token. The tenant is the shop, so a reinstall reattaches to existing data.
sequenceDiagram
participant M as Merchant
participant Admin as Shopify admin (iframe)
participant AB as App Bridge
participant App as Next.js app
participant S as Shopify OAuth
M->>Admin: Install / open DiscReload
Admin->>App: load /embedded (iframe)
App->>AB: app-bridge.js (first script)
AB-->>App: window.shopify.idToken()
App->>App: POST /api/auth/shopify/token-exchange (Bearer session token)
App->>S: token exchange (expiring: 1)
S-->>App: access_token (1h) + refresh_token (90d)
App->>S: GraphQL locations query
S-->>App: stocking location
App->>App: provisionShopConnection (tenant = shop)
App-->>Admin: dashboard renders
The Admin API rejects non-expiring tokens, so every caller — embedded queries
and the background processor alike — goes through connectionWithFreshToken,
which renews from the refresh token before the access token expires.
sequenceDiagram
participant C as Caller (embedded query / processor)
participant T as validAccessToken()
participant DB as system.db
participant S as Shopify OAuth
C->>T: connectionWithFreshToken(tenantId)
T->>DB: read connection
alt token still valid
T-->>C: cached access_token
else expired (or within 5-min skew)
T->>S: grant_type=refresh_token
S-->>T: new access_token + refresh_token
T->>DB: updateConnectionTokens
T-->>C: fresh access_token
end
Staff photograph a disc; two background phases run off the event store. Colour estimation and image processing happen right after intake, and the Shopify variant is created once a weight and description are submitted.
sequenceDiagram
participant Staff
participant App as Next.js app
participant ES as Event store (tenant.db)
participant BP as Background processor
participant S as Shopify Admin API
Staff->>App: POST begin-create-product (photo)
App->>App: auth + subscription gate
App->>ES: event (status: data-entry)
Note over BP: poll cycle (~5s)
BP->>S: estimate colour from photo
BP->>BP: centre disc + remove background
BP->>ES: photo processed, colour set
Staff->>App: POST finish-create-product (weight + description)
App->>ES: event (status: creating)
Note over BP: next poll cycle
BP->>App: GET shopify-connections (fresh tokens)
BP->>S: productVariantsBulkCreate + media (qty 1)
S-->>BP: variant created
BP->>ES: event (status: created)
Shopify hosts plan selection and charging; the app only reads whether the shop has an active subscription (the trial counts as active) from its own Admin API. The blocking "none" answer is re-checked promptly so the gate opens as soon as the merchant approves a plan.
sequenceDiagram
participant M as Merchant
participant App as Next.js app
participant S as Shopify Admin API
participant P as Shopify App Pricing (hosted)
M->>App: open embedded app
App->>S: currentAppInstallation.activeSubscriptions
alt has active subscription
S-->>App: ACTIVE
App-->>M: dashboard
else none
S-->>App: (none)
App-->>M: "Choose your plan"
M->>P: select plan
P-->>App: redirect back with charge_id
App->>S: re-check (skip cache)
S-->>App: ACTIVE
App-->>M: dashboard
end
- Node.js 18+
- npm or yarn
- Shopify store with Admin API access
Legacy in-admin custom apps can no longer be created; the app is distributed as a custom-distribution app owned by the operator:
- Go to https://dev.shopify.com/dashboard and create an app ("Start from Dev Dashboard")
- Create a version with these Admin API scopes:
read_productswrite_productswrite_filesread_filesread_locationswrite_inventoryread_inventory
- Set the Redirect URI to
https://{your-domain}/api/auth/shopify/callback(addhttp://localhost:3000/api/auth/shopify/callbackfor local development) - Release the version and install the app on the client's store (custom distribution install link)
- Copy the Client ID and Client Secret from the app's Settings page into
nextjs-app/.env
The store's access token is NOT configured anywhere: after logging in, the
admin enters the store's *.myshopify.com domain on the dashboard and
approves the app. That produces a non-expiring offline token, stored with the
store's primary location in the system database. Until this happens, the app
is locked for everyone.
# JWT Secret
openssl rand -base64 32
# API Key for background processor
openssl rand -base64 32# NextJS app
cd nextjs-app
npm install
# Background processor
cd ../background-processor
npm installnextjs-app/.env
DATABASE_PATH=./data/system.db
TENANT_DATABASES_PATH=./data/tenants
JWT_SECRET=<your-generated-jwt-secret>
JWT_EXPIRATION=7d
# Required - the app refuses all requests if unset
BACKGROUND_PROCESSOR_API_KEY=<your-generated-api-key>
# From the Dev Dashboard app (see Shopify Setup). Shop domains and inventory
# locations are captured per tenant in the UI connect flow, not configured here.
SHOPIFY_CLIENT_ID=<your-app-client-id>
SHOPIFY_CLIENT_SECRET=<your-app-client-secret>
SHOPIFY_SCOPES=read_products,write_products,write_files,read_files,read_locations,write_inventory,read_inventory
SHOPIFY_REDIRECT_URI=https://{your-domain}/api/auth/shopify/callback
SHOPIFY_API_VERSION=2025-10
PORT=3000background-processor/.env
NEXTJS_API_URL=http://localhost:3000
NEXTJS_API_KEY=<same-api-key-as-above>
POLLING_INTERVAL_MS=5000
# Each tenant's offline token, shop domain and location come from the
# /api/queries/shopify-connections endpoint - only the API version is env
SHOPIFY_API_VERSION=2025-10
OPENAI_API_KEY=<your-openai-api-key>
OPENAI_IMAGE_MODEL=gpt-image-2
IMAGE_BACKGROUND_HEX=#ADD8E6
IMAGE_CANVAS_SIZE=1024
IMAGE_MARGIN_PX=48Development:
# Terminal 1: NextJS app
cd nextjs-app
npm run dev
# Terminal 2: Background processor
cd background-processor
npm run devProduction:
# NextJS app
cd nextjs-app
npm run build
npm start
# Background processor
cd background-processor
npm run build
npm startThe app is multi-tenant with open self-serve registration: each registration creates a new tenant (a store and its staff) with its own event database.
- Navigate to http://localhost:3000 and click "Register your store"
- Register with email + password - you become the admin of a new tenant
- On the dashboard, enter your store's
*.myshopify.comdomain and approve the app on Shopify (one-time; the offline token never expires). A store can be actively connected by only one tenant. - Invite your staff from "Manage Users" - they share your tenant's inventory and are blocked until step 3 is done.
Every tenant repeats the same flow independently; the background processor serves all tenants from one process.
Dev reset: delete nextjs-app/data/ (system + tenant databases) and clear
browser localStorage (old tokens are rejected).
Deployments that predate tenant databases can merge the old
data/users/*.db event databases into one tenant's database (register the
tenant first):
cd nextjs-app
node scripts/migrate-to-tenant-db.js --tenant <tenant-uuid>Shopify token events are deliberately not migrated - the tenant's admin simply re-connects the store from the dashboard.
- Create Restocker Accounts
- Login as admin
- Click "Create User" (if implemented in UI)
- Provide email and temporary password
- Restocker must change password on first login
-
Select Product
- Click "Create Product"
- Search/select Shopify product from dropdown
-
Capture Photo
- Take photo or upload from gallery
- Photo is stored in event store
-
Color & Weight
- Background processor estimates color automatically
- Review/adjust color in dropdown
- Enter weight (e.g., "168G RED PRISM Foil")
-
Create
- Click "Create in Shopify"
- Background processor creates variant with:
- Unique weight (appends 2, 3, etc. if duplicate)
- Selected color
- Uploaded photo
- Inventory quantity: 1
POST /api/auth/register- Create first admin (one-time)POST /api/auth/login- User loginPOST /api/auth/change-password- Change passwordPOST /api/admin/create-user- Create restocker (admin only)
POST /api/commands/begin-create-productPOST /api/commands/record-product-colorPOST /api/commands/finish-create-productPOST /api/commands/record-product-created-in-shopify(API key only)POST /api/commands/record-product-failed-in-shopify(API key only)POST /api/commands/record-product-image-processed(API key only)POST /api/commands/record-product-image-processing-failed(API key only)
GET /api/queries/shopify-products- List Shopify productsGET /api/queries/user-products- User's productsGET /api/queries/product-state- Product statusGET /api/queries/product-image- Product photo (?variant=original|processed, defaults tooriginal)GET /api/queries/products-needing-color-estimation(API key only)GET /api/queries/products-needing-image-processing(API key only)GET /api/queries/products-to-create-in-shopify(API key only)GET /api/queries/product-details-for-shopify(API key only)
CREATE TABLE users (
id TEXT PRIMARY KEY,
email TEXT UNIQUE NOT NULL,
password_hash TEXT NOT NULL,
role TEXT NOT NULL CHECK(role IN ('admin', 'restocker')),
must_change_password INTEGER NOT NULL DEFAULT 0,
created_at INTEGER NOT NULL
);CREATE TABLE events (
id INTEGER PRIMARY KEY AUTOINCREMENT,
aggregate_id TEXT NOT NULL,
event_type TEXT NOT NULL,
event_data TEXT NOT NULL, -- JSON
photo_blob BLOB, -- Only for BeginProductCreated
timestamp INTEGER NOT NULL,
version INTEGER NOT NULL
);- BeginProductCreated - Product creation started (carries the photo blob)
- ColorEstimated - Color estimated by background processor
- ColorSetV2 - Estimated RGB matched to an available Shopify color name
- ProductWeightSet - Weight entered by user
- ProductReadyToBeCreated - Ready for Shopify creation
- ProductCreated - Successfully created in Shopify
- ProductCreateFailed - Failed to create (with retry count)
- ProductImageProcessed - Disc centered on the light blue canvas (carries the processed blob)
- ProductImageProcessingFailed - Image processing failed (with retry count)
- ShopifyTokenReceived - OAuth token stored on the
shopify-authaggregate
data-entry- User is entering informationcreating- Being created in Shopifycreated- Successfully createdfailed- Failed after 5 attempts
- Polls for products without color
- Downloads product image
- Resizes to 100x100
- Calculates average RGB
- Records color via command API
- Polls for products with a photo but no processed image
- Reads the original photo (never the processed one — Job 1 depends on it)
- Sends it to OpenAI
images/edits(gpt-image-2) to replace the surroundings with light blue - Uses
sharpto trim to the disc's bounding box and re-center it on an exactIMAGE_CANVAS_SIZEcanvas filled withIMAGE_BACKGROUND_HEX - Records
ProductImageProcessedwith the resulting PNG - Retries up to 5 times, recording
ProductImageProcessingFailedeach time
The generative step handles background replacement only; centering, canvas size,
margin, and the exact background color are done deterministically in sharp, so
they do not depend on how precisely the model framed the image.
- Polls for products ready to create and already image-processed
- Maps RGB to color name
- Ensures unique weight variant
- Uploads the processed image to Shopify
- Creates variant with photo, color, weight
- Records success/failure
- Retries up to 5 times on failure
Note: because Shopify creation waits for the processed image, a product whose
image processing fails all 5 attempts stays in data-entry and is never created.
The product page surfaces this.
- Commands modify state → emit events
- Events are immutable → append-only log
- Queries replay events → compute current state
- No read model optimization → full replay every time (MVP)
function replayEvents(events: Event[]): ProductState {
let state = { status: 'not-started' };
for (const event of events) {
switch (event.eventType) {
case 'BeginProductCreated':
state = { ...state, status: 'data-entry', ... };
break;
// ... handle other events
}
}
return state;
}- Databases are created automatically on first run
- Located in
nextjs-app/data/directory - One
system.db+ one{uuid}.dbper user
- Check API token has correct scopes
- Verify product exists in Shopify
- Check rate limits (background processor will retry)
- Ensure API key matches in both .env files
- Check NextJS app is running and accessible
- Verify NEXTJS_API_URL is correct
- Optimized read models (projections)
- Bulk upload
- Inventory management (mark as sold)
- Analytics dashboard
- Mobile native app
- Advanced color detection (ML)
- Frontend: Next.js 14+, React, TypeScript, Tailwind CSS
- Backend: Next.js API Routes, Node.js
- Database: SQLite (better-sqlite3)
- Authentication: JWT, bcrypt
- Image Processing: Sharp
- E-commerce: Shopify Admin API
MIT
For issues and questions, please refer to the original specification document.
