← Design system
niṣṭhā

Architecture plan

High level · v317 Nov 2026

Stamp loop built, tested end to end on Square's sandbox Every payment confirmed with Square before it counts Attack-tested First real-till pilot: next Square OAuth for cafes: next Not live with real customers yet

The journey

How a stamp reaches a phone

The cafe rings a sale as it always does. Square tells us about it, we check with Square that it is real, and the stamp appears on the card. Slide through the eight steps, or let it play.

How a stamp works?

One sale · one stamp · never counted twice

CustomerPhone card Cafe tillSquare checkout PaymentsSquare Front doorCloudflare Our serverniṣṭhā serverRender Our ledgerPostgres (Neon) card scanned sale paid signed event . "is it real?" one locked write card page shows the new stamp 1 2 3 4 5 6 7 8 team alerts

  1. The customer shows the card on their phone. Staff scan it inside Square's own checkout, so there is no second screen.
  2. The sale is paid as usual. Square records it with the customer attached.
  3. Square sends us a signed message about the sale. It arrives through Cloudflare.
  4. The server checks the signature, answers Square at once, and carries on in the background.
  5. It asks Square directly whether that payment is real and completed, using the cafe's own permission.
  6. The stamp, or the reward, is written to the ledger in one locked step, once, however many times the message arrives.
  7. Anything odd, such as a reward used with none in hand, is flagged for the team instead of being guessed at.
  8. The card page reads the ledger and shows the new stamp.

A stamp only exists because Square confirmed a real, completed payment. Nothing on the customer's side can create one.

The parts

Four parts, four jobs

Each part does one thing and hands over cleanly to the next.

Cloudflare

One front door

Pages are served from the edge, so the site is quick and never sleeps. Every call for data passes through the same door to the server, with protection in front of it.

Postgres · Neon

A ledger that is only ever added to

Every stamp, reward and refund is a new line. History is never edited, so any total can be checked against the lines that made it.

Square

Confirm, then count

A message about a payment is only a message. Before anything is counted, we ask Square about that payment ourselves. A made-up one has nothing to find.

Safety

Guarded from the inside out

Signed messages in, careful writes to the ledger, secrets sealed, every team change on record, and a standing set of attack checks that runs against a throw-away copy.

The stack

What runs where

One front door, one server, one database. Square stays the only system of record for who the customer is and what was paid.

PartWhat it doesWhere it stands
Pages and proxyServes every page, and passes calls for data on to the server. Cloudflare.built
ServerCafe sign-up and design, customer cards, the team dashboard, and the Square webhook. Render.built paid always-on tier before the pilot
DatabaseCafes, customers and the ledger. Postgres on Neon.built backups plan before the pilot
SquareCustomers, orders and payments. We confirm each one with Square before it counts.tested end to end on sandbox
EmailSign-up codes and messages to cafes, and replies back to the team.built
Wallet passesThe card in Apple Wallet and Google Wallet.code built, accounts to set up
Square sign-in for cafesA cafe approves niṣṭhā once, instead of handing over a key.next
Alerts viewOdd events and team changes shown in the dashboard, not only through the API.planned

Settled

Decisions that shape everything

These are made. The rest of the plan assumes them.

Where stamps come from

Only from a confirmed payment

Stamps come from Square's own record of a completed sale, never from a button a person can press.

Why: it makes fraud at the till hard, and it keeps the cafe's behaviour unchanged.

Who holds the points

We keep our own ledger

No Square Loyalty subscription is needed. The ledger lives in our database.

Why: a cafe pays us, not us plus Square's loyalty fee. Customers still choose us over Square's own programme on price and simplicity.

Who owns identity and money

Square does

Customers and payments live in Square. Our database holds only the card, the stamps and the audit trail.

Why: we never hold card details, and a cafe can leave at any time with its data intact in Square.

The customer

No login to collect stamps

The card code on the phone is all it takes. An account is optional, for history and offers.

Why: a login would break the promise of nothing to install and nothing to remember.

Rollout

Four phases

01

Prove it works against real Square

  • The full loop runs against Square's sandbox: sale, stamp, reward, a reward used on a sale, a completely free sale, a refund, and the customer's own screens.
  • A message about a payment is checked with Square before it counts.
  • Hosting, database and email are in place.

Gate: a stamp lands on a phone because a real Square transaction completed, not because a button was clicked.

02

Safe to put in front of a cafe

  • Careful writes to the ledger, sealed secrets, rate limits, an audit trail and a repeatable attack test.
  • Square sign-in for cafes, replacing pasted keys.
  • Paid always-on hosting and a database backup plan.
  • Privacy policy and consent wording, reviewed by a solicitor.
  • Error tracking and uptime alerts.

