Technical briefing

Read this before you change a Worker, a theme file, or a P&L formula. It is the context of the running estate — not a sign-in tutorial.

What this estate is

Our Tech Accessories is a UK-only Shopify shop (ourtechaccessories.com). It sells everyday tech accessories (chargers, MagSafe banks, mounts, cases). There is no high-street stock. A partner packs the box — mostly CJ Dropshipping, with leftover AliExpress / DSers fulfilments. James is still the merchant: the card charge, the brand, and “where is my order?” sit here.

The public face is three things: the storefront, the store mailbox, and /pages/track. Profit Admin, Meta Ads Manager, supplier consoles, and this git workspace are operator surfaces. Customers never log into those.

flowchart TB
  subgraph public [Customer-visible]
    store["Shopify storefront"]
    hello["Store mailbox"]
    track["/pages/track"]
  end
  subgraph edge [Edge]
    mx["Mail forwarding"]
    proxy["track-proxy Worker"]
    access["Cloudflare Access"]
  end
  subgraph back [Back office]
    desk["Profit Admin"]
    gmail["Store Gmail + desk Assist"]
    meta["Meta ads + Pixel"]
    cj["CJ / DSers / Alibaba"]
    agent["Cursor in business-ops"]
  end
  store --> meta
  store --> cj
  hello --> mx --> gmail
  track --> proxy --> cj
  access --> desk
  desk --> store
  desk --> meta
  desk --> cj
  agent --> desk
  agent --> store
  agent --> meta
        

Money, parcels, and mail each have one owner. Do not add a second path that the customer or the P&L will see twice.

Two repositories

Canonical skill edits live in skills/ and shared/skills/, then ./scripts/sync-skill.sh. Copies under .cursor/skills/ are generated. Apps Script is paste-deployed: a git change does nothing until someone pastes it into the store Google account.

The public briefing at jamesmmiller.github.io/profit-admin-docs is a copy of apps/profit-admin/site/. After you change those files, run ./scripts/publish-docs.sh. Do not edit the Pages repo by hand.

Live surfaces

The Android Profit Admin PWA is retired. Phone and laptop use the hosted desk. Worker ota-profit-admin only redirects there.

Hosted desk — Ads

Ads → Performance defaults to the whole Meta ad account. Split by campaign, ad set, or ad overlays that level on the daily totals. Intra-day lists every ad that delivered in the current scope, with a day sparkline plus spend, share, purchases, ROAS, and CTR. Click a row to plot that ad on the hourly chart (up to six; four when comparing two periods). Dashed lines are the comparison set. Views, named subsets, SKUs, and object pickers live under Advanced — they are not the first screen.

Empty object ids on Insights means account-level. The same rule applies to the machine API split field (campaign / adset / ad).

Hosted desk — Mail

Mail shows the store inbox for an owned address such as the store mailbox. Genuine customer mail that still needs a reply is listed first. Filters include Assist drafts and Needs you. Assist is two-tier triage: a cheap path drafts pitch, FAQ, and volume-deal replies from built-in seed templates; a tool-using agent drafts tracking replies from Shopify and track-proxy facts; refunds, returns, and damage escalate with no draft by default. Mail → Assist has presets (safe drafts, auto cheap, human only, paused), per-category action chips, and an effective-routing summary (auto-send needs an explicit master switch; refund never auto-sends). You still send through the Gmail API unless a category is set to auto-send. A scheduled poll drafts replies in the background. A saved reply can also be added through the API. Edit a template under Mail → Templates (built-ins save as an org override with the same id). The mailbox is still Gmail, with the store address forwarded to it. Once desk drafts have proven themselves, the old inbox bot is retired; fulfilment “on its way” mail goes track-proxy → Profit Admin. The Gmail connection is stored in D1, so a Container replace does not drop the mailbox connection. Empty saves never clear the refresh token or owned addresses; only Disconnect deletes the row.

Components, sequence diagrams, the draft lifecycle, and a “no drafts appearing” checklist are on the Mail system page.

How a sale becomes a desk number

1. Meta (or organic) lands on a locked PDP handle. Do not rename live campaign URLs; hot-swap the product under the handle.
2. Shopify checkout. Payments Basic UK — the desk assumes 1.5% + £0.25.
3. Fulfilment: CJ app or leftover DSers. Tracking lands on the Shopify fulfilment; track-proxy verifies the webhook, caches CJ, and can fire branded “on its way” mail.
4. Profit Admin collectors pull Shopify orders, Meta Insights, and landed COGS (DSers ledger → CJ API → Shopify unitCost). pnl.py is the only formula.
5. Hosted: Shopify webhooks bump the orders clock; a 15-minute cron bumps the ads clock and a short tracking batch for Delivery times. The desk polls clocks and reloads. Full Refresh still owns CJ freight and catalog.

Meta has no spend webhook — Ads can lag 15 minutes. A new webhook order may sit on unitCost until the next full Refresh quotes freight. Never invent cost on a Worker-only path.

Finance on the desk is that same P&L, summed for a period (all time, this month, last 7 days, last 30 days) against the matching prior window. It is a management view, not a tax computation. Bank readings, and any large debtor or creditor, are figures an owner types in. A reading can be removed, and it can store the all-time profit beside the balance. There is no bank feed. Customers pay at checkout, so the desk does not keep an aged debtor ledger.

Who owns which data

Invariants

Trust boundary on the desk

Humans sign in through Cloudflare Access (Google). A separate operator-only fallback exists and is documented privately. The Worker passes the verified identity, role and organisation on to the engine, and in the hosted setup the engine refuses requests that did not come through the Worker (except public paths). Viewer POST to Refresh / Settings is 403.

Machines: POST /api/v1/oauth/token then Bearer access token (or a long-lived API key for scripts). OpenAPI is at $BASE/docs. Cloudflare admin credentials are for deployment and Access administration only — never the desk Bearer.

Where to change what

Read next

1. C4 diagrams on this site — estate, then desk.
2. docs/estate/technical.md — operator reference, purchase sequence, fulfilment lanes.
3. profit-admin docs/architecture.md — request path, clocks, Refresh, storage layout.
4. docs/api-agents.md + the profit-admin skill — only when you are calling the machine API.

Longer product tutorials stay in docs/tutorial. They assume you already have this map.