All work
Case 04Internal Tool · Shopify Admin

Shopify Product Bulk Operations Suite

Configure query filters, upload a product workbook, run prepare → process → review → update against the Shopify Admin API — from a single web UI.

Role
Full-Stack Engineer
Year
2026
Discipline
Internal Tool
Stack
6 technologies
FastAPIReact 19PostgreSQLShopify Admin GraphQLAlembicTailwind v4

What it does

  • Configure query filtersFor the products and media that should be pulled from a store (handles, vendors, tags, date ranges, wildcards).
  • Upload a Data.xlsx workbookWith the desired product changes; the app validates schema and required fields before letting a run start.
  • Pull live store dataThrough three Shopify bulk GraphQL queries (products, pricelists, files) and download the JSONL results.
  • Classify each rowInto IMPORT / REBUILD / UPDATE / SKIP, then emit a human-readable report.xlsx plus five JSONL mutation payloads.
  • Human review gateThe merchant approves the diff before any write goes through.
  • Fan-out the updatesAs five Shopify bulk mutations, listening to the bulk_operations/finish webhook for completion.

Tech stack

Backend

Python 3.12, FastAPI, SQLAlchemy 2, Alembic, PostgreSQL (SQLite for smoke tests), Pydantic v2, httpx, openpyxl.

Frontend

React 19, Vite 6, TypeScript, Tailwind v4, shadcn/ui, React Router 7.

Shopify integration

Admin GraphQL API, bulkOperationRunQuery / bulkOperationRunMutation, stagedUploadsCreate, HMAC-verified webhooks. Every .graphql file is validated against the live Admin schema in CI.

Auth

Shopify OAuth with role mapping (owner / staff / collaborator), HS256 session JWTs, optional Clerk sign-in path verified against Clerk’s JWKS. Stateless, in-memory token storage on the client.

Engineering highlights

  • Single-process pipeline

    No Celery, no Redis, no subprocess calls — the API does prepare, process, and update in-band, with run state persisted in Postgres and artifacts on disk.

  • Dual-dialect database layer

    The same models and queries run against Postgres (Alembic-managed, prod) and SQLite (zero-setup, smoke tests).

  • Cross-platform storage layout

    A single STORAGE_ROOT resolves to the right OS-specific app-data directory via platformdirs (Windows / macOS / Linux), with config, uploads, run artifacts, and webhook events living under one tree.

  • Schema-validated GraphQL

    Custom build step that round-trips every query and mutation through the Shopify Admin schema before commit — catches breaking changes from the API surface, not from production.

  • Structured access logs

    One JSON line per request to stdout, ready to ship into any log pipeline.

  • SPA + API in one binary

    A single uvicorn process serves the React bundle and the API; deployment is one container behind a TLS proxy.

What it demonstrates

  • Designing and shipping a non-trivial integration against a third-party GraphQL API (Shopify Admin) with bulk operations, webhooks, and OAuth.
  • Owning the full stack — auth, data modeling, migrations, business logic, UI, deployment story — with clean separation between routes, services, and schemas.
  • Pragmatic architecture choices: polling over websockets, in-process over queues, file-system artifacts over object storage, until scale demands otherwise.
  • Disciplined repo hygiene: phased migration plan, tracked follow-ups, reproducible local setup, CI-validated GraphQL.

Stack at a glance

FastAPI · React 19 · TypeScript · PostgreSQL · Alembic · Tailwind v4 · shadcn/ui · Shopify Admin GraphQL · OAuth + JWT · Clerk · HMAC webhooks

Previous case · 03

Shopify CRO Audit Pipeline

End-to-end internal tool: FastAPI backend, React 19 frontend, one process owning the full pipeline. No external worker, no queue, no headless browser farm.

Next case · 01

Content Automation Pipeline

Production-grade content factory: image gen → video clips → voiceover → captions → assembly → cost ledger → database sync.