Gate: you would be comfortable if a stranger's phone number were in the database tonight.

03

One pilot cafe

  • A real till on real Square, with real customers in the queue.
  • Watch for staff skipping the scan in a rush. It is the risk most likely to happen.

Gate: a month of real use where regulars trust their stamp count.

04

Make it sellable

  • Pricing informed by the pilot, not guessed.
  • Rewards by item or by amount spent, set per cafe.
  • Several locations under one owner.
  • The alerts view in the dashboard, and a nightly check that totals still match the ledger.
  • Wallet passes live in Apple and Google, and gift cards on the same card.

Immediate next steps

In order

  1. Build Square sign-in for cafes, so a cafe approves niṣṭhā once and no key is ever pasted in.build
  2. Move the server and database to paid tiers that stay awake and keep backups.you
  3. Create the production Square application and webhook subscription, including the order-completed event.you
  4. Run the first real-till test with one cafe, including a free redemption.buildyou
  5. Have the privacy and consent wording reviewed before real customers sign up.you

Layer by layer

What the program is made of

Think of a restaurant. The dining room is what guests see, the kitchen does the cooking, the pantry and the specialists behind the kitchen supply it, and the suppliers outside deliver the ingredients. niṣṭhā has the same four layers, and every request goes through them in the same order.

1 · What people see: pages in the browser 2 · The server: one program answers every request 3 · Helpers the server calls on 4 · Outside the program: where things live Join pagescan, name, card Card pagebarcode, stamps Account pagehistory, offers Owner pagesdesign, progress Team dashboardcafes, alerts the gate: who may call · size and shape of input · speed limits Join and cardssign up, card, wallet Cafe sign-updesign, review, live Team toolsmanage, export, flags Square messagesthe webhook door Contact and mailmessages in and out LoginsSquare talkerStamp engineEmail senderPlansWallet passes Postgres: our ledgerSquareEmail servicesApple and Google Wallet

Everything funnels through the gate. Nothing in layer 2 can be reached without first passing the same safety checks, and nothing in layer 1 ever talks to layer 4 directly.

Explore a part

Six jobs, in plain English

Pick a part. Each one says what it does, walks through it step by step, and explains why it is built that way.

Join and card

Layer 2 · Join and cards

Getting a card takes seconds: scan the cafe's QR code, type a name, and the card appears on the phone.

Think of

A coat-check ticket. The ticket number is the secret; the label on the coat peg is only a convenience for staff.

Step by step

  1. The QR code opens the cafe's join page. It only works once the team has taken that cafe live.
  2. The page sends the name (and, if the customer wants an account, an email and password) to the server.
  3. The server checks the request is sensible and not part of a flood, then creates the customer in the cafe's own Square account, with the new card code stored as Square's reference.
  4. It takes the next number for that cafe in a single indivisible step, so two people joining at the same moment can never get the same number. That gives a readable ID like CH-0042.
  5. It saves the customer and sends back a link to the card.
  6. The card page loads the card by its code and draws the barcode (or QR) the till will scan.

Why this way

The card code is long and random: it is the secret on the barcode. The readable ID is only a label, so nobody can use it to open or look up a card.

Also true

Guests keep only a name. Accounts are optional and only add history and offers.

In the code

customer sign-up routeids moduleSquare talkercard page

Follow one message

What the stamp engine asks, in order

