Ryguasu
Ryguasu ("hen" in Guaraní) is an inventory, sales, and cash register system for the small retail of Paraguay: the minimarket, the corner store, the neighborhood butcher shop. Every business shares one backend and one database, and that forces you to take isolation seriously. On this page I don't list features: I answer the questions I'd ask a system that keeps other people's money.
I designed the data model and the architecture, wrote the backend, the isolation between businesses and the encrypted backups, and I take care of the deploys and of checking that production stays healthy. The frontend and the visual design are my teammates' work, built on my API contracts.
00First, the product
A minimarket here keeps its inventory on paper or in a spreadsheet: nobody knows what the goods on the shelf really cost, prices move with the dollar, and the till leaves no history anyone can check. Ryguasu is a subscription per branch with a 14-day trial: the business loads its products — factory barcodes, internal codes or scale PLUs — and sells from a web POS that can take losing the internet.
The backend does the boring, hard part: it recalculates the weighted average cost on every purchase, freezes price, cost and name into every sale line, and handles Guaraní as base with ARS/USD/BRL at each business's own rate. The demo tenant carries 4,551 sales over 183 days, squared against its own reports.
Seven ways to break it
A system like this isn't judged by the days when everything runs fine. I built these cards around the uncomfortable questions — the ones an interviewer would ask me, or reality would — and each one answers with the threat, the defense that exists today and how it was tested. The mistakes along the way are told too, exactly as they happened.
What if one business queries another's data?
A bug in a query, or a nightly job that forgot its tenant, returns the inventory and sales of every business. With a shared schema this accident gives no warning: everything works, until a customer sees data that isn't theirs.
Two independent layers: the application resolves the tenant on every request, and underneath, PostgreSQL Row Level Security with FORCE policies and a role without BYPASSRLS. Without context, the database returns zero rows — never someone else's.
What if two tills sell the last unit at the same time?
Two sales read stock = 1 at the same time, both go through, stock lands at −1 and afterwards nobody knows the true average cost.
SELECT … FOR UPDATE on product and balance, always in the same order — concurrent sales serialize without deadlocks. Every money or stock mutation demands an Idempotency-Key.
What if the internet drops mid-shift?
The till stops selling — or worse: it sells, and those sales get lost before reaching the server. And here internet and power cuts just happen; they're not a textbook scenario.
Offline-first POS with a local outbox: sales queue up and sync when the connection comes back. Each device carries a JWT license signed by the backend with its tenant and a grace window based on subscription state — identity comes from the signature, never from client input.
What if the dollar moves after the sale?
If history gets recalculated with the new rate or the new price, old margins and reports stop adding up. And a client with bad intentions could send its own total.
The client sends only productId and quantity. The server computes and freezes per line the price, cost, name and exchange rate at the instant of the sale, in numeric(19,4) — never floating point. Changing a price today never rewrites the past.
What if it boots with default secrets?
A rushed deploy with example credentials: the system starts, works, and sits open to anyone who has read the repository.
A startup guard aborts the boot on default or missing secrets — before the migrations can run. It came out of an independent security audit: 7 findings, each proven by executing the attack, each closed. On top of that: gitleaks over the full history on every push.
What if the server dies tonight?
Losing days of sales from dozens of businesses. I work with an old rule of the trade: a backup that wasn't tested is not a backup. Getting to a real one took me four iterations, and they're documented.
Nightly job: dump → compression → age encryption with a public key (the private one never touches the server) → R2, with checksums recorded in the database. The dump completes or screams: it never ends up silently filtered.
What if the backup never ran — and nobody noticed?
The scariest case isn't the backup failing: it's the backup quietly not running and nobody finding out. The machine died before reporting, and the "daily backup" hasn't existed for three weeks.
Dead man's switch (Healthchecks.io): the job pings when it ends well and when it ends badly — and the absence of a ping is the alarm. The "died before reporting" case is covered by design.
Why those defenses exist
None of the above came out of one inspired night. It came out of working with written specs, decisions recorded with their why, and one fixed rule: nothing reaches production without a human approving it.
- Spec-driven development · 35 specsI work with SDD: every part of the system is specified before it's coded, and those 35 specs are the source of truth. The written API rules — an endpoint that deviates updates the contract in the same commit. If two specs contradict each other, I escalate it; I don't resolve it silently on my own.
- 49 decisions with their whyADR-style records: date, status, reasoning, and what supersedes them if they change. Research before code: bonus units ("12+1") were settled by reading IAS 2 — zero code changed, one document written.
- CI saw what my machine didn'tGitHub Actions runs the tests with Testcontainers against a real Postgres. The Linux runners caught a timestamp-precision bug that never reproduced on macOS — it would have blown up only in production. Going over the rest of the code turned up 4 more cases of the same problem.
- Human in the loopThe project is developed with AI assistance, under one condition that isn't negotiable: no push, merge or deploy goes out without my confirmation. The whole infrastructure costs about 50 dollars a month.
What's done, what's written, what's missing
I prefer to separate what already runs in production from what's specified and not yet migrated. Mixing the two would be selling you something that doesn't exist.
- · RLS on 25 tables · 42/42 adversarial
- · Idempotency and locks under a real race
- · Encrypted backups + restore drill 25/25
- · Offline sync with signed licenses
- · Multi-currency with frozen rates
- · Manual subscription payments (Phase 9)
- · Open-registration defense: per-IP rate limit, 30-day trial purge
- · Billing with versioned prices and payment snapshots (DEC-032/033/035/037)
- · Zero Trust over the staff panel — the separate app exists; the deploy behind Access is pending verification
- · Full sale by weight: PLU and scale barcodes (spec 15)
- · A separate staging before touching production with the first paying customer — hard rule, not good intention
- · Public demo with a seeded tenant
- · Access for AI agents via MCP (spec 19)