DUDE

05  ·  Under the hood

Boring technology, defended choices

Server-rendered HTML, raw SQL, no build step and no front-end framework — because simplicity of implementation is a feature, and the previous codebase's real failure was that it couldn't be fixed.

The stack

What it's made of

ApplicationPython and Flask with Jinja templates, server-rendered. No separate front-end app, no build toolchain, no framework.
Front endSmall islands of hand-written JavaScript only where the job needs it: the sign-off screen that drives a vendored signature pad and PDF renderer, one shared type-ahead, a submit guard, the uploader. About 1,600 lines of our own, plus those two vendored libraries.
HostingGoogle Cloud Run, one service, scale-to-zero.
DatabaseCloud SQL Postgres, accessed with raw SQL and no ORM. The schema lives in numbered SQL files where every constraint is visible in plain text.
MigrationsHand-written numbered SQL files, applied once each, in order, by a script that records what it applied.
AuthGoogle sign-in restricted to the company's Workspace domain. No passwords stored anywhere.
IntegrationsQuickBooks Online, QuickBooks Time, Google Drive, Google Sheets, Google's document AI for receipt parsing, and the Maps routes API for one calculator. Every client has retry with exponential backoff and its own error type.
PDF workThree open-source libraries. Commercial PDF tooling would have consumed the entire monthly budget on its own.
Scheduled workCloud Scheduler calling authenticated endpoints — a nightly schedule backstop, a list refresh, a token-expiry check.
SecretsSecret Manager. No token or credential has ever been in the repository.
Tests2,314, green, run against a real Postgres. External services are mocked at the transport boundary, not at our own function boundaries.
EmailNone in DUDE. Deliberately — it's a compliance decision, not an omission. The client portal, a separate application, sends transactional mail from a separate registrable domain.
Version controlEvery slice is a branch and a pull request, merged with a merge commit — never squashed, never rebased, because the documentation cites commit hashes and a rebase rewrites them.
Second productThe client portal is its own repository, its own cloud project and its own service, sharing only a database instance. The two talk over five one-directional endpoints.
23,928lines of Python
40,849lines of tests
1.71×test code per line of app
47migrations
38tables
170routes

Costed up front at roughly $15–$40 a month against a hard ceiling of $200. In October 2026 the real bill was read for the first time and came in at about $31 a month across both products — the estimate held. Figures on this page are DUDE's, as of 28 October 2026; the portal's are on its own page.

Design calls

Ten decisions worth defending

Derive it, don't store it

applied as doctrine

Three of the most visible numbers in the fleet module — a machine's label, its current usage, and its last service date — are stored nowhere. They are computed every time they're read.

The payoff is what isn't there. There is no "next due" column, so the function that completes a service needed no changes at all to make the due board correct — and there is nothing to forget to recompute when a reading is voided, added, or an interval is edited.

The insert is the check

Double-submission guards don't check and then insert — they insert against a unique index and let the database decide. Check-then-insert loses to the concurrent tap, every time, because each call is its own transaction.

And a replay asks rather than silently swallowing, because editing and resubmitting is a legitimate thing to do. The re-rendered form carries a fresh token, so its own double-tap is caught too.

Two mechanisms on one page, on purpose

One screen uses a server-side token for the case where a duplicate is permanent — a burned asset id that ends up painted on a van — and plain JavaScript for the case where a duplicate is merely untidy.

Consistency would have put the permanent case on JavaScript. The choice is made by failure mode, not by tidiness.

The URL is the state

The job tracker has five filters, a card view and five preset chips — and no saved views, no per-user configuration. A query string is the view, a preset is a named link, and adding another one costs a label. Bookmarkable, pasteable, and there is no per-user state to migrate later.

A companion check runs at import: the app refuses to start if the six lifecycle phases ever stop exactly partitioning the fifteen statuses. A sixteenth status cannot quietly disappear from the board.

The cache buster is a single conditional

The platform hands us the revision identifier. Its presence simultaneously switches on a year-long cache lifetime for static files and appends the revision to every static URL the app generates. Not one template changed, and not one asset was missed.

The two halves cannot be separated — a long cache lifetime on its own would strand iPads on stale JavaScript for a year — so a test asserts they appear and vanish together. A new deploy means new asset URLs, which means a guaranteed cache miss, and the miss is the refresh.

A second, tighter timeout budget for the field

Drive calls made while rendering a page run on a much shorter budget than Drive calls that write something — because a wedged render pins one of only four worker threads, and a tech staring at a spinner on cell signal is a support call.

The honest limit is written down next to it: a library default upstream makes the tighter budget a soft ceiling, not a guarantee. Recording that is cheaper than someone later discovering it and distrusting the whole note.

Asymmetric retries, deliberately

Some operations retry hard and then fail open; others try twice, briefly, and then refuse. Which posture applies is chosen per path by what a wrong answer costs. Refusing on a read failure is right where a mistake writes a payroll record; it is wrong where a mistake merely blocks the button that creates a customer in QuickBooks over one flaky minute.

