Wiki

01 Outside systems

Nine things outside this repo. If something misbehaves, it is nearly always one of these, and the table says which files are the ones talking to it.

02 Domains & environments

03 Scheduled jobs (crons)

Most scheduling is GitHub Actions: each workflow curls an endpoint with the x-audit-key header. SIM activation is the exception — Vercel calls it directly from the schedule in vercel.json and authenticates with CRON_SECRET. In both cases the endpoint holds the logic and the scheduler holds only the clock.

Reading a cron expression

Five fields: minute hour day-of-month month day-of-week, always UTC (so in British Summer Time everything runs an hour later than the number suggests).

• 0 1 * * * — minute 0 of hour 1, every day.
• 0 */6 * * * — minute 0, every 6th hour.
• 0 5 */3 * * — 05:00, every 3rd day of the month.
• 0 9 * * 1 — 09:00 on Mondays (day-of-week: 0 = Sunday).
• 15 * * * * — minute 15 of every hour.

Adding a new scheduled job

1. Write the endpoint in api/. For a GitHub Action, protect it with verifyAuditKey(req) and a POST-only check. For Vercel Cron, compare its bearer header to a configured CRON_SECRET and fail closed if the variable is absent.
2. Add a workflow in .github/workflows/ with a schedule: block and workflow_dispatch:, curling ${{ secrets.VERCEL_DOMAIN }}/api/your-endpoint with -H "x-audit-key: ${{ secrets.AUDIT_API_KEY }}".
3. Merge to main — scheduled workflows only ever run from the default branch, so a cron on a feature branch will never fire.

04 A tier order, end to end

Signal, Flow and Capture are the only things sold. This is the whole path from the pricing page to a SIM in someone’s hand.

1. 1

   The customer builds an order

   Quantities per tier, monthly or annual, physical SIM or eSIM, and optionally a router. An eSIM order also has to say which phone — the QR email links to a device-specific setup guide, and there is no safe guess. The page will not let an eSIM order reach payment until that is answered.

   Prices come from /api/tier-prices, read out of the Stripe catalogue rather than hardcoded, so a wallet sheet can never promise an amount the invoice disagrees with.

   checkout.htmljs/checkout.jsapi/tier-prices.js
2. 2

   The server prices it and creates the payment

   The browser sends tier keys and quantities, never prices. Everything chargeable is looked up server-side, so a tampered request can change what is bought but never what it costs. A router with no SIM is refused outright — it has nothing to connect to.

   One shape of order: a Subscription created default_incomplete, any routers added to its first invoice, and that invoice’s PaymentIntent is what the customer confirms. The order reference is minted here so the same one reaches the confirmation page and the email.

   api/create-tier-payment.jsapi/lib/tier-catalogue.js
3. 3

   Nothing exists until the card clears

   No account, no order, no service, no SIM claimed. This is a rule with a test around it (test/payment-integrity.test.mjs): the legacy checkout wrote rows as it went, which left abandoned orders and SIMs held against payments that never completed.

4. 4

   Stripe fires payment_intent.succeeded

   The tier webhook verifies the signature, ignores anything that is not a tier order, and provisions: the account, the order, one service per SIM (three Signal SIMs is three things the customer holds, each with its own ICCID), a claimed SIM for each, and a service per router. The order insert is the idempotency claim — a unique index on the payment intent id means a duplicate delivery loses it and stops.

   If stock runs out the webhook does not fail: the money has already moved, and the service row is the record that someone is owed a SIM. It waits on the To Do list until stock arrives, and is allocated automatically the moment it does.

   api/tier-stripe-webhook.jsapi/lib/tier-fulfilment.jsemail
5. 5

   You fulfil it

   eSIM: To Do → eSIMs to issue, one row per QR. Mark issued sends the QR, the setup guide for the recorded device, and the activation code for anyone who cannot scan a code on the phone they are installing to.

   Physical: the order page’s Fulfillment panel. Tick what is in the envelope, add the tracking number, Mark as Posted. One email per parcel, so an order that ships in two goes gets two.

   api/admin/services/[id]/fulfil.jsapi/lib/fulfillment-service.js
6. 6

   It renews, or it does not

   Renewals move the period forward on every service on the subscription. A failed payment flags them past_due and emails the customer once — not on each of Stripe’s retries. A cancellation ends every service on it. See §05.

   api/lib/subscription-lifecycle.js

05 Everything that touches Stripe

Our code → Stripe

Stripe → our code

Two endpoints, each with its own signing secret. POST /api/tier-stripe-webhook (STRIPE_TIER_WEBHOOK_SECRET) provisions tier orders and handles subscription lifecycle for every subscription on the account. POST /api/stripe-webhook (STRIPE_WEBHOOK_SECRET) is the legacy handler for router and eSIM orders from the deleted checkout. Both verify the signature against the raw bytes, so body parsing is off on each.

06 Refunds & router returns

All refunds start on the order page in this portal (admin/order.html → POST /api/admin/orders/:id/refund) and are attributed to the signed-in admin. They used to be Slack buttons; that endpoint has been deleted, so an old button now 404s.

The endpoint branches on product_type — everything below lives in api/lib/refund-service.js.

eSIM — one step

• processEsimRefund() → Stripe refund (full or partial pence amount) → refunds row completed → order refunded → service cancelled → customer email → Slack alert.

Router — three steps, because the hardware has to come back

