DEV Community: Lith SEO

Point your AI assistant at your invoices — we shipped an MCP server

Lith SEO — Fri, 09 Oct 2026 00:21:06 +0000

FoxyInvoice now speaks MCP — the Model Context Protocol. Connect Claude
Desktop, Claude Code, VS Code, or Cursor to your workspace and ask it to
invoice a client in plain English:

"Invoice Globex for 10 hours of consulting at $150/hour, due in 30 days."

→ Created INV-2026-0007 for $1,608.75 ($1,500 + $108.75 CA tax), due
November 7. It's a draft — want me to send it?

Every number in that sentence came from the server, not the model. That's the
design constraint this post hangs off. Here's the whole thing: how auth works
when the client is a robot, why the tools are thin wrappers over the REST
handlers, and the one trick that makes agent retries harmless.

Try it on a real workspace: FoxyInvoice is free to start — create one at foxyinvoice.com/login and redeem founding code U8B4Z8S87X on the Upgrade page for 6 months of Pro, free, no card. Then Settings → AI assistants → Generate token, and ask Claude to invoice someone.

What shipped

A JSON-RPC endpoint at /api/v1/mcp speaking MCP's Streamable HTTP transport,
exposing seven tools:

Tool	What it does
`list_clients`	Search clients by name or email
`create_client`	Create a client
`list_products`	List the catalog
`list_invoices`	List invoices, filter by status/client
`get_invoice`	One invoice, all lines, computed totals
`create_invoice`	Create a draft invoice
`send_invoice`	Email a draft to its client

Auth: a robot is not a browser session

The SPA authenticates with short-lived JWTs behind httpOnly cookies. Right for
a browser, wrong for an assistant you configure once — a token that dies every
15 minutes breaks every MCP client config on earth. But a long-lived
credential needs a story for "how do I make it stop".

The answer is personal access tokens — the same shape GitHub chose:

Generated in Settings → AI assistants, shown once, stored only as a SHA-256 hash. The database can't leak what it doesn't have.
Presented as Authorization: Bearer foxy_… on every call. No cookies, no handshake state — the server is stateless, so any HTTP client that can POST JSON can drive it.
Revocable in one click, checked on every request.
A token acts as its user — live. There's no permissions snapshot in the token. Every request re-resolves the user's current roles from the database, so disabling a user or changing their roles takes effect on the very next tool call. Nothing to propagate, no cache to invalidate, no "I removed them and their integration still worked" bug class.

JWTs are deliberately not accepted at the MCP endpoint — a short-lived
browser credential pasted into an assistant config would be a support ticket
factory.

Tools are thin, the core is shared

The tempting way to build this is a parallel implementation: tool handlers
that re-do the queries the REST handlers already do. The correct way is to
make the REST handlers thin and share what's underneath. We extracted the
bodies of the client, product, invoice, and send handlers into *_core
functions that take the authenticated user and the request — both surfaces
call them:

REST handler  ─┐
               ├─► clients::create_core(state, auth, body)
MCP tool call ─┘

Which means everything the REST API guarantees, the tools inherit for free,
because it is literally the same code:

Permission checks — a token can never do more than its user can.
Tenant scoping — every query filters by the token's tenant; cross-tenant probing returns not-found, not data.
Server-owned money math — the agent passes qty and unitPrice and nothing else. The server assigns the INV-YYYY-NNNN number, computes per-line tax from the client's jurisdiction and the tenant's nexus rules, rounds per the invoice rules, writes the audit trail. The model never states an amount, because a confidently wrong total on an invoice is not a bug, it's a liability.
Quotas — send_invoice counts against the same monthly send limit as the UI.

Sending is a separate tool, on purpose

A draft costs nothing. An email is irreversible. So creating and sending are
different tools with different names, and create_invoice always produces a
Draft — there is no "send too" parameter. The send tool's description tells
the agent to confirm with the user first.

Is a tool description binding? No. But models follow it remarkably well, and
the real backstop is structural: an agent has to make a second, deliberate,
differently-named call to reach a human being's inbox. Accidents need two
mistakes instead of one.

The retry problem, solved with an idempotency key

Agents retry. A dropped connection mid-create_invoice means the model will
try again — and without protection, "invoice the client" becomes two
invoices.

So create_invoice accepts an optional requestId (any UUID the agent picks
and reuses across retries of the same logical create). The server stores it
as the invoice's client-supplied id; a replay with the same requestId
returns the existing invoice instead of inserting a duplicate. First call
creates, retry returns what the first call created.

This is the same mechanism the offline-first SPA already uses — when you
create a client on a plane and it syncs later, a retried sync can't duplicate
it either. One idea, two surfaces.

Errors an agent can act on

MCP separates protocol errors from tool errors, and we lean on that: business
failures — client not found, validation failed, quota exhausted, no
permission — come back as successful tool calls with isError: true and a
plain-language message. The model reads "Client has no email address — cannot
send invoice", tells the user, and offers to fix it. Only genuine protocol
garbage is a JSON-RPC error. The difference is an assistant that recovers by
itself versus one that says "an error occurred".

The protocol, honestly assessed

MCP is young and moving fast, and we took a position: implement the spec's
Streamable HTTP transport statelessly and skip the rest. No session ids, no
server-initiated SSE streams, no stdio. What that buys:

The endpoint is documented in one page — initialize negotiation, tools/list, tools/call, and a 401 when the bearer is missing.
Statelessness composes with idempotency: any request can die and be retried, because there is no session to lose.
Server-side, it's one axum handler in the Rust API — the same codebase weight class as any other endpoint, not a subsystem.

We'll track the spec as it settles. The stateless subset is the part every
client already agrees on.

Try it

If you have a workspace: Settings → AI assistants → Generate token, paste
the one-liner into Claude Code (or the JSON into Claude Desktop), and ask
your assistant to invoice someone.

Full reference (every tool, token lifecycle, wire format):
foxyinvoice.com/docs/mcp
· this post lives at
foxyinvoice.com/blog/mcp-ai-invoices

FoxyInvoice is a live product — free invoicing for freelancers and small
businesses, built by SEOlith. This post is part of
a series documenting the whole build.

Building FoxyInvoice — Appendix: Glossary & Checklists

Lith SEO — Sat, 26 Sep 2026 13:53:23 +0000

This series is written in the open, from a real production system. This closing reference page collects every term the series used and the two checklists that turn it into a launch. [All chapters and diagrams live in the public repo.]

Glossary — every term this series used

Git & process

Repository (repo) — the project plus its full history.
Commit — one versioned snapshot with a message.
Branch / merge / rebase — parallel lines of work / combining them / replaying yours on top.
Worktree — a second checkout of the same repo, for working two branches at once (source of a war story).
Tag — a named point in history (blog-v1.0).
CI/CD — automation that tests (CI) and deploys (CD) on push.
Concurrency group — pipeline lock ensuring one deploy at a time.

Frontend

SPA — single-page app; the server ships a shell, JavaScript renders pages.
PWA — progressive web app; installable, offline shell via service worker.
UI vs UX — what's on the screen vs whether the person succeeds.
Progressive disclosure — show only what's needed now; hide the rest behind "Advanced."
Route input binding — URL parameters delivered as component inputs (timing matters — Story 1).
Signals — reactive values the UI tracks automatically.
SSR / prerendering — server renders pages per-request / static HTML generated at build time.

