Nudge Tags — the whole machine, on one page

01 What the business actually is

Two products, sold together, in that order. The plaque gets you in the door; the subscription is the business.

02 The whole process, start to finish

Three tracks run in parallel: making the plaque, the tap itself, and the money. Click any box for the detail behind it.

03 Every address we own

Four things are live on the internet under this brand. Everything else is a redirect or a reserved name.

DNS and email — where the domain actually points

Every route on app.nudgetags.com

This is the complete list. Anything not here does not exist.

Open to the public — no login

Signed in — a venue owner or their staff

Ours only — the operator surfaces

04 Every URL, complete

Every address the business owns or answers on — public pages, customer links, operator-only screens, machine endpoints, redirects and consoles. If a URL exists and is not on this list, the list is wrong.

nudgetags.com — the public marketing site

app.nudgetags.com — customer-facing

The two generated pages are worth understanding: the slug is the customer's name lowercased with anything non-alphanumeric turned into hyphens, capped at 48 characters — "The Lark Café" becomes /welcome/the-lark-caf. Each close's exact URL is also written onto its row in the Income sheet, so the link is recoverable from the books.

app.nudgetags.com — signed in

app.nudgetags.com — ours only

Machine endpoints — nothing to click, but they exist

Subdomains and redirects

Updated 22 Aug 2026: no .vercel.app address serves anything any more. ops.nudgetags.com was created and the Operations Map moved onto it; nudge-tags-ops and nudgetags.vercel.app now 307 to the owned domain, joining nudge-reviews.vercel.app which already did. quote.nudgetags.com was moved off the retired quote project and its redirect now fires. Per-deployment URLs (<project>-<hash>-purple-pi-marketing.vercel.app) still resolve, embed the team name, and should never be sent to anyone.

Consoles — where to log in

05 Google — what it does, when it costs money, and what to check

There is no single "Google API". There are five separate touchpoints, and only three of them cost anything. The one that earns the money is free.

The five touchpoints

How the free part works — the bit that actually earns

Every Google Maps URL for a place carries a feature id that looks like !1s0x6b91598d0ef1ec8f:0x5177853dd7667eae. Dropped into a specific URL shape with the action code !12e1, that opens the review composer directly:

https://www.google.com/maps/place//data=!4m3!3m2!1s<FEATURE-ID>!12e1
                              ↑
                    the empty name segment is required — do not "tidy" it away

When an owner pastes a link, the app runs this ladder:

1. Is it Google at all?

   The hostname must be one of g.page, goo.gl, maps.app.goo.gl, google.com, search.google.com, maps.google.com, business.google.com. Anything else is refused with "That link isn't a Google one."

2. Is it already a review link?

   If it contains /writereview, /review or !12e1, it is left exactly as it is. A g.page/r/…/review link from Google's own "ask for reviews" button is already the best form there is.

3. Is it a short link?

   A maps.app.goo.gl link — what the Maps share button gives you — is followed server-side to the full URL. Hard limits: two hops, five seconds, and each hop must still be a Google host. This is why the conversion endpoint requires a login: otherwise it would be an open URL fetcher for anyone.

4. Pull out the feature id and rebuild.

   The owner is shown exactly what changed: "We converted your Maps link so it opens the review box straight away." Nothing is ever silently rewritten.

5. A ?cid= link is saved but flagged.

   A CID is only half the feature id, so the review link cannot be built from it. Rather than quietly save something that lands on the listing, the owner is told to re-copy the URL from the browser bar while viewing the place.

Turning the paid part on — the exact steps

Everything above the line works with no key. Below the line is what a key buys, and it is one key for all four paid calls: GOOGLE_PLACES_KEY. It is not set in production today, which is why every venue card shows a lettered tile instead of a photo and the rating-over-time chart is permanently empty.

1. Create a Google Cloud project

   Under the nudgetags.com Workspace account, not a personal one, so it survives a laptop change. Attach a billing account.

2. Enable two APIs — they are separate switches

   Places API (New) and Street View Static API. Enabling one does not enable the other, and the failure mode is a silent null rather than an error.

3. Set a budget alert and a quota cap before anything else

   Google removed the old flat $200/month credit in 2025 in favour of per-SKU free allowances. Nothing in our code caps spend. Set a hard daily quota per API and a billing alert at a figure you are willing to lose.