1. 1

   Initiate return

   initiateRouterRefund(): no money moves yet. Order → return_initiated, a pending refunds row is written, a return CSV is generated into the shipping bucket, and Slack is alerted. The order appears under To Do → “Return labels to send”.

   POST /api/admin/orders/[id]/refundGET …/return-label-csv
2. 2

   Send the label

   You download the CSV, give it to Evri, get a return QR back, and upload it on the order page (PDF/PNG/JPEG, 8 MB max). That stores it in the shipping bucket and emails the customer their label.

   POST …/return-labelEMAIL_TRIGGERS.RETURN_LABEL_ROUTER
3. 3

   Router arrives → complete the refund

   completeRouterRefund(): now the Stripe refund happens. Refunds row → completed, order → refunded, service → cancelled, subscription cancelled, and the “return processed” email goes out. Shows under To Do → “Refunds to confirm” until then.

   POST …/complete-returnEMAIL_TRIGGERS.RETURN_PROCESSED_ROUTER

07 Emails & templates

Every customer email goes through one function: sendTemplatedEmail(TRIGGER, { to, orderReference, variables }) in api/lib/email.js. It resolves the template (your saved override if there is one, otherwise the code default), substitutes {{tokens}}, wraps it in the shared layout, and sends via Resend.

Not templated

• api/contact.js — the marketing site’s contact form, forwarded straight to support@go-unbounded.co.uk with the Resend SDK directly.
• Support replies from the Support tab — those go out through Gmail, not Resend (§11).

Editing templates

Email Templates lists every trigger. Editing one writes a row to email_templates keyed by trigger; that row wins over the code default from then on. The table starts empty on purpose — an unedited trigger shows its code default from api/lib/email-templates.js. Reusable bits (buttons, detail boxes, QR image box) come from api/lib/email-blocks.js and are injected as {{tokens}}, which is why you’ll see tokens in the editor you don’t have to fill in yourself.

08 Slack notifications

Three separate ways we post to Slack, with three separate credentials. This is the most confusing corner of the setup, so it’s worth reading once.

Every Slack path is best-effort: a missing webhook URL is logged and skipped, and a failed post never fails the order or the refund.

09 Admin portal page map

Each page is a static shell; all data arrives from /api/admin/*, which is gated by requireAdmin (session cookie + ADMIN_EMAILS allowlist, re-checked every request). On a 401 the shared helper in admin/admin.js bounces you to the login page.

10 Support inbox (Gmail)

The Support tab is a thin Gmail client for the Workspace mailbox that support@go-unbounded.co.uk and hi@go-unbounded.co.uk both deliver into (they’re alternate addresses on one account, so one connection covers both).

• Connecting: gmail/oauth-start → Google consent → gmail/oauth-callback stores the refresh token in the gmail_connection table. It’s a singleton row (id = 'default') — reconnecting overwrites it.
• Scopes: gmail.readonly, gmail.send, gmail.modify, userinfo.email.
• Which threads show: a Gmail search for to:support@… OR to:hi@…, newest first.
• Replying sends through the Gmail API as the connected mailbox — it does not go through Resend, so support replies never appear in Resend logs.
• The stored refresh token is live credentials for the mailbox. That row is service-role only, RLS on, no anon policy.

11 Admin sign-in & passkeys

Nobody types a password. You sign in with a passkey (Face ID / Touch ID / Windows Hello / security key) against Supabase Auth; first-time setup goes through an emailed sign-in link. Two things must both be true for any admin request to succeed: a valid Supabase session, and your email in ADMIN_EMAILS. The allowlist is re-checked on every request, and it fails closed — unset means nobody is an admin.

Session state lives in two HttpOnly cookies (admin_session, admin_refresh). Endpoints are same-origin on the admin subdomain, so there’s no header secret involved. The step-by-step setup guide — DNS, Vercel env vars, Supabase config, adding devices — is in admin/README.md.

12 Database tables & storage

Storage buckets

• shipping — outbound Evri CSVs (csv/evri-shipping-*.csv), return CSVs, and uploaded return labels. Handed out as signed URLs (1 hour for CSVs, 7 days for labels).
• esim-qr-codes — the QR images emailed to eSIM customers, referenced by sim.qr_code_path, signed for 7 days.

13 Status values

orders.status

service

status is active or cancelled. subscription_status tracks Stripe separately and starts as active, becomes initial once the renewal subscription is created with its year-long trial, then mirrors Stripe (trialing, active, past_due, cancelled). cancelled_at is the date the service ends — which is exactly what the 01:00 and 12:00 crons scan for.

14 Environment variables

Set in Vercel (Production and Preview separately — Preview values apply to all preview deploys, not just test). Cron secrets live in GitHub repo settings instead.

GitHub repository secrets

VERCEL_DOMAIN (base URL the crons curl), AUDIT_API_KEY (must match Vercel’s), TEST_SUPABASE_URL, TEST_SUPABASE_ANON_KEY.

15 Something’s broken — where to look

16 Keeping this page honest

This page is plain hand-written HTML in admin/wiki.html — no API, no database. It cannot go out of date on its own, which means it will go out of date unless it’s edited alongside the change. The moments that matter:

• New scheduled job → add a row to §03.
• New or changed Stripe event handling → §06.
• New email trigger → §08 (and it’ll appear in the Email Templates page automatically).
• New env var → §15, with what breaks when it’s missing — that column is the useful one.
• New admin page or endpoint → §10.

Deeper reference lives next to the code: admin/README.md (portal setup, DNS, passkeys, Gmail OAuth) and api/SECURITY.md (trust boundaries and the reasoning behind them).