Backend & data

REST / HTTP verbs / status codes — the request vocabulary (GET/POST/PUT/DELETE; 200/201/400/401/404/409/500).
JWT — signed token carrying claims (user, tenant, permissions).
Refresh token — long-lived credential rotated to extend sessions.
ORM (EF Core) — write objects; it writes the SQL.
Query filter — automatic WHERE clause (ours: tenant scoping).
Migration — versioned schema-change script; the only legal writer of schema.
Idempotent — safe to run twice (ADD COLUMN IF NOT EXISTS).
Transaction / outbox pattern — commit business row + email row atomically; a worker delivers.
Value object — a type defined by its values (Money = decimal + currency), equality by content, refuses illegal math.
Nexus — a presence in a US state that triggers sales-tax duties.

Infrastructure

DNS records: A / MX / TXT — name→IP / mail routing / free-form proofs.
TLS / certificate / ACME — encryption; the proof you own the domain; the protocol that issues it (Caddy automates).
Grey-cloud — DNS-only routing (no proxy) — required for direct ACME challenges.
VPS — your rented Linux box.
Docker: image / container / compose / volume / network — blueprint / running instance / stack file / persistent disk / private LAN.
BuildKit secret — credential mounted during build only; never in image layers.
Rate limiting — per-IP request budgets on public endpoints.
X-Robots-Tag / robots.txt allowlist — crawler directives; default-closed indexing.
IndexNow — push protocol telling engines your URLs changed.
llms.txt — markdown menu for AI answer engines.

Product & ops

Multi-tenancy — many businesses, one system, isolated data.
RBAC — roles → permissions → guards.
Share token — unguessable URL as scoped authorization.
Funnel — stranger → visitor → signup → activated → paid.
Marginal cost — cost of one more user (ours: ≈0).
Break-even — subscribers covering fixed costs (ours: 2 Pro).
GEO (generative-engine optimization) — being the machine-readable answer.

The checklists

Server setup (full walkthrough in Chapter 6):

[ ] Domain bought; nameservers → Cloudflare; A record grey-cloud
[ ] VPS up; compose stack: postgres healthy → api healthy → worker running
[ ] Caddy certificates issued; site loads over HTTPS
[ ] SES identity verified; probe email sent & received
[ ] Email routing rules + verified destinations; probe again
[ ] Nightly backups, size-checked, landing off-box
[ ] Secrets generated on-host; repo secret-scan green

Launch (product-level):

[ ] Signup → onboarding → first invoice sent, tested in a clean browser
[ ] Feedback widget round-trip (submit → email → console → resolve)
[ ] Payments sandbox end-to-end (link → webhook → Paid status)
[ ] robots.txt allowlist reviewed; prerendered pages spot-checked with curl
[ ] Search Console + Bing Webmaster verified; sitemap submitted
[ ] Access logs on; one organic crawl observed

— That's the series. Every chapter, diagram, and scar lives in the
repo, versioned in git, ready for whoever builds the next one.

The machine this series documents is live, and reading these words is
the proof it ships. Create a free workspace at
foxyinvoice.com, then redeem founding code
U8B4Z8S87X on the Upgrade page — 6 months of Pro, free, no card. If anything
breaks, there's a feedback button in the app. I read every one.

Building FoxyInvoice — Chapter 13: War stories — six postmortems and what each one cost

Lith SEO — Sat, 26 Sep 2026 13:42:45 +0000

This series is written in the open, from a real production system. This chapter is six real postmortems, each in the same format: symptom, diagnosis, fix, lesson. [All chapters and diagrams live in the public repo.]

Every incident below is real, timestamped in git, and shipped a
permanent change to how we work. The format is the same each time —
symptom, diagnosis, fix, lesson — because the lesson is the only
part worth keeping. Read them as a set and a meta-lesson emerges:
almost every failure was a system telling us a comforting lie.

Story 1: The edit button that created invoices

Symptom. User report: "On clicking Edit invoice button, new
invoice page is opened. Not able to edit invoices." Plus, from the
same user: double-clicking Create produced duplicates.

Diagnosis. Two bugs stacked. (a) The editor read its route
parameter in the constructor — but Angular binds route inputs after
construction, so the id was always null and "Edit" rendered a blank
"New" form; saving minted a fresh invoice. (b) Deeper: the invoice
repository loaded entities without line items — line updates
404'd, and adding a line recomputed totals against an empty set,
silently zeroing an invoice's math. One confused click had uncovered a
data-corruption class.

Fix. An effect() that reacts when the route input binds;
Include(LineItems) at the repository level (also fixed quote
conversion losing its lines); create-success now navigates away so a
second click can't duplicate.

Lesson. Reproduce in a real browser before theorizing — the
visible bug was framing timing, but only reproduction exposed the
corruption underneath. And domain integrity shouldn't depend on every
call site remembering an Include.

Story 2: The hand-edited database (twice)

Symptom. API containers crash-looping at startup on deploy;
logs show column already exists / relation already exists from the
migration engine.

Diagnosis. Schema changes had been applied by hand (psql) on
the production database — once a table, once a column — while the
proper migration for the same change sat in the repo. The migration
collided with the hand-made reality, threw, rolled back, and the
container died at boot. Both times.

Fix. Emergency reconciliation (apply the missing column, record the
migration in the history table), then rewrite the migrations
idempotently (CREATE TABLE IF NOT EXISTS, ADD COLUMN IF NOT EXISTS) so they're safe on every database state. New repo-wide rule,
now in the developer docs: never apply schema changes out-of-band; if
forced, the follow-up migration must tolerate reality.

Lesson. A migration isn't a formality — it's the only writer of
schema. Two writers means one of them is lying to the other.

Story 3: The deploy queue zombie

Symptom. Every deploy sat "pending" forever — while runners were
online and idle. Cancelling and re-running changed nothing.

Diagnosis. The concurrency group that serializes deploys had a
zombie holder: a cancelled run that never released the lock. New
runs were created pending with zero jobs — the job row only appears
once the lock is acquired — so the UI showed an eternal, healthy-
looking queue.

Fix. Renaming the concurrency group sidesteps the zombie entirely
(production-deploy-v2). Diagnosis technique worth stealing: zero
jobs + idle runners = deadlock, not queue. The jobs API tells you
instantly which one you have.

Lesson. "Pending forever" is a distinct failure mode. Know its
signature, because the queue UI is constitutionally incapable of
admitting it.

Story 4: The email that bounced to everyone

Symptom. Feedback notifications bouncing as
MAILER-DAEMON delivery failures — user reports reaching nobody.

Diagnosis. The notification address lived on a domain whose mail
routes pointed at Cloudflare Email Routing — and while the rules
existed, the destination address was unverified. Every bounce
also masked a second gap: notifications had no Reply-To, so any
manual reply would have gone to a dead sender.

Fix. Notifications moved to a verified inbox; Reply-To now
points at the reporter; and any mail-routing change gets a probe
email — config-saved is not delivered. (Also learned to read MX
records before assuming Google hosted everything.)

Lesson. Email infrastructure needs end-to-end tests like every
other infrastructure. A saved rule is a hypothesis; a received probe
is a result.

Story 5: The partial upgrade that broke the build