4. Mint two keys, not one

   This matters. The shopfront photo is loaded by the customer's browser, which means the key ends up in the page source where any signed-in customer can read it. A server key must be IP-restricted or secret; a browser key must be referrer-restricted — and Google does not let one key carry both kinds of restriction.

   Key A (server): Places API (New) only, used by the lookup and the daily rating job. Key B (browser): Street View Static + Places Photo only, restricted by HTTP referrer to app.nudgetags.com. Splitting these is a small code change and it is the difference between a leaked key being harmless and a leaked key being someone else's bill.

5. Set CRON_SECRET in the same deploy

   The daily rating job spends money per venue. The code fails closed — the moment a Places key exists without a cron secret, the job returns 503 rather than let an open endpoint run up a bill. Set both together or the ratings never start collecting.

6. Add the key in Vercel and redeploy

   Project nudge-reviews → Settings → Environment Variables → Production. Environment changes need a redeploy to take effect.

7. Backfill the venues

   The address lookup only fires when someone changes the Maps link in Settings — deliberately, so unrelated saves don't cost money. Existing venues will need their Maps link re-saved once each to pick up an address and photo.

"How is it enabled per venue?"

It isn't, and this is the single most misunderstood part of the setup. The key is global — one key, all customers. What varies per venue is whether that venue has given us something to look up. There are two different Google fields on two different screens, and filling one does not fill the other:

Only two link shapes are accepted for the Maps field: the address-bar URL of a venue's page (which always contains /maps/place/) and the short link the share button produces. A search URL is refused on purpose — a search can resolve to a different business with the same name, and the wrong shopfront on a customer's card is worse than no photo.

What a human has to keep an eye on

06 Every account and service in the stack

Ten external services. For each: what it does, where to log in, what it costs, and what happens if it disappears.

07 Keys and settings — the complete register

Every setting the app reads, whether it is set today, and exactly what changes if it is wrong. Set in Vercel → project nudge-reviews → Settings → Environment Variables → Production. Changes need a redeploy to take effect.

08 What we store, and where

Twenty-one tables in one Postgres database in Sydney. This is every piece of data the business holds about a customer or their customers.

What happens when you delete something

Deleting a business erases that customer completely: their users, venues, tags, every tap, every rating, every complaint and every pending invite. Deleting a venue erases all of that venue's history. There is no soft delete, no archive and no undo. This is why deleting a venue is the most locked-down action in the whole product — it needs a superadmin email, the owner role, typing the venue's exact name, and re-entering the account password.

The intended way to switch something off is the active flag, not deletion. Pausing keeps the printed QR codes and plaques valid so they work again the moment you switch back on.

Changing the database

1. Nothing runs automatically.

   Not on deploy, not on start-up. A release that needs a new column will crash in production until a human runs the migration by hand. This is the most important operational fact in this section.

2. The command

   cd ~/Documents/claude/nudge-tags/nudge-reviews
   DATABASE_URL="<the pooler string>" npm run db:migrate

3. There is no ledger of what has run.

   Every migration file is re-executed every time. It is safe only because each one is written to be repeatable — but see the risk list, one of them is not, and it quietly re-grants access on every run.

09 Every form, and where it ends up

One rule: nothing is captured that isn't stored somewhere we own and shown on a screen someone opens. If a row can't be pointed at on this page, it shouldn't be collected. Audited end to end on 22 August 2026.

Customer-facing — the things a member of the public touches

Dashboard — the things a customer or an operator submits

Why a new link is covered automatically

New tables, staff cards and placements need no wiring. A tap records the ?c= code onto the visit, and every board reads whatever tags that venue currently has and joins on that code. Nothing enumerates placements in code, so a placement created a minute ago appears on the next page load with no deploy and no configuration.

The one thing that escaped this was traffic on a link with no matching placement — a bare /r/<slug> records as direct, and a QR printed before a tag existed keeps its old code. Those taps counted in the venue's totals but appeared in no row, so the total quietly exceeded the sum of its parts. The placement board now ends with a “Not on a placement” line, so the two always reconcile on screen.

Known gaps

Fixed in this audit

• The website contact form posted to formsubmit.co, a third-party relay that emailed the inbox and stored nothing. No count, no list, no way to tell a quiet week from a broken form — and if the relay was never activated, early enquiries were lost silently. It now posts to /api/enquiry: stored first, emailed second, listed on the operator dashboard.
• Customer GPS fixes were kept forever. location_retention_days existed as a setting with no code behind it. The daily job now deletes fixes past their venue's window, defaulting to 30 days where none is set.
• Staff ratings were counted as Google review activity. They now record their own surface and never route to Google.