Every message from Square goes through the same nine questions. Pick something that could happen at a till and watch where it stops.

    Outcome

    Pick a scenario

    The engine asks nine questions. The first one that fails decides what happens.

    Refunds and completely free sales follow shorter, separate paths with their own checks. They are described in the stamp rules above.

    The data

    What we keep, and why

    The whole system stores a handful of kinds of record. Square holds the customer and the money; we hold only what the card needs.

    RecordWhat it holdsWhy it exists
    cafesOne row per cafe: name, look of the card, status, reward rule, link to its Square account.Everything else belongs to a cafe.
    customersCard holders of a cafe: card code, readable ID, stamp and reward counts, optional login.The card, and the running total shown on it.
    transactionsThe ledger: every earn, redeem and reversal, with the Square sale it came from.The history the totals can always be checked against.
    webhook eventsEvery message from Square, with its outcome or the reason it was ignored.Duplicate filter, audit trail and retry queue.
    flagsThings the team should look at. They never change a customer's stamps.Odd events are shown to a person, not guessed at.
    audit trailEvery change made through the team's tools: when, from where, what.Accountability. Never stores what was typed, only that it happened.
    sessionsWho is logged in, as scrambled tickets with an expiry.Keeping people logged in without storing anything reusable.
    messagesThe conversation between the team and each cafe, plus contact-form messages and offers.Setup and support in one thread.

    Principles

    Rules the whole design follows

    One way in

    A single path writes stamps

    There is no back door and no second screen. Stamps come from Square's confirmed sales through one engine, so one place can be checked and tested.

    Ask, do not trust

    Verify with the source

    A message about a payment is only a message. Before anything counts we ask Square about it directly.

    Never rewrite history

    Add lines, never edit them

    Corrections are new lines. The past stays as it was, which is what makes totals trustworthy.

    Fail safe

    When unsure, do nothing and tell someone

    An unexpected situation leaves the customer's stamps alone and raises a flag for the team.

    Small secrets

    Keep as little as possible

    Guests are a name only. Passwords and tickets are stored scrambled. Square keys are sealed in the database.

    Prove it

    Test like an attacker

    A standing set of attack checks and a full run against Square's sandbox exist to be re-run after every change.

    The road a request takes

    Nine gates between a tap and the database

    Every request to niṣṭhā, from a customer's phone to the team's dashboard, travels the same road. Press a gate to see what it does and why it is there.

    Cloudflare's edge

    The first stop is Cloudflare, close to the visitor. It answers every page and image itself from stored copies, so the site is fast and never sleeps. It also absorbs floods of junk traffic before they reach us. Only calls for live data continue on.

    The Square webhook takes a shorter road: it skips the browser-only gates (4 and 8) and instead has its own signature check at the door.

    Explore a service

    Seven services, what each one does

    We rent every part of the infrastructure instead of running machines. Pick a service for what it holds, how it connects to the others, and what happens if it has a bad day.

    Cloudflare

    The front door

    Cloudflare is the first thing every visitor meets. It does four jobs for us at once.

    What it does

    1. Pages: hosts every web page, font and image as static files. There is nothing to run, so it cannot crash or sleep.
    2. Function: a small program that passes data calls to our server (see gate 2).
    3. Protection: absorbs floods of traffic and can block bad visitors before they reach the server.
    4. Headers file: tells browsers how long to keep copies of fonts and images, and adds the safety headers to every page.

    If it has a bad day

    The site is unreachable. There is one front door, which keeps things simple and protected, at the price of depending on it.

    Cost and plan

    The free plan is far above our traffic.

    You control

    protection rulesbot filteringthe shared secret

    Where it runs

    Three places the system lives

    The same code runs in three settings, kept apart so that practising never touches real customers.

    PlaceDatabaseSquareUsed for
    On a laptopThe test database, or nonePretend Square (nothing leaves the machine) or the sandboxBuilding and trying things
    The test setupA separate test databaseSquare's practice copy (sandbox)The unit tests, the attack checks, and the full journey run
    LiveThe real database, in FrankfurtPractice copy today; the real one for the pilotReal cafes and customers

    The attack checks and the journey run refuse to start if they would touch the real database.

    From code to live

    How a change reaches the site

    Nothing is changed by hand on a live machine. A change is written, tested, saved to GitHub, and the services pick it up themselves.

    1 · WRITEA change is madeOn a laptop, in the code.
    →
    2 · TESTThree test runsThe unit tests, the attack checks, and the journey run against Square's practice copy.
    →
    3 · SAVEPushed to GitHubThe saved version is the single source of truth.
    →
    4 · PAGESCloudflare publishes the pagesIt picks up the new files and serves them from the edge within a minute.
    →
    5 · SERVERRender restarts the serverIt installs what the code needs, starts the program, and adds any new database columns.

    A new database column is always added, never removed, so the old and new versions of the server can both run against the same database during a restart.

    When things break

    What happens, and what the customer sees

    Each part is allowed to fail without losing a stamp. This is what we designed for.

    If this happensWhat the system doesWhat a customer notices
    Square is slow or unreachableThe event is kept as failed and retried every few minutes for a day. A stamp is only given after Square confirms the payment.A stamp can appear a few minutes late.
    The server is asleep or restartingThe front door answers with a short "waking up" message and the page tries again.A short wait on the first visit.
    The database cannot be reachedThe server answers with a plain error. Nothing is half-saved.An error message, then it works again.
    Email service is downThe page says it could not send the code and offers to try again.A code arrives later or not at all.
    Square sends the same message ten timesThe duplicate filter and a database rule count it once.Nothing, which is the point.
    Someone floods the siteCloudflare absorbs the worst; speed limits slow the rest.Nothing, or a polite "slow down" for the flooder.
    A secret key leaksThe key is replaced in the service's settings. Square tokens are stored sealed, so a copy of the database alone is not enough.Nothing, if caught quickly.
    Cloudflare has an outageThe site is unreachable until it recovers. This is the accepted cost of one front door.The site will not load.