The schema carries the invariants

Constraints make half-set rows impossible: a person record must attach to a company, a "waiting" record must carry a reason, a completed record must carry a completion date. A partial unique index enforces one pending signature request per job and document.

One constraint reads "zero or more" rather than "greater than zero", and the comment explains why: a baseline reading of zero is a brand-new machine. The same lesson bit us elsewhere — one shared validator was correct for an interval and wrong for a baseline, and stayed invisible for three slices because its error message was about intervals too. The fix was to split it, not to add a flag.

Read the guard from the source, not the running object

the alternatives are circular

To prove every web address is locked to the right kind of user, the test parses the guard out of the source text, dispatches the real route, and asserts the two agree. The obvious alternatives were rejected on the record: reading the guard off the running function proves only that the route carrying the guard carries the guard, and a hand-maintained table of expected answers is the same author discipline moved one directory away.

It also states its own limit. It proves the routes are gated as declared; it says nothing about whether the declarations are right. The only evidence for that is a hand-check — and the slice wrote down that the hand-check does not renew itself.

One way in, which is why a second product is a second application

Every sign-in to DUDE is checked against a signed claim that the account belongs to our Workspace domain. One domain-locked door is what makes every screen behind it safe. Adding a client login would make each screen's safety depend on which door the request came through — across everything ever built.

So the client portal is a separate repository with a separate deploy. The reasoning is mechanical, not philosophical: this project deploys its working tree, so code living together rides in each other's production images, and with no continuous integration the repository boundary is the only isolation that cannot be crossed by accident. The conditions that would reverse the decision are written down beside it.

Transferable

What I'd tell someone doing this

Probe, don't reason — and don't price a probe like a project

A read-only script against the live account disproved an assumption the whole schedule design rested on, across all 684 records, before any code depended on it. Thirteen of them exist against that one API alone. They are the cheapest thing in the repository.

Verify a guard in both directions, by running it

A test that fails when you delete the fix is not the same as a test that fails when you break the fix. Two scripted harness runs, 39 deliberate reverts between them, and four checks turned out to be green for the wrong reason.

Ask who the real consumer is

The permission outage survived 967 tests because every net ran as the file's owner. Nobody had exercised the thing as the user that actually runs it in production.

Hunt by the shared dependency, not the name

A census that grepped for a function name missed a byte-identical copy on a field-facing screen. The count was right for the wrong reason. Search for what the code depends on, not what you expect it to be called.

Hook a rule to a checkable value

The document teaching "re-derive your citations" broke its own sixteen citations in the commit that created it. A hook that names a document is weaker than a hook that names a value someone can check.

Scope fences leak through the surfaces nobody diffs

A stylesheet can breach a scope fence with no application code in the diff at all — and a brand-new page can walk into a shared component's assumptions without changing a byte of it.

Deletion deserves to be a slice

One whole slice existed to remove indexes and a table that had become false teaching — structures that looked like they were doing something and weren't. Removing a misleading thing is real work with real risk.

Adversarial review will not save you from scope

It answers "is this correct?" and is structurally silent on "is this the problem we set out to fix?" That second question needs its own owner, out loud, early.

A rule that waits on the outside world needs something that watches

Two dependencies were pinned under "this moves only when an advisory is published against it." Both triggers fired weeks before anyone noticed, and four deploys shipped past them. A trigger with no reader is a hope — so the check moved into the deploy's own preflight.

A fix at the scene of an incident owes a census of its class

Measured across five slices: a rule invented in one place, explicitly naming the older code it was leaving behind, and then not applied there two slices later. A pattern copied into the second repository "at birth" never received the fix the first one got.

Count what the process costs, then decide on purpose

The documentation-to-code ratio sits flat at about 3.2 to 1 across thirteen slices. A review offered six costed ways to bring it down. I took none of them — but the number is measured rather than assumed, which is the part that matters.

About

Who did what

I'm Dillon Freilinger. I own Done Done Services and I'm not a software engineer. I wrote and froze the requirements, chose the architecture from written options, made every user-facing call, ran the reviews and signed off every slice. Claude wrote the application code across sessions that were never permitted to decide anything on their own.

The interesting claim isn't that a language model can write Flask. It's that the bottleneck turned out to be the process, not the code: the failures on the previous page are almost all failures of verification, scope or record-keeping, and almost none of them are failures of syntax. The rules that fixed them are the deliverable as much as the app is.

DUDE runs behind Google sign-in restricted to our own domain, so there is no public demo to link — the guides are inside the app, where they can't go stale without somebody noticing. The client portal is reachable by anyone, but it will only ever show you a sign-in box.

Each of these was invented, proved itself, and then had to be re-invented. Nothing carried them forward. This file carries them forward.

the slice playbook, on why it exists