Skip to content

About

Margin Protector AI — Autonomous profit recovery for Shopify merchants. 6 deterministic heuristics, transparent AI reasoning, 1-click GraphQL execution. Next.js 16, React 19, Tailwind CSS 4.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Margin Protector AI. Shopify, margin audit, hackathon build. Find the profit leaks. A Shopify margin audit. Six deterministic checks flag dead stock, shipping erosion and stockouts, and each fix shows its math. 6 deterministic heuristics, no model calls, Shopify Admin GraphQL, demo store dataset. marginprotectorai.vercel.app



Open the dashboard   Open the Bazaar demo   Read the six heuristics



Demo site status Built at the OpenClaw Hackathon 2026 Data: demo store seed Next.js 16 React 19 Tailwind CSS 4 Shopify Admin API 2026-01 License: MIT

See where a store loses margin, and the math behind every fix.

Load  →  Audit  →  Rank  →  Explain  →  Preview


How it works  ·  The six heuristics  ·  Status  ·  Run it locally


Two dashboard screens on the demo store. 01, see where margin leaks: revenue, conversion, sessions and pending orders up top, overstocked SKUs show their monthly holding cost, and low stock shows CRITICAL. 02, read the math behind each fix: Run Audit ranks ten action cards on the demo store, and each card opens its arithmetic: capital tied up, holding cost, recovery and break-even.

Captured from a local production build (next start) on 30 October 2026 with the bundled demo dataset. The "Shopify Connected" label in the header is static: this build reads no store.

Margin Protector AI is a Shopify profit-leak audit dashboard built at the OpenClaw Hackathon 2026. It runs six deterministic heuristics over products, orders and daily analytics, ranks what it finds by urgency, and explains every recommendation with plain arithmetic (capital tied up, holding cost, recovery, break-even) rather than a model's guess. Today it runs on a bundled demo store: the dashboard does not read a live store, and its Deploy Fix button plays a scripted preview rather than calling Shopify.

Built by Matt (RVAClassic, Operator Uplift) at the OpenClaw Hackathon 2026, March 2026.


How it works

Store data, margin engine and dashboard. Store data is a demo seed: 8 products, 25 orders and 7 days of analytics, shaped like Shopify Admin records, with prices in integer cents. The margin engine runs six heuristics: dead stock, shipping erosion, critical restock, conversion dip, refund anomaly and pending backlog, with plain arithmetic and no model calls. The dashboard shows ranked fixes: ten action cards on the demo seed, each with its math in an AI Thinking panel; Deploy Fix previews a mutation and nothing is sent.

The dashboard loads products, orders and analytics from three API routes, then posts to /api/margin/analyze, which runs src/lib/marginAnalyzer.ts and returns action cards. Every number is computed from the data with fixed assumptions written into the code: a 2% monthly holding cost, a 35% clearance discount, 45% cost of goods, a $55 average order and a 3.5% benchmark conversion rate. The reasoning text also quotes fixed benchmark figures (for example, a 22% return reduction from fit quizzes) that are part of the template, not measurements.

Deterministic
The same data always produces the same cards. There is no language model in the analysis path, so nothing is invented between the numbers and the recommendation.
Shows its work
Each card has a description, a proposed execution and a collapsible AI Thinking panel with the dollar amounts, ROI and break-even behind it.
Ready for Shopify, not wired to it
POST /api/shopify/discount can create a real discount code through the Admin GraphQL API when credentials are set. The dashboard does not call it yet.

Next.js 16.2 (App Router, Turbopack) · React 19 · TypeScript (strict) · Tailwind CSS 4 · shadcn/ui and Magic UI · Framer Motion 12 · Shopify Admin GraphQL API 2026-01 · Vercel


The six heuristics

All six live in src/lib/marginAnalyzer.ts. On the demo seed they produce ten cards: one clearance bundle and three per-SKU stale-inventory alerts, one shipping alert, two restocks, one conversion campaign, one refund alert and one backlog alert.

# Heuristic Trigger Urgency What it proposes
1 Dead stock bundle Not archived, more than 50 units, 0 sold in 30 days HIGH, plus a MEDIUM alert per SKU A 35% clearance bundle; per SKU, a 40% markdown on secondary channels
2 Shipping margin erosion Active, shipping cost above 40% of price HIGH Renegotiate the carrier rate, or raise the price by half the gap and A/B test it
3 Critical restock Active, stock below the reorder threshold HIGH A purchase order for three times the threshold, expedited freight and a backorder page
4 Conversion dip Any day below 3.0% conversion MEDIUM A 15% flash sale, abandoned-cart emails and $500 of retargeting
5 Refund rate anomaly Refunds above 5% of orders MEDIUM Audit refunded orders, improve sizing guides, add a fit quiz
6 Pending order backlog Four or more orders pending LOW Escalate old orders and send proactive delay notices

