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.
The journey
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.
One sale · one stamp · never counted twice
A stamp only exists because Square confirmed a real, completed payment. Nothing on the customer's side can create one.
The parts
Each part does one thing and hands over cleanly to the next.
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.
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.
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.
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
One front door, one server, one database. Square stays the only system of record for who the customer is and what was paid.
| Part | What it does | Where it stands |
|---|---|---|
| Pages and proxy | Serves every page, and passes calls for data on to the server. Cloudflare. | built |
| Server | Cafe sign-up and design, customer cards, the team dashboard, and the Square webhook. Render. | built paid always-on tier before the pilot |
| Database | Cafes, customers and the ledger. Postgres on Neon. | built backups plan before the pilot |
| Square | Customers, orders and payments. We confirm each one with Square before it counts. | tested end to end on sandbox |
| Sign-up codes and messages to cafes, and replies back to the team. | built | |
| Wallet passes | The card in Apple Wallet and Google Wallet. | code built, accounts to set up |
| Square sign-in for cafes | A cafe approves niṣṭhā once, instead of handing over a key. | next |
| Alerts view | Odd events and team changes shown in the dashboard, not only through the API. | planned |
Settled
These are made. The rest of the plan assumes them.
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.
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.
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 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
Gate: a stamp lands on a phone because a real Square transaction completed, not because a button was clicked.
Gate: you would be comfortable if a stranger's phone number were in the database tonight.
Gate: a month of real use where regulars trust their stamp count.
Immediate next steps
Layer by layer
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.
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
Pick a part. Each one says what it does, walks through it step by step, and explains why it is built that way.
Getting a card takes seconds: scan the cafe's QR code, type a name, and the card appears on the phone.
A coat-check ticket. The ticket number is the secret; the label on the coat peg is only a convenience for staff.
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.
Guests keep only a name. Accounts are optional and only add history and offers.
Every time something happens at the till, Square posts a short message to one address on our server. This door receives it, makes sure it is genuine, and hands it to the stamp engine.
A letterbox with a guard. The guard checks the wax seal on every envelope, writes the letter in a logbook before anything else, and tells the post office "received" straight away so it never waits.
Answering first means Square never times out and resends. The logbook is three things in one: a duplicate filter, a full audit trail, and a retry queue.
Nothing in this door can be reached from a browser. It accepts only Square's signed posts.
The engine turns a confirmed sale into a stamp, and decides when stamps become a reward. The rules are short and strict.
Anything that depends on a person pressing a button can be abused, so stamps depend only on Square's own record of a completed sale.
A sale that the reward covers completely has no payment, so Square sends an order-completed message instead. That message can only spend a reward, never give a stamp.
Every stamp, reward and refund is written as a new line in a ledger. Lines are never edited or removed, so any total can be checked against the lines that made it.
A paper till roll. You can add a line or print a correction, but you cannot rub out what was printed.
Without the lock, two messages could read the same total and one stamp would be lost. Without the unique rule, a repeated message could count twice.
Their name, email and card are wiped, but the numbers stay so the cafe's history still adds up. Nobody can be identified from what is left.
There are three kinds of "who are you?", and each is kept apart so one can never act as another.
The barcode on a card is shown at the till and could be photographed. So seeing or erasing someone's data needs their login, not just their barcode.
The login ticket cannot be read by page scripts, is not sent from other websites, and is marked secure on the live site.
The team runs every cafe from one private page: onboarding, live cafes, messages, and the numbers.
One place keeps the team's work consistent, and everything it changes leaves a line in the audit trail, so "who changed this?" always has an answer.
The page only ever shows text as text. A customer typing something clever into their name cannot make it run.
Follow one message
Every message from Square goes through the same nine questions. Pick something that could happen at a till and watch where it stops.
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
The whole system stores a handful of kinds of record. Square holds the customer and the money; we hold only what the card needs.
| Record | What it holds | Why it exists |
|---|---|---|
| cafes | One row per cafe: name, look of the card, status, reward rule, link to its Square account. | Everything else belongs to a cafe. |
| customers | Card holders of a cafe: card code, readable ID, stamp and reward counts, optional login. | The card, and the running total shown on it. |
| transactions | The ledger: every earn, redeem and reversal, with the Square sale it came from. | The history the totals can always be checked against. |
| webhook events | Every message from Square, with its outcome or the reason it was ignored. | Duplicate filter, audit trail and retry queue. |
| flags | Things the team should look at. They never change a customer's stamps. | Odd events are shown to a person, not guessed at. |
| audit trail | Every change made through the team's tools: when, from where, what. | Accountability. Never stores what was typed, only that it happened. |
| sessions | Who is logged in, as scrambled tickets with an expiry. | Keeping people logged in without storing anything reusable. |
| messages | The conversation between the team and each cafe, plus contact-form messages and offers. | Setup and support in one thread. |
Principles
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.
A message about a payment is only a message. Before anything counts we ask Square about it directly.
Corrections are new lines. The past stays as it was, which is what makes totals trustworthy.
An unexpected situation leaves the customer's stamps alone and raises a flag for the team.
Guests are a name only. Passwords and tickets are stored scrambled. Square keys are sealed in the database.
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
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.
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
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 is the first thing every visitor meets. It does four jobs for us at once.
The site is unreachable. There is one front door, which keeps things simple and protected, at the price of depending on it.
The free plan is far above our traffic.
Render runs our one program, the server that answers every data call. It is a rented computer that someone else keeps patched and running.
Data calls fail while pages still load. On the free plan it sleeps when unused, so the first visit after a quiet spell is slow. A paid always-on plan before the first cafe fixes that.
Free today. Paid before the pilot.
Neon holds our Postgres database: the cafes, the customers and the ledger. It is the only place anything is permanently stored.
The server cannot save or read stamps. It answers with a plain error and nothing is half-written, because each stamp is saved as a single all-or-nothing step.
Free today. A paid plan adds point-in-time restore, which is how we would rewind after a mistake.
Square owns who the customer is and what they paid. We borrow its facts, and keep none of its money.
Messages arrive late or our check cannot reach Square. Events are marked failed and retried every few minutes for a day, so no stamp is lost.
A cafe only needs its normal Square account: no loyalty subscription.
Two services: one sends mail out, one catches the replies.
Sign-up codes do not arrive. The page tells the person to try again in a moment, and nothing else breaks.
Free tiers cover our volume.
A customer can add their card to Apple Wallet or Google Wallet so it is one tap away at the till.
The code is built and tested. The Apple and Google accounts and their keys still need to be set up before the buttons turn on.
The buttons say "coming soon" and the card still works in the browser.
The domain is the address people type. Three parties each have a small role.
If the registration lapses or the records are wrong, the site and our email both disappear at once. Renewal dates and the registrar login belong in the admin's secure notes.
Where it runs
The same code runs in three settings, kept apart so that practising never touches real customers.
| Place | Database | Square | Used for |
|---|---|---|---|
| On a laptop | The test database, or none | Pretend Square (nothing leaves the machine) or the sandbox | Building and trying things |
| The test setup | A separate test database | Square's practice copy (sandbox) | The unit tests, the attack checks, and the full journey run |
| Live | The real database, in Frankfurt | Practice copy today; the real one for the pilot | Real cafes and customers |
The attack checks and the journey run refuse to start if they would touch the real database.
From code to live
Nothing is changed by hand on a live machine. A change is written, tested, saved to GitHub, and the services pick it up themselves.
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
Each part is allowed to fail without losing a stamp. This is what we designed for.
| If this happens | What the system does | What a customer notices |
|---|---|---|
| Square is slow or unreachable | The 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 restarting | The 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 reached | The server answers with a plain error. Nothing is half-saved. | An error message, then it works again. |
| Email service is down | The 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 times | The duplicate filter and a database rule count it once. | Nothing, which is the point. |
| Someone floods the site | Cloudflare absorbs the worst; speed limits slow the rest. | Nothing, or a polite "slow down" for the flooder. |
| A secret key leaks | The 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 outage | The site is unreachable until it recovers. This is the accepted cost of one front door. | The site will not load. |