Symptom. Deploy "succeeded" — backends healthy — but the SPA build
had failed inside it with npm ERESOLVE. New code was live on the
API; the site itself was yesterday's.

Diagnosis. A dependency bot bumped three Angular packages to
22.1.4 while the rest of the family stayed on 22.1.3. Angular's peer
dependencies demand exact-version alignment, so npm install became
unresolvable. Why didn't the deploy fail loudly? It overlapped with
story-3-era pipeline bugs — the failure was surfaced only after the
queue was fixed.

Fix. Align the entire @angular/* family + Material/CDK in one
commit, regenerate the lockfile, and add the rule to the docs: on
any Angular bump, move the whole family together.

Lesson. Ecosystems with strict peer-graphs turn "small" upgrades
into set-theory problems. When a bot proposes a partial set, the set
is the unit of review.

Story 6: The version diamond

Symptom. A telemetry/health-check upgrade crashed the API
containers into a restart loop the moment it deployed.

Diagnosis. Our internal platform packages required MediatR 14; the
app pinned MediatR 12. Both versions in one process resolved to a
runtime MissingMethodException-style explosion — the classic
dependency diamond, invisible at compile time in the right
(disastrous) packaging layout.

Fix. The interim revert is documented (that feature was withdrawn
same-day); the durable fix came later — replacing MediatR entirely
with a tiny MIT-licensed in-process mediator with no version gravity,
and bumping the platform packages as a set. Chapter 03's architecture
now documents the post-migration world.

Lesson. Your dependency graph is architecture. Any package that
everyone transitively requires becomes a load-bearing wall — pick
ones with a migration story, or none at all.

The template (steal this)

The postmortem template, rendered live: SYMPTOM → DIAGNOSIS → FIX → LESSON — the loop that turns each incident into a permanent rule.

Postmortems earn their keep only if the lesson becomes a check, a
doc line, a gate, or an idempotent default — otherwise you're just
collecting scars. Every lesson above now lives in the repo's
developer landmines file, where the next 2 a.m. version of us will
actually read it.

Reading this and want to write your own war stories instead of reading ours? Create a free workspace at
foxyinvoice.com, then redeem founding code
U8B4Z8S87X on the Upgrade page — 6 months of Pro, free, no card. If anything
breaks, there's a feedback button in the app. I read every one.

Next: Appendix A — Glossary & Checklists. The series is complete; the machine keeps running.

Building FoxyInvoice — Chapter 12: Engagement & automation — UI first, then automate

Lith SEO — Sat, 26 Sep 2026 02:48:47 +0000

This series is written in the open, from a real production system. This chapter is the engagement surface: onboarding, progress you don't lose, and gentle machines that act for the user. [All chapters and diagrams live in the public repo.]

"Engagement" conjures dark-pattern streaks and notification spam. It
shouldn't. Engagement is the product working so well that leaving it
half-finished feels like loss — progress the user doesn't want to
abandon, moments of completion worth screenshotting, and gentle machines
that act on the user's behalf. This chapter is the engagement surface
we shipped, in the order it was built, under one governing rule:
build the manual UI first; automate only flows that already proved
themselves by hand.

The onboarding staircase (first five minutes)

A new signup lands on a three-step wizard: name your business + pick
currency → add your first client → "you're ready" (with the founding-
code hint for testers). Each step is one decision, skippable, and
writes real data — so finishing onboarding is having a workspace.
Then the dashboard's get-started checklist walks the rest: first
invoice, first send, first payment link. The metric this staircase
serves is the only one that matters early: time to first sent
invoice. Everything that shortens it is engagement; everything that
lengthens it is churn you built yourself.

Progress you can see (and don't want to lose)

Draft save & resume, twice over. The invoice editor has a "Save draft" that stays on the page (URL swapping to the edit route so a refresh can't duplicate it), plus local autosave with a resume banner — mid-form work survives navigation. The template generator offers the same to anonymous visitors (Chapter 11's slice 1). The psychology is honest: no dark patterns, just don't lose the user's work, and they'll come back to it themselves.
The usage meter as an honest nudge. Free accounts see "4 / 10 invoice actions this month." Not a countdown timer, not a lock — a number, and when it approaches the limit, an upgrade page explains what Pro adds. Conversion pressure that respects the user converts the right users: the ones who grew.

Gentle machines: automation that acts for the user

Reminders. The worker scans daily: a pre-due nudge three days before, a friendly reminder at +3 days overdue, a firmer notice at +14 — each deduplicated so a client never gets spammed by a cron rerun. Invoice-sending anxiety is the freelancer's biggest tax; the product volunteering to chase payment is engagement of the deepest kind.
Recurring invoices. A template + schedule becomes Draft invoices on cadence, taxed and totaled through the same engine, optionally auto-sent. The user's "engagement" with their monthly retainers becomes checking that the machine did it — which is the goal.
Quote acceptance on the public link. The client clicks Accept on their phone; the system converts the quote to a real Draft invoice server-side and emails the owner. Closing a deal while the owner sleeps is the product's best trick.
Founding codes. Six months of Pro per code; the founder console generates batches and shares each with one tap (native share sheet or a ready-to-send clipboard message with redemption instructions). Generosity with a ledger — every code tracks redeemed status.

Each of these automated after a manual version proved the flow —
reminders were conceptually "send that email yourself," recurring was
"clone that invoice monthly," quote-accept was "click Convert when they
say yes." Automation amplified verified behavior instead of guessing at
it.

What we deliberately did not build

The refuse-list from Chapter 02, enforced in practice: no time
tracking, no expense ledger, no inventory, no notification inbox vying
for attention. Also — no streak mechanics, no badges, no emails
manufacturing re-engagement. The product's hook is the user's own
unpaid invoice; we just make sure it's easy to finish and easy to
chase.

Recap. Onboard to a finished-feeling workspace in three steps,
never lose work, show honest usage, and let gentle machines —
reminders, recurrence, quote acceptance — act on the user's behalf.
Automate only what proved itself manually, and measure everything
against time-to-first-sent-invoice.

Reading this and want your own dashboard of truth? Create a free workspace at
foxyinvoice.com, then redeem founding code
U8B4Z8S87X on the Upgrade page — 6 months of Pro, free, no card. If anything
breaks, there's a feedback button in the app. I read every one.

Next: Chapter 13 — War stories: six postmortems and what each one cost.

Building FoxyInvoice — Chapter 11: Reach — SEO, AI crawlers, and being the machine-readable answer

Lith SEO — Sat, 26 Sep 2026 00:49:08 +0000

This series is written in the open, from a real production system. This chapter is the reach stack: prerendering, robots.txt, llms.txt, IndexNow, and measuring it all with access logs. [All chapters and diagrams live in the public repo.]

Somewhere between "launched" and "learned people exist," every product
discovers distribution. Ours arrived with a twist that defines this
chapter: half your future traffic now arrives via machines that never
render your app — search crawlers that mostly cope, and AI answer
engines (GPTBot, ClaudeBot, PerplexityBot) that flat-out don't run
JavaScript. If your site is a client-side SPA, those engines see a
blank page with a title. This chapter is everything we built so the
crawlable half of the internet can actually read the product — and how
we measure it.

The problem, precisely

The FoxyInvoice app is an Angular SPA: the server ships an empty shell
and JavaScript builds the page. Human browsers: fine. Googlebot:
tolerant, eventually. AI crawlers: blind. Fetch the marketing page
with curl — which is exactly what a crawler does — and you got:

<title>Invoicing</title>
<app-root></app-root>

One word and an empty div. To every machine reader, our entire free
invoice-template business was the word "Invoicing."

The fix stack, bottom to top

1. The allowlist robots philosophy

Our robots.txt doesn't list what's forbidden — it lists what's
allowed, then disallows everything else:

User-agent: *
Allow: /$ /pricing /privacy /terms /templates /templates/*
Disallow: /

Every future route — admin consoles, /upgrade, QA harnesses — is
non-indexable by default until deliberately made public. The same
policy is enforced server-side with X-Robots-Tag: noindex, nofollow
headers at the edge proxy, per URL: private pages carry it; public
pages don't. Belt and suspenders, because robots.txt disallow alone
never guarantees de-indexing.

2. Prerendering at build time (the pragmatic middle)

Full server-side rendering means an always-on SSR server — violating
our boringness constraint — for pages that are 95% app shell. Instead,
a post-build script generates static, crawler-ready copies of every
public route when the SPA compiles:

Real <title> and meta description per page ("Free Plumbing Invoice Template — FoxyInvoice")
Canonical URL, Open Graph tags, JSON-LD structured data
Full article body copy inside the shell — line items, how-to steps, FAQ — because meta tags describe content; answer engines quote content
The build fails if the sitemap and the template data drift apart (a one-line count check that caught a real bug on its first run)

The edge proxy's try_files serves these static files to anything that
fetches the URL; real browsers still get the app (Angular replaces the
static body on boot). No new server, no SSR framework, crawler-complete
pages.

3. `llms.txt` — a menu for answer engines

The emerging convention: a markdown file at the root telling AI systems
what the product is and linking its key pages, in their vocabulary.
Ours lists the product, every template page with a one-line
description, and contact points. Cheap, human-readable, and exactly
the artifact a "recommend an invoicing tool" query wants.

4. IndexNow: push instead of wait

Crawlers traditionally rediscover content on their own schedule.
IndexNow flips it: on every deploy, the pipeline POSTs all sitemap
URLs to the alliance endpoint (Bing-powered — which feeds several AI
answer engines) with a key file proving domain ownership. Our first
ping returned HTTP 202 — accepted — and the pages were in Bing's queue
the same evening.

5. Measurement: access logs are the truth

"You can't improve what you can't see," so the edge now logs every
request as JSON (rotated, bounded). The analysis is one script:
user-agents, paths, crawler classes. Within days we could see search
crawlers reading robots.txt and template pages — and, just as
valuable, probe-noise (stray /wp-admin scans) being correctly
absorbed. Pair this with Google Search Console + Bing Webmaster
registration (a five-minute runbook lives in the repo) for the
indexing-and-impressions view logs can't give you.

The funnel the surface feeds

Reach is only worth building if it lands somewhere. The template
gallery — now crawlable — is the top of a three-slice funnel we shipped
in order:

Slice 1 — no-signup value + persistence: the generator works anonymously, autosaves locally (30 days), and offers resume on return.
Slice 2 — the signup handoff: "Save & finish online" carries the exact filled invoice through signup into the new account as a real draft.
Slice 3 — the soft capture: "Email me this invoice" stores the draft server-side against their address (with a nurture email); if they later sign up with that address, the dashboard converts it into a real invoice automatically.

Each slice was verified in a real browser before shipping — the funnel
is the one place where "should work" is banned.

Recap. Serve machines real HTML (prerendered at build), allowlist
what's public (default-closed), publish llms.txt, push updates via
IndexNow, and measure with access logs + Search Console. The era of
"GEO" — being the machine-readable answer — is just SEO where the
reader never renders your JavaScript.

Reading this and want to be found the way this series was? Create a free workspace at
foxyinvoice.com, then redeem founding code
U8B4Z8S87X on the Upgrade page — 6 months of Pro, free, no card. If anything
breaks, there's a feedback button in the app. I read every one.

Next: Chapter 12 — Engagement & automation: UI first, then automate.

Building FoxyInvoice — Chapter 10: Feedback tickets shipped — closing the loop while they remember

Lith SEO — Fri, 25 Sep 2026 15:16:45 +0000

This series is written in the open, from a real production system. This chapter is the feedback loop: widget, notification, console, and a real bug from report to resolved. [All chapters and diagrams live in the public repo.]

The single most valuable object in this company is a bug report from a
real user. It is worth more than a roadmap session (it's evidence, not
opinion) and more than an analytics dashboard (it comes with intent and
context). Everything in this chapter exists to shorten the distance
between user notices problem and user hears it's fixed — because a
loop that closes while they still remember filing it converts a critic
into a collaborator.

The feedback loop, rendered live: widget → attachment upload → reply-to-reporter email → triage → fix → deploy → resolve.

The widget: lower the friction to zero

A floating button on every page. No login required — anonymous users
leave an optional reply-to email (and many do). The message field asks
for anything: bugs, confusion, ideas. The attachment field accepts
screenshots and screen recordings (MP4/WebM/MOV, ≤ 15 MB) —
recordings after we learned that users describing a broken flow in
words produce ambiguous prose, while thirty seconds of screen video is
a repro script. Two small decisions that matter:

The comment is the payload; the attachment is enrichment. If object storage hiccups mid-submit, the feedback still saves and the loss is merely noted in the logs — never lose the words because the picture failed.
The page URL and user-agent ride along automatically. "It's broken on /payments" arrives saying exactly which /payments.

The notification: reply-able by construction

Submission queues an outbox email (Chapter 03's transactional pattern)
to the founder with everything inline and — the detail that took a
bounce-storm to learn — Reply-To set to the reporter's address.
Staff hitting "reply" answers the user, not a dead mailbox. The email
also carries a deep link straight to the console entry.

The console: a tiny ticket system, honestly scoped

A single page with four tabs — New → Triaged → Resolved / Archived
— attachments rendered inline (with an auth-header blob fetch, because
<img src> can't carry tokens), recordings playable in a <video>
player, and a status workflow with timestamps. That's the entire ticket
system. No SLAs, no assignee matrices, no Jira — a workflow is only as
wide as the team that maintains it, and this one is maintained in the
same codebase as the product (fix-adjacent, therefore fix-adjacent in
the diff).

Case study: one bug, report to resolved

The best way to show the loop is a real one. A user reported: "On
clicking Edit invoice button, new invoice page is opened. Not able to
edit invoices." Same morning, a second report from the same user:
double-clicking Create made duplicate invoices.

Repro (docker + seeded DB): both reproduced instantly. Diagnosis
went two layers deep — the visible bug was Angular route-input timing
(the editor read its id before the router bound it), but reproduction
exposed something worse underneath: the invoice repository loaded
entities without line items, so line updates 404'd and — the
corruption class — adding a line recomputed totals against an empty
set, silently wiping the invoice's math. One user's confused click had
uncovered a data-integrity hole. Fix: an effect for the route
input, and Include(LineItems) at the repository level (which also
fixed quote conversion losing its lines). Ship: tests, commit
referencing the feedback, push — the Chapter 07 pipeline had it live
same-day. Close: status → Resolved; the reply (one click, thanks to
Reply-To) told the user exactly what had been wrong and that their
report caught a second bug they never saw. That user has filed more
feedback than anyone — because the loop visibly worked.

Why this beats analytics

Analytics tells you that something is wrong ("drop-off on step 3").
Feedback tells you why ("there's no currency picker on this form" —
a real report that same week). Instrument funnels, yes; but read your
inbox like a scientist. At small scale, ten verbose humans outperform
any dashboard you can build.

Recap. Zero-friction capture with recordings, reply-able
notifications, a ticket workflow exactly as wide as the team, and a
loop fast enough that the reporter experiences the fix. The feedback
loop isn't support — it's your highest-signal product process.

Reading this and want to file bug #37 yourself? Create a free workspace at
foxyinvoice.com, then redeem founding code
U8B4Z8S87X on the Upgrade page — 6 months of Pro, free, no card. If anything
breaks, there's a feedback button in the app. I read every one.

Next: Chapter 11 — Reach: SEO, AI crawlers, and being the machine-readable answer.

Building FoxyInvoice — Chapter 9: The daily cadence — twenty minutes that run the business

Lith SEO — Wed, 23 Sep 2026 01:44:00 +0000

This series is written in the open, from a real production system. This chapter is the daily operating loop — the habit, not the feature, that actually runs the business. [All chapters and diagrams live in the public repo.]

Products don't fail from missing features; they fail from absent
operators. The antidote isn't more hours — it's a cadence: a small,
fixed routine you can keep on your worst day. Ours takes about twenty
minutes and runs the entire go-to-market. This chapter is the routine,
the tools that automate each step, and the philosophy underneath:
machines do the scanning; you do only the judgment.

The loop

The daily cadence, rendered live: triage queues (5 min) → hunt HN/Reddit (10 min) → human judgment on replies (5 min) → feed recurring questions back into the product.

Step 1 — triage (5 min). Three inboxes, in order of human urgency:
the feedback console (users took time to tell us something — Chapter
10), the lead queue (today's radar sweep, pre-scored), and the error
console (crashes the app self-reported). Anything actionable gets
assigned; everything else waits unapologetically.

Step 2 — hunt (10 min). Your future users are publicly complaining
about the problem your product solves — today, in threads you can read.
Two channels, both automated to the edge of judgment:

Hacker News radar: an hourly sweep (via Algolia's API) for exact-phrase matches on problem language. One hard-won detail: strict phrase matching — quoted queries plus a post-filter. Without it, a search for "wave alternative" matches any comment containing "alternative," and the queue drowns in noise.
Reddit search kit: bookmarked searches (sorted: new, past month) across the subs where our segments actually live. We originally wanted the Reddit API; its policy approval sat in a ticket for weeks, so we switched to public search RSS and lost nothing. When an API gate blocks you, ask whether the public page already shows what you needed.

Step 3 — judgment (5 min). The radars score; only you decide.
Genuine demand → draft a reply in the lead tool (so it's tracked),
then post it where the person is, human and specific. Everything else →
skip. One honest reply a day beats fifty spray-and-pray comments; the
latter also gets you banned, which is a growth strategy with an
expiration date.

Step 4 — feed the machine. Every recurring question becomes
product: a FAQ entry, a template, a UX fix, a chapter of this series.
The cadence's real output isn't replies — it's compounding
sculpting of the product toward real demand.

Why "daily games" is really "operator habits"

The brief for this series asked about daily games and player
engagement — gamified streaks, invites, nudges. Here's the honest
sequence we landed on: engagement mechanics for users only work after
engagement habits for the operator. You can't design a retention loop
for customers you don't have yet; you can keep a daily loop that
guarantees you'll find, hear, and serve the next ten. The user-facing
loops (streak-like usage meters, founding codes, reminders) arrive in
Chapter 12 — built on top of a cadence that made their data
meaningful.

The metrics glance (the extra two minutes)

Dashboard: signups this week, invoices created, feedback count, crawler
hits from the access logs (Chapter 11 made reach measurable —
GPTBot visiting your sitemap is a real thing you can see now). No
charts-for-charts; four numbers, honestly counted, enough to know if
the week moved.

Recap. Triage three queues, hunt two channels with machines doing
the scanning, spend your five judgment minutes on one great reply, and
let every recurring question sculpt the product. Twenty minutes; the
compounding is the point.

Reading this and want a machine worth running a cadence on? Create a free workspace at
foxyinvoice.com, then redeem founding code
U8B4Z8S87X on the Upgrade page — 6 months of Pro, free, no card. If anything
breaks, there's a feedback button in the app. I read every one.

Next: Chapter 10 — Feedback → tickets → shipped: closing the loop while they remember.

Building FoxyInvoice — Chapter 8: Unit economics — what it actually costs

Lith SEO — Wed, 23 Sep 2026 00:27:12 +0000

This series is written in the open, from a real production system. This chapter is the cost sheet most build-in-public series skip — real numbers, including the honest ones. [All chapters and diagrams live in the public repo.]

This is the chapter most build-in-public series skip, which is exactly
why it's here. The numbers below are the real cost structure of running
FoxyInvoice at its current scale, with marginal items marked as
estimates where our invoices round them away. The punchline arrives
early: the machine costs about a takeaway dinner a month; the real
investment is your evenings. Everything after that is arithmetic.

Fixed costs: the whole business on one table

Item	Cost (monthly)	Notes
VPS (entire stack, both products)	~$8–15	One small instance; the bottleneck is RAM, not CPU
Domain	~$1	Annual renewal amortized
DNS + Email routing (Cloudflare)	$0	Free tier, honestly enough
Email sending (SES)	~$0	First 3k+ emails/mo effectively free at our volume; ~$0.10/1k after
Object storage (PDFs, attachments)	~$0–2	Kilobytes-to-megabytes per user
Backups off-box (S3 + email)	~$0–1	Compressed dumps are tiny at this scale
CI/CD	$0	GitHub free tier + self-hosted runners
Monitoring / logs	$0	Access logs + error console in-app; no paid APM
Total	≈ $10–19/mo	~$120–230/year, both products

Two deliberate zeros deserve a sentence. No managed database — a
$15–80/month line item at every "you should use managed Postgres"
checkpoint — because our nightly, size-checked, off-box backups plus
volume-backed containers cover the actual risk at this scale (Chapter
06). And no paid observability stack, because access logs plus an
in-app error console answer the questions a one-person team actually
asks. Managed services are answers to problems of teams you don't
have; buy them when the problem arrives, not the fear.

Marginal cost: what one more free user costs

A signup costs: a few database rows (bytes), a welcome email
(~$0.0001), and their invoices' PDFs in storage (cents per year).
Marginal cost per free user is effectively zero. The free tier's
10-actions-per-month limit protects database write amplification and
product focus — not margins. That's why "free for 10 years" is a
promise we can afford to put in the terms: the cost of keeping it is
measured in rounding errors.

The paid side: Stripe's take

Payment links (invoice payments): ~2.9% + 30¢ per transaction, paid by the flow of money, not by sitting there.
Subscriptions (Pro $9 / Business $29): the same processing rate on each charge. Net on a Pro subscription after processing: roughly $8.40/month.

Break-even arithmetic

With ~$15/month fixed:

2 Pro subscribers cover the entire infrastructure. Two.
10 Pro ≈ $84 net — the VPS, storage, a domain, and a very modest monthly "salary" for the robot.
100 Pro ≈ $840/mo net — real side-income territory.
1,000 Pro ≈ $8.4k/mo — "quit reconsidering" territory, and the scale where managed databases and paid observability do enter the budget (the cost table grows with trust, not before it).

Founding codes barely register: 6 months of Pro granted free costs
nothing cash-out — it defers revenue that mostly wouldn't have existed
yet, and buys testimonials, bug reports, and the honest word-of-mouth a
new product can't buy any other way. Marketing spend to date: $0. The
template gallery, this series, and replies where the users actually
are (Chapter 09) are the marketing budget.

The cost the table can't show

Your time. The honest ledger of a solo SaaS: hundreds of evenings of
build, a standing 20-minute daily cadence, and the occasional 2 a.m.
incident (Chapter 13 prices those in cortisol). We don't monetize that
column, but we don't hide it either — it's the actual investment
everything else compounds on.

Where the revenue honesty stands today

At the time of this writing: paid subscriptions ≈ zero, users in the
dozens, one power user whose feedback shaped the product more than any
roadmap session. The machine is the story — a business whose cost
floor is dinner-for-one monthly can afford to grow slowly and in
public, which is precisely the experiment this series documents.

Recap. ≈$15/month runs two products. Free users cost nothing,
which is why free-forever is a credible promise. Two Pro subscribers
break even; one thousand change your life. Managed services are
bought when the team-shaped problems arrive. And the real currency
was evenings all along.

Reading this and wondering what your own machine would cost? Create a free workspace at
foxyinvoice.com, then redeem founding code
U8B4Z8S87X on the Upgrade page — 6 months of Pro, free, no card. If anything
breaks, there's a feedback button in the app. I read every one.

Next: Chapter 9 — The daily cadence: twenty minutes that run the business.

Building FoxyInvoice — Chapter 7: CI/CD — push to main and it's live

Lith SEO — Wed, 23 Sep 2026 00:08:25 +0000

This series is written in the open, from a real production system. This chapter is the deploy pipeline end to end, plus three real incidents where it quietly lied to us. [All chapters and diagrams live in the public repo.]

There is no staging environment in this system. There is main, and
main is production. That sounds reckless until you see the gates —
and the alternative for a solo operator (a staging box you maintain,
promote to "when there's time," and drift from reality) is worse.
This chapter is the pipeline that makes push-to-deploy safe enough to
sleep through, and the three times it lied to us anyway.

The pipeline, end to end

The deploy pipeline, rendered live: push → parallel gates (tests, security, secrets) → SSH deploy → health gates → SPA rebuild → smoke test → IndexNow.

Walk the interesting parts:

The gates run first, in parallel. Unit tests plus
Testcontainers-backed integration tests (real Postgres in ephemeral
Docker — tenant-isolation tests from Chapter 04 run here). A
conformance gate checks repo standards against a committed
baseline — new violations block, frozen historical debt doesn't, so
the fleet can adopt gates without a Big Bang cleanup. And gitleaks
scans for credentials, because everyone eventually pastes one.

A concurrency group serializes deploys. Two pushes minutes apart
deploy in order, never interleaved. (Keep this term in mind — it has a
war story below.)

The deploy is SSH + shell, nothing exotic. git reset --hard on
the host (why manual docker compose up there deploys stale code — the
host repo is always mid-flight), then a build that receives the private
feed token as a BuildKit secret — mounted during the build,
evaporating after; never in a layer or image history.

Health gates, then SPA, then smoke. Each API container must report
healthy before the pipeline proceeds (unhealthy = dump container logs
and fail loudly). Database migrations apply automatically on container
startup — EF Core tracks applied migrations in a history table, so
restarts are idempotent. Then the SPA rebuilds on the host (including
the SEO prerender step from Chapter 03), swaps into Caddy's directory,
and both /healthz endpoints must return 200. The final step even
pings IndexNow so discovery engines learn the content changed.

Runners: self-hosted, in a pool. GitHub's included minutes are
exhausted at a $0 spending limit, so jobs run on the org's own Linux
runners — shared with sibling repos, which means queueing is normal and
monitored. (This will matter in war story #3.)

The three times the pipeline lied

Every CI/CD system is a distributed system, and distributed systems
lie. Ours did, three ways, each now a permanent lesson:

The masked failure. The build step ended with
|| echo "WARNING: build failed (using cached image)" and then ran
up -d --no-build. The build failed (missing token), the script
shrugged, containers kept running yesterday's image — and the
pipeline reported success for eight hours. The lesson, now a
repo-wide rule: a failed build must abort the deploy. A green
check that shipped nothing is worse than red.
The zombie concurrency holder. A cancelled deploy run never
released the concurrency group. Every later run was created
pending with zero jobs — the job row only appears when the lock is
acquired — and sat there forever while the UI implied queuing was
normal. Diagnosis came from the jobs API: zero jobs + idle runners =
deadlock, not queue. The fix was renaming the group; the lesson is
that "pending forever" is a distinct failure mode you must know how
to recognize.
The label that matched nothing. Moving the deploy job to the
self-hosted pool, the runner labels were written as a quoted
string — which YAML/Actions parsed as one giant literal label
no runner on Earth advertises. Jobs queued eternally again, this
time invisible in a different way. The fix: a real YAML list. The
general lesson: when nothing ever picks up your job, print exactly
what labels it's demanding — don't trust your eyes reading YAML.

Rollback, and why we rarely say the word

Rollback here is git reset to the previous SHA and redeploy — minutes
of work, no image registry needed (everything builds on the host).
But database migrations complicate true rollback: a migration that
ran won't un-run safely. So the doctrine is forward-fix: the pipeline
is fast enough (and gates strong enough) that fixing forward beats
reverting schemas. The one hard rule that came from painful
experience: never apply schema changes out-of-band — hand-editing
the production DB twice caused startup crash-loops when the real
migration later collided with the hand-made change. If reality forces
your hand, the follow-up migration must be idempotent
(ADD COLUMN IF NOT EXISTS) and the history table reconciled.

Why push-to-deploy is a psychological feature

For a solo developer, the deepest value isn't the minutes saved — it's
that shipping stays a habit. When deploys are ceremony, you batch
changes, batches breed fear, fear breeds bigger batches. When git push is the release process, every fix ships the day it's written
(and Chapter 10's feedback loop closes while the user still remembers
filing the report).

Recap. Gates before deploy, one deploy at a time, health-gated
containers, secrets that evaporate, smoke tests, and a philosophy of
forward-fix. The pipeline's job is to make shipping boring — and its
own failure modes taught us more than its successes.

Reading this and want to see a push go all the way through? Create a free workspace at
foxyinvoice.com, then redeem founding code
U8B4Z8S87X on the Upgrade page — 6 months of Pro, free, no card. If anything
breaks, there's a feedback button in the app. I read every one.

Next: Chapter 8 — Unit economics: what it actually costs.

Building FoxyInvoice — Chapter 6: Accounts, hosting, DNS, email — from zero to a domain

Lith SEO — Mon, 21 Sep 2026 21:48:31 +0000

This series is written in the open, from a real production system. This chapter is the step-by-step shopping list for turning code on a laptop into a URL someone else can type. [All chapters and diagrams live in the public repo.]

This is the chapter people skip and then suffer: the accounts, the
names, the records that turn code on your laptop into a URL someone
else can type. It's step-by-step because order matters — several steps
depend on earlier ones existing. Budget an afternoon and about the cost
of two coffees a month.

The shopping list (in dependency order)

Domain — buy first; everything else hangs off it.
DNS host (Cloudflare, free tier) — points the name at machines and routes mail.
A VPS — one modest Linux box runs the entire system.
Email sending (SES SMTP) — accounts need a verified identity and API keys.
Object storage (S3-compatible) — PDFs and feedback attachments.
Payments (Stripe) — for payment links and subscriptions.
GitHub — code + CI/CD (you have this if you're reading on it).

Each subsection: what to click, what it costs, and the trap we hit.

Domain + Cloudflare

Buy the domain anywhere reputable; point its nameservers at
Cloudflare. Two record concepts do all the work in this project:

A record — foxyinvoice.com → <VPS IP>. The trap: for Caddy's automatic TLS (next section) to prove domain ownership, the certificate authority must reach your server directly — so records stay grey-cloud (DNS-only), not proxied. One toggle; TLS silently fails without it.
MX records — inbound mail routing (below).

Cloudflare also gives you Email Routing free: rules like
support@yourdomain → your-real-inbox. The war story from this repo:
rules existed, but the destination address had an unverified state —
and every feedback notification bounced as a MAILER-DAEMON storm for
a day before anyone noticed the pattern. Lesson: email infrastructure
needs a delivery test, not just a config save. We now send probe
mails on any routing change.

The VPS and the compose file

One Linux box (any provider; ours is a small OVH instance) runs
everything as Docker Compose services:

postgres (per product) · api (per product) · worker (per product) · caddy

Two details that earned their place in the repo docs:

Compose projects are namespaces. The freemium stack runs with -p fox --env-file .env.freemium; forget the env-file once and compose interpolates the other stack's database password into the container, which crash-loops on auth failure. Environment files are credentials wearing a hat.
Data lives in volumes (pgdata), so docker compose down, rebuild, up — the data never moves.

Caddy: TLS you never think about

Caddy sits in front, terminates TLS, proxies /api/* to the api
container by name, and serves the built SPA from disk. Its
superpower is automatic certificates — Let's Encrypt/ZeroSSL issue
and renew with zero cron jobs. The trap that cost us an evening: the
Caddyfile is bind-mounted read-only as a single file into the
container; editing the host file with any inode-replacing tool
(sed -i) is invisible to the running container, and reloads happily
keep the old config. Fix: edit in place + docker restart caddy.
Config-drift bugs look like caching bugs and aren't.

Email: SES and the sandbox saga

Transaction email needs a real SMTP relay (your VPS's port-25 mail will
land in spam purgatory). We use AWS SES via SMTP credentials — with the
honest story that our production-grade SES lives in an older AWS
account while the newer one sits in sandbox (can only email
verified addresses). The pragmatic architecture that fell out: the
mailer takes host/credentials from env vars — swap relays without code
changes. Also: feedback emails set Reply-To to the reporter, so
staff replies reach users instead of a dead inbox.

Object storage + payments

S3-compatible storage holds rendered invoice PDFs and feedback
attachments (screenshots and screen recordings — ≤ 15 MB, with a
server-side size guard so a giant recording can't choke memory).
Stripe needs only a developer account to start: payment links are
created per invoice server-side; the webhook is the source of truth for
"paid." Subscriptions (Pro/Business) run through Stripe Checkout so,
again, we never see a card number.

Secrets: generated, never committed

A generate-secrets.sh produces random DB passwords, JWT signing keys,
and admin passwords at first setup; they live in .env files on the
host, referenced by compose. The repo carries a secret-scanning gate
(gitleaks) in CI because everyone eventually pastes a key somewhere —
the gate turns a bad Tuesday into a red check.

The launch checklist

[ ] Domain bought, nameservers at Cloudflare
[ ] A record → VPS IP, grey-cloud
[ ] Compose up: postgres healthy → api healthy → worker running
[ ] Caddy obtained certificates (site loads with the padlock)
[ ] SES identity verified; probe email sent and received
[ ] Email routing rules + destination verified (probe again)
[ ] Backups cron'd, size-checked, landing off-box
[ ] Secrets generated on-host; repo scan green
[ ] Stripe webhook URL configured and tested

Recap. Domain → DNS (grey-cloud!) → one VPS running compose →
Caddy's auto-TLS → SES with probes → storage → Stripe → secrets by
script. The traps are all configuration drift that looks like caching
— until you write probes for each hop.

Reading this and want a domain of your own to point at? Create a free workspace at
foxyinvoice.com, then redeem founding code
U8B4Z8S87X on the Upgrade page — 6 months of Pro, free, no card. If anything
breaks, there's a feedback button in the app. I read every one.

Next: Chapter 7 — CI/CD: push to main and it's live.

Building FoxyInvoice — Chapter 5: The domain — invoices, tax, and money math

Lith SEO — Mon, 21 Sep 2026 02:43:09 +0000

This series is written in the open, from a real production system. This chapter tours the domain logic: the invoice lifecycle, the tax waterfall, and the exports accountants actually want. [All chapters and diagrams live in the public repo.]

The "domain" is the part of the software that would be true even if you
ran the business on paper: what an invoice is, when tax applies, how a
quote becomes a bill. Get this layer right and every interface on top —
web, public link, export file — is just a window onto the same truth.
This chapter tours FoxyInvoice's domain logic, which is where most of
the genuine engineering lives.

The invoice state machine

The invoice lifecycle, rendered live: Draft → Sent → Paid/Partial/Overdue → Void, and how a quote becomes a real invoice on accept.

Small on purpose. Every extra state is a branch in fifty UIs and a
question for every customer. Overdue isn't stored so much as
derived: a daily worker flags Sent invoices past due (which also
triggers reminders — +3 and +14 days, plus a pre-due nudge three days
before). Credit notes exist as a third type for refunds/adjustments.

Two invariants protect this machine:

Totals are server property. The SPA shows a live preview explicitly labeled "server-confirmed on save" — but no number the browser sends is ever trusted. Every mutation (edit a line, change a discount) triggers full recomputation from the line items up through the tax engine. The client lying about a total simply has no effect.
Edit windows. Invoices lock InvoiceEditWindowHours (default 24h) after certain transitions — accounting systems don't like history being quietly rewritten.

The tax engine: nexus, jurisdictions, and a waterfall

US sales tax is the reason this product has a "tax engine" and not a
tax_rate column. The rules in one paragraph: whether you collect
sales tax for a sale depends on where your business has **nexus* (a
presence triggering tax duties), what jurisdiction the client is in,
and what kind of thing you sold — service vs good, taxable or
exempt, sometimes with a rate override.*

The engine models exactly that, evaluated per line item:

Is the client tax-exempt? → zero tax, keep the line total.
Do you have nexus in the client's jurisdiction? → no: don't collect.
Is a rate known for that jurisdiction? → no: can't collect.
Is there a taxability rule for this product type in this jurisdiction? → use it (including rate overrides); otherwise fall back to the product's default taxability.
Apply: lineTotal × rate, rounded to cents. Never floats.

Jurisdictions carry component breakdowns (state/county/city) for
reporting; a tax liability report sums what you owe where. The
whole calculator is a pure function — no I/O — which makes it the most
tested code in the repo.

Quotes that convert

A quote is an invoice with type=Quote and the same math. Conversion
clones header + lines into a real Draft invoice (new number from the
tenant's sequence, atomically reserved with SELECT … FOR UPDATE so
two concurrent creates can't collide), then voids the quote so it can't
convert twice. The client-facing version (Chapter 12): a share link
with Accept / Decline buttons — accept runs this exact conversion
server-side and emails the owner. One code path for button and menu.

Getting paid: two directions

Online: per-invoice Stripe payment links; the checkout webhook auto-records the payment and moves the state machine. No card data ever touches our servers (Chapter 04).
Offline: record payments manually, or email a payment notice to a dedicated inbound address — SES receives it, S3 stores it, a worker parses it, and a human confirms before it books. Note the trust ladder: machines suggest, humans confirm for anything money-shaped.

Recurring invoices: templates with a schedule; a worker generates
Draft invoices on cadence, runs them through the same tax engine, and
can auto-send. Because it reuses the create path, every invariant
applies for free.

Exports: the accountant is the audience

An invoicing product that can't hand off to the accountant is a toy.
Three formats ship today — CSV (spreadsheets), QuickBooks IIF
(balanced TRNS/SPL entries — debits and credits must sum to zero or
QuickBooks rejects the file), and Tally XML for India (voucher
envelopes where every voucher must balance). An export profile
per workspace holds country, tax registration number, its
locale-aware label (EIN, GSTIN, VAT No…), and fiscal-year start — so a
PDF invoice in India shows GSTIN: 27ABCDE… without anyone configuring
"labels." Export code is where you learn accountants are a format
problem more than a math problem.

Money, one more time

Every amount is (decimal, currency); cross-currency arithmetic
throws; totals are aggregates of per-line decimals rounded once at the
edges (subtot→tax→total each rounded to cents, in a fixed order —
rounding order is an API contract with your accountant).

Recap. A small state machine guarded by server-owned totals, a pure
per-line tax waterfall driven by nexus and jurisdiction, conversion
instead of duplication, machines-suggest-humans-confirm for inbound
money, and exports designed for the person who'll actually read them.

Reading this and want to send a real invoice through this machine? Create a free workspace at
foxyinvoice.com, then redeem founding code
U8B4Z8S87X on the Upgrade page — 6 months of Pro, free, no card. If anything
breaks, there's a feedback button in the app. I read every one.

Next: Chapter 6 — Accounts, hosting, DNS, email: from zero to a domain.

Building FoxyInvoice — Chapter 4: Multi-tenancy & data security — the vault

Lith SEO — Sun, 20 Sep 2026 15:30:48 +0000

This series is written in the open, from a real production system. This chapter is the vault: identity, isolation, authorization, and the tests that prove it holds. [All chapters and diagrams live in the public repo.]

Multi-tenant means many unrelated companies share one running system and
one database, each seeing only its own data. Get it right and hosting
stays cheap forever. Get it wrong and Business A reads Business B's
invoices — for a billing product, that's the ballgame. This chapter is
how FoxyInvoice's isolation works, and — more important — how it's
proven every time the tests run.

The threat model, honestly

Solo developers imagine hackers. The realistic threat is your own
future self at 2 a.m. writing a query that forgets the tenant filter.
Every mechanism below exists to make that mistake impossible to write,
or impossible to ship. Security here is less about firewalls and more
about making the wrong code hard and the breach loud.

Identity: who are you

Three ways in, one result — a signed ticket:

Email + password, hashed with Argon2id (memory-hard; a leaked hash is expensive to crack). Passwords are never stored, logged, or emailed.
Google SSO — OAuth handshake, automatic workspace provisioning. Honesty footnote: the OAuth client still lives in an old, legacy-named cloud project that predates the product — it's the live sign-in identity for both sites; a rename is eventual.
Either way, login mints a short-lived JWT access token (claims: user id, tenant id, permission list) plus a rotating refresh token. The browser shows the JWT on every API call; the server verifies the signature — no session table lookup on the hot path.

Isolation: the three locks

The security model, rendered live: how a JWT’s tenantId flows into global EF Core query filters, a save interceptor that stamps every insert, and CI tests that prove zero leaks.

Global query filters. The ORM (EF Core) attaches WHERE TenantId = current to every query on tenant-scoped entities — automatically. Application code writes plain db.Invoices.ToList() and cannot forget the filter, because the filter isn't in the application code. (A per-tenant model-cache key keeps the compiled filters correct when tenants interleave.)
The stamp. On save, an interceptor writes the caller's tenant onto every new row. You can't insert into someone else's workspace even by trying — the framework overwrites you.
The proof. Integration tests log in as two tenants, create overlapping data, and assert zero cross-visibility. Isolation that isn't tested is a vibe. These tests run in CI on every push.

The escape hatches are deliberate and rare: background jobs (reminders,
radars) use IgnoreQueryFilters() with explicit tenant handling — each
one a conscious, commented decision.

Authorization: what may you do

RBAC — roles map to permission strings (invoice:create,
tenant:manage_settings, …). The same list drives three layers: route
guards in the SPA, element-level hiding in templates, and — the one
that actually matters — HasPermission checks on the API. The UI is
courtesy; the server is law. Custom role builder for workspaces that
want finer grain.

Scoped access: the share token

For "show this invoice to my client," there's a fourth lock: a
32-byte unguessable token in the URL is the authorization — no
account for the client, scoped to one document, expiring, revocable.
Quote acceptance (Chapter 12) rides the same mechanism.

The rest of the vault checklist

Audit trail — an interceptor snapshots before/after JSON for changed entities: who, what, when, from which IP. Subtle bug worth stealing: if a save fails, the interceptor must drain its pending audit buffer, or the next successful save writes audit rows for changes that never committed.
Backups — nightly pg_dump, gzip, size-checked (a 200-byte backup is a failed backup), copied off the box (S3 + email). A backup you've never restored is a hope, not a backup.
No card data, ever — Stripe holds payment methods; we store ids. PCI compliance by not playing.
GDPR posture — "export everything I own" produces a full JSON dump (we built it as a feature and test it with it); deletion disables users immediately and hard-purges after a 30-day grace.
Secrets — generated by script, living only in .env files on the host, caught by a gitleaks gate if they ever try to enter the repo.

Security posture: honest about the stage we're at

Isolation, tests, backups, and no-card-data are the controls we treat
as non-negotiable at any size — the 80/20 that protects what actually
matters for a billing product. Beyond that spine, the security program
matures the same way everything else in this series does: gated by
real usage rather than built speculatively ahead of it. The next layer
— deeper account-takeover hardening, broader defense-in-depth — scales
with the stakes, and grows in the open, in this repo.

Recap. Signed identity, filters you can't forget, stamps you can't
spoof, tests that prove it, permissions enforced where it counts, and
scoped tokens for sharing. The vault is mostly removing ways to be
wrong.

Reading this and want to poke at the vault yourself? Create a free workspace at
foxyinvoice.com, then redeem founding code
U8B4Z8S87X on the Upgrade page — 6 months of Pro, free, no card. If anything
breaks, there's a feedback button in the app. I read every one.

Next: Chapter 5 — The domain: invoices, tax, and money math.