10 What runs on its own

Two scheduled jobs, one polling loop, and one thing that cleans up by chance. That is the entire list of automation — everything else only happens because a person clicked something.

11 The money

What we charge, what it costs us, where it is recorded, and the places the numbers currently disagree with each other.

The model in one line

Hardware is the wedge; the subscription is the business. Plaques sell from a published price list plus a flat install — deliberately low friction, because the point of the plaque is to get the subscription signed. Prices are no longer derived from landed cost, so a supplier price change moves our margin rather than silently moving the customer's quote.

What has actually been spent, and on what

Four supplier orders, 505 units, A$1,475.66 — a blended landed cost of $2.92 a unit. Revenue to date is $0, so the current net position is −$1,475.66.

Shipping is 29% of everything spent. Freight, not unit price, is the lever worth negotiating. Orders 1 and 2 are still USD estimates converted at 1.43117 — the sheet's own yellow cells flag them. Until they are replaced with the actual AUD charged, every cost, margin and breakeven figure carries a small FX error.

The accounting chain

1. One Google Sheet is the book of record.

   "Nudge Tags Accounting", in Drive › Nudge Tags › Accounting. Three tabs: Expenses (one row per supplier order, split into goods / shipping / tax / fees), Income (one row per sale), Inventory (each product's landed cost per unit and how many were bought). Receipts sit alongside it as PDFs.

2. A small Apps Script hands the sheet over as data.

   Guarded by a shared token. It is also what receives a closed sale from the quote builder and writes it into the Income tab.

3. The dashboard reads it live.

   app.nudgetags.com/finances, superadmin only, refreshing every 60 seconds. Five sub-tabs — Overview, Revenue, Expenses, Units & Inventory, Ledgers — and five time ranges recomputed in the browser, so switching range never disagrees with the server.

4. Nothing is ever written back except a closed sale.

   If a number is wrong on screen, the fix is always in the sheet.

Two quote tools — and which to use

Where the documents disagree about money

These are live contradictions between things a customer could be handed. They are ranked by how much trouble they could cause.

12 The physical product

Exact specification, the colour codes, and the pipeline that turns a Python script into something a factory can quote.

How a plaque gets made

1. Draw it

   Python scripts in nudge-tags/brand/ emit the artwork as SVG with all type converted to outlines, so the files open correctly anywhere without the font. make_plaques_all.py for round, make_square_reviews.py for square.

2. Export to print resolution

   sips -s format png -Z 2126. Never qlmanage — Quick Look pads and crops non-square artwork into a square thumbnail and silently wrecks the drawing. The round master is 600 dpi at Ø90 mm; the square is 540 dpi at 100 mm.

3. Copy into Drive

   Renders › "Circles — General (not reviews)" and "Squares — Review Plaques". Drive is the source of truth, not the repo — a stale local duplicate once shipped an old square design to the live website for hours before anyone noticed.

4. Regenerate the spec sheet

   A landscape technical drawing with top, side and back views, every dimension, the adhesive area, the chip keep-out and five manufacturing notes. This is the PDF that goes to a factory with an RFQ.

5. Rebuild the website textures

   python3 website/build_assets.py reads the print PNGs from Drive and flattens them into the textures the 3D showroom uses — then bump ART_VERSION in two files by hand or browsers keep serving the old print for up to a year.

6. Order, write, lock, install

   Factory produces; each chip is written with the NFC Tools app and locked; plaque goes on with 3M VHB.

Chips and suppliers

13 The commercial layer

The partnership, the contract, how we sell, and who we are selling against.

The partnership, as it stands on paper

The customer Service Agreement

Seventeen numbered clauses. The canonical copy is in Drive › Nudge Tags › Sales; it is generated by a script, so the way to change it is to edit the generator and re-render, never to hand-edit the document.

How we sell

The competitor: Quick Suite

Around 200 clients across AU, US, CA and NZ, month-to-month with no contracts, built solo by its owner. Broader software than ours — review replies, SEO blogs, social posts and a chat assistant, all branded as named AI characters — and a genuinely strong proof asset in a live client dashboard showing a café going from 28 to 674 reviews. Their hardware is included in the subscription, generic, and the client keeps it on cancellation. They do not do NFC menus.

The honest read from our own dossier: their hardware is worse than ours and their software is deeper than ours. Their exposed flank is compliance — they are actively expanding a "not happy? tell us" route and they generate review text for customers to paste into Google, both of which breach Google's policy and endanger the client's listing, not just theirs. That attack line only works while our own thresholds stay at 1, which is why the threshold question above is a positioning decision rather than a settings detail.

Two notes for the record: the intel came from a call where Leon posed as a buyer for his father's restaurant; and their claim that "47% of people in Queensland use AI to find local businesses" is unverified and probably invented — do not repeat it. Their actual pricing is still unknown, and getting hold of their two emailed proposals remains the single highest-value open item for setting our own price.

14 Playbooks

The dozen things that actually get done, written so either of you can do them without asking the other.

Onboard a new venue, from signed deal to live plaque

1. Sign the agreement

   Fill in the customer block and the fee schedule in clause 4.2 — branding choice, plaque count, setup fee, rate per plaque, monthly total, start date. Tick the 6 or 12 month term. Both founders sign as Co-Founder. Send as PDF, not .docx: the brand font is not embedded.

2. Create their account

   app.nudgetags.com/admin → business name, owner's name, owner's email. You get a setup link that is valid 7 days and shown exactly once. Copy it before leaving the page — there is no resend button, and with email switched off there is no self-service recovery either.

3. Send them the link

   They set their own password and land on onboarding: venue name, Google review link, threshold. Leave the threshold at 1 — everyone goes to Google.

4. Set the venue up properly

   Paste the Google Maps link in Settings (this is the one that costs a lookup and gives you the address, photo and rating tracking). Set the venue's timezone if it isn't Brisbane. Add the menu link if they're running menus.

5. Create a placement per physical object

   Reviews tab → Placements. One per plaque, one per table, one per staff member. Each gets its own ?c= code, and that code is the only reason "which table actually gets used" is answerable.

6. Write and lock the chips

   NFC Tools app, one URL per plaque, matching that placement's link exactly. Lock every chip before it leaves your hands — an unlocked tag can be rewritten by any customer with a phone, and a locked wrong URL means physically replacing the plaque.

7. Install and test on site

   3M VHB, never on metal. Then tap each plaque with a real phone and confirm it opens the right page — not the right venue, the right placement.

8. Log the sale

   app.nudgetags.com/quote → build the order → log the close. It writes one Income row per product line and stock-on-hand follows automatically.

9. Invoice

   Manually, for now — Stripe cannot take a card yet. Set a reminder for the recurring charge, because nothing in the system will do it for you.

Ship a change

cd ~/Documents/claude/nudge-tags/nudge-reviews
npm run typecheck
vercel deploy --prod --yes \
  --scope purple-pi-marketing

cd ~/Documents/claude/nudge-tags/website
vercel --prod

cd ~/Documents/claude/nudge-tags/quote
vercel --prod

Change the database

1. Write a new numbered migration file

   In db/migrations/. Use ADD COLUMN IF NOT EXISTS / CREATE TABLE IF NOT EXISTS — every file is re-run on every migration, so it has to be safe to repeat. Never put a bare UPDATE in one; one existing migration does that and it silently re-grants access every time it runs.

2. Update db/schema.sql too

   It is what a fresh database is built from. It is currently missing two tables that live only in migrations — don't add a third.

3. Run it against production, by hand

   cd ~/Documents/claude/nudge-tags/nudge-reviews
   DATABASE_URL="<pooler string>" npm run db:migrate

   Nothing runs this automatically. Deploy the code only after the migration has run, or the site crashes for everyone in between.

Rotate a key

Switch email on — the highest-value hour available

1. Create a Resend account and add nudgetags.com as a sending domain.
2. Add the SPF and DKIM records at GoDaddy

   Alongside the existing Google Workspace records, not instead of them. Wait for Resend to show the domain verified.

3. Set RESEND_API_KEY in Vercel and redeploy.

   CRON_SECRET is already set, so the monthly report will not be blocked.

4. Test all four

   A password reset to yourself; leave a 1-star rating on a test venue and check the alert lands; run the report job manually; create a test account and check the welcome email.

5. Then tell customers about it

   Password self-service, feedback alerts and the monthly report all start working at once — and the monthly report is the single best anti-churn asset in the product.

Take the first real payment

1. Activate the Stripe account

   Business verification and bank details. Gauresh only — never hand these to anyone else, and never enter them on someone's behalf.

2. Configure Stripe Tax with an AU registration

   The code requests automatic tax on every checkout. Without this configured, creating a checkout session fails outright.

3. Recreate the product and both prices in live mode

   $149/month and $1,188/year, AUD, recurring, priced per unit so the quantity equals the venue count.

4. Recreate the webhook in live mode

   Pointed at https://app.nudgetags.com/api/stripe/webhook, subscribed to the six subscription and invoice events.

5. Set four variables in Vercel and redeploy

   The secret key, both live price IDs, and the webhook signing secret. Until all four are set the billing page correctly says card payments aren't switched on.

6. Mark your own accounts exempt

   Founder accounts are flagged by a database column and there is no admin screen for it — it needs a one-line SQL update against Supabase. Do this before testing, or you will invoice yourselves.

Monthly finance close

1. Enter every supplier order

   One row per order in the Expenses tab, above the blank row so the sheet's own totals still cover it. Split the cost into goods, shipping, tax and fees — the grey cells are formulas, don't type over them. Category must read exactly Inventory.

2. Replace any FX estimates

   Yellow cells are USD converted at an assumed rate. Replace them with the actual AUD your statement was charged. Orders 1 and 2 are still outstanding.

3. File the receipt

   Drive › Nudge Tags › Accounting › Expenses, named to match the order.

4. Check every sale is on the Income tab

   Sales closed through the quote builder land automatically. Anything invoiced by hand needs a row — with Qty 0 for software-only revenue and a Type containing "subscription", or the unit economics skew.

5. Add any new product to the Inventory tab

   Product, type, description, supplier, landed cost per unit, units bought. The product name has to match what the quote builder sells, because that name is what links stock to sales.

6. Read the dashboard

   /finances → Overview for net position and cash recovered, Units & Inventory for stock on hand and the stock-out horizon, Expenses to see whether freight is still 29% of spend.

Something is broken — triage in order

1. Can you load a plaque link?

   app.nudgetags.com/r/<a real slug>. If yes, customers are fine and this is not an emergency.

2. Check the operator console

   /admin shows the last 25 crashes with the path and the affected user, plus a 24-hour count. Start here before guessing.

3. Marketing site fine but nobody can log in?

   That is the specific signature of a broken AUTH_SECRET.

4. Everything slow?

   Check Supabase is up and that the Vercel functions are still pinned to syd1. Cross-Pacific queries once made the whole product feel broken.

5. Dashboard fine, finance page dead?

   The Apps Script deployment URL or the token has changed. Both halves of the token have to match.

6. Check Vercel's own logs

   Deployment logs for build failures, function logs for runtime errors, cron logs to see whether the scheduled jobs actually ran.

Give Leon access

Today he has none of the operator surfaces. To change that: he needs a user account in the product, and his email added to SUPERADMIN_EMAILS in Vercel, followed by a redeploy. Be deliberate — that one variable grants the operator console over every customer account, the real revenue figures and the ability to permanently delete a venue. There is currently no way to grant the finance dashboard alone; if that separation matters, it has to be built. He will also need: the Vercel team, the Supabase project, the Drive folder, the GoDaddy login and the Stripe account — none of which he can be given through the product.

When a customer cancels

1. Check the term

   If they are inside a 6 or 12 month minimum, the early-termination fee applies — 50% of remaining fees, or 30% after month six on a 12-month term. Notice is 30 days and does not shorten the minimum term.

2. Do not delete anything

   Set the venue to paused. Deleting erases every tap, rating and complaint permanently and cannot be undone. Pausing keeps the plaques valid if they come back.

3. Recover the plaques

   Nudge-branded plaques are our property and are due back within 14 days, or invoiceable at replacement cost. Custom-branded plaques stay with the customer.

4. Stop the billing

   Manually, since Stripe isn't live. Once it is, cancelling the subscription flips the account automatically and the links go dark on their own.

15 What has to be revisited, and when

Nothing on this list is urgent today. Everything on it becomes expensive if it is never done.

16 Open items, worst first

Everything found in this audit that a founder would rather know now than discover later. Nothing here is on fire; several things would be, given time.

Do first

Fix this month

Know about it

17 Where everything lives

Which file, which folder, which document. Start here when you can't remember where something is kept.

On the Mac

Everything is under ~/Documents/claude/nudge-tags/. This folder is backed up to Google Drive and is not in version control.

In Google Drive — BUSINESS › Nudge Tags

18 Change log

What changed in this manual, and when. Append a line here every time it is updated — a manual nobody trusts the date on is a manual nobody reads.