Status

Hackathon Built at the OpenClaw Hackathon 2026; the last commit is from 28 March 2026. The demo deploys to marginprotectorai.vercel.app, with the marketing page at /landing. Demo
Demo data The dashboard and every analysis route read the bundled seed in src/lib/mockShopifyData.ts, which is built to trigger all six heuristics. No route reads a live store's products, orders or analytics. Demo seed
API only POST /api/shopify/discount sends a real discountCodeBasicCreate mutation when SHOPIFY_STORE_URL and SHOPIFY_ACCESS_TOKEN are set, and returns a mock response ("source": "mock") without them or after any Shopify error. In the dashboard, Deploy Fix shows a client-built payload and a scripted success message, and the restock preview shows a purchaseOrderCreate payload that is never sent. Discount route

Run it locally

Prerequisites
Node 20.9 or newer (Next.js 16's minimum) and pnpm. No store or credentials are needed for the dashboard.
Read first
marginAnalyzer.ts for the rules and AGENTS.md: this Next.js version has breaking changes.
What the checks prove
Types and the production build. There is no test suite, and pnpm lint currently reports two React hook errors.
git clone https://github.com/operatoruplift/Margin-Protector-AI.git
cd Margin-Protector-AI
pnpm install
pnpm dev                 # http://localhost:3000, marketing page at /landing
pnpm build && pnpm start # production build
pnpm exec tsc --noEmit   # type check
pnpm lint                # ESLint with the Next.js config

To try the discount route against a real development store, copy .env.example to .env.local and set both values. The route then posts to https://<store>/admin/api/2026-01/graphql.json; without them it answers with a mock.

Variable Used by
SHOPIFY_STORE_URL POST /api/shopify/discount: the your-store.myshopify.com host
SHOPIFY_ACCESS_TOKEN POST /api/shopify/discount: an Admin API access token that can create discounts
curl -X POST http://localhost:3000/api/shopify/discount \
  -H 'content-type: application/json' \
  -d '{"sku": "APJ-BLK-L", "discountPercentage": 35, "productTitle": "Alpine Puffer Jacket"}'
API routes
Route Returns
GET /api/products The 8 demo products
GET /api/orders The 25 demo orders
GET /api/analytics Seven days of demo analytics
POST /api/margin/analyze Action cards from the six heuristics
POST /api/agent/run The same output, kept for backward compatibility
POST /api/shopify/discount A discount code from Shopify, or a mock without credentials

The three data routes wait 400 ms before answering, to simulate a store API.

Architecture diagram
flowchart LR
    subgraph Client["Next.js 16 dashboard"]
        UI["React 19 UI"]
        Terminal["Audit terminal"]
    end

    subgraph Routes["Next.js API routes"]
        API["/api/margin/analyze"]
        Data["/api/products, /orders, /analytics"]
        Discount["/api/shopify/discount"]
    end

    subgraph Engine["Margin analyzer"]
        H1["Dead stock"]
        H2["Shipping erosion"]
        H3["Critical restock"]
        H4["Conversion dip"]
        H5["Refund anomaly"]
        H6["Pending backlog"]
    end

    Seed["Demo seed (mockShopifyData.ts)"]
    Shopify["Shopify Admin GraphQL"]

    UI --> Data
    Terminal --> API
    Data --> Seed
    API --> Seed
    API --> Engine
    Discount -.->|only with credentials, not called by the UI| Shopify
Loading
Repository layout
Path Contents
src/app/page.tsx The dashboard: KPI ribbon, inventory, orders, audit terminal, action cards, reports, executions and settings views
src/app/landing/page.tsx The marketing page
src/app/api/ The six API routes listed above
src/lib/marginAnalyzer.ts The six-heuristic engine
src/lib/mockShopifyData.ts The demo store seed
src/types/index.ts Shared product, order, analytics and action types
src/components/ui/ shadcn/ui and Magic UI components

The code is MIT licensed (see LICENSE), as the original README intended. The demo store, its products, orders and customers are fictional.

Built by Matt Sim, founder of Operator Uplift. More builds at github.com/operatoruplift. Want one built for your product? Book a 15-minute call.

About

Margin Protector AI — Autonomous profit recovery for Shopify merchants. 6 deterministic heuristics, transparent AI reasoning, 1-click GraphQL execution. Next.js 16, React 19, Tailwind CSS 4.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages