One person, a formal AI-agent workflow, and a PDF product taken from broken to hardened

Serverless doesn't forgive assumptions a normal server tolerates

The product's PDF rendering engine depended on a native-binary canvas library and pdf.js's worker-based rendering model: both fine on a normal server, both broken on Vercel's serverless runtime. The canvas library couldn't link its underlying system graphics libraries in that environment; pdf.js loads its worker script through a dynamic import the deployment bundler can't trace statically, so the worker file simply never shipped. The failures didn't look the same twice (sometimes an outright 500 error, sometimes the request "succeeded" but the output was barely smaller than the input), while all of it worked correctly on a local machine. That mismatch is its own lesson: a serverless environment can pass every local test and still not run the same code path once deployed.

The database had the same category of problem: a file-based SQLite store on a filesystem that's read-only at the application root, so writes there failed outright with a read-only-filesystem error; redirecting writes to the one writable scratch directory available didn't really fix it either, because that storage doesn't survive between function invocations, so a write could succeed and then simply not be there anymore the next time a user's request landed on a different instance.

Underneath both of those was a business-critical concern that hadn't been addressed at all yet: the app includes Stripe checkout for buying credits, and no dedicated security review had been run against it.

Rebuilding the engine around the runtime's actual constraints, not around what's convenient locally

   Before                                    After
   ──────                                    ─────
   [ canvas (native binary) ]                [ mupdf — pure WASM ]
   [ pdf.js worker (untraceable) ]     ──►    [ no worker, no native deps ]
   [ SQLite (local file) ]                    [ Supabase Postgres, self-hosted ]
          │                                          │
          ▼                                          ▼
   Fails silently on Vercel                   Runs identically local & deployed

Leaving Vercel for self-hosting

Once the engine and the database worked, I took the product off Vercel entirely and recorded the decision in an ADR. Supabase was already the backend for data, sign-in, and file storage, so the real question was where that data lives. Supabase's managed cloud would have put user rows and files on someone else's servers. Supabase is open source, though, and the same stack runs in Docker, so self-hosting it keeps every row and every stored file on infrastructure I control.

The app now ships as a Docker image next to that self-hosted Supabase stack. Local development runs the identical stack, so what I test on my laptop is what runs when deployed. The Terraform describes the AWS side: EC2 instances that require IMDSv2 and use encrypted disks, managed through Systems Manager with no SSH port open, an optional load balancer in front of each instance, and the image kept in ECR.

The cost is that I now run it myself: backups, image updates, disk space, and TLS certificates are my job, not a platform's. The ADR says so plainly, so it's a choice on record rather than a surprise later.

Privacy by construction, not by policy

The server-side flow already carried a privacy decision worth naming on its own: the optimized output gets stored in a private bucket so a user can re-download it later, but the raw uploaded file itself never does (only the result is retained, never the source). The in-browser mode takes that same instinct to its logical endpoint. For a document someone doesn't want leaving their own device at all, such as a contract, an ID scan, or a medical record, the file is never uploaded anywhere in the first place. The same compression engine runs inside a Web Worker on the user's own machine, compiled to WebAssembly, so "we don't see your file" is an architectural fact rather than a policy promise someone has to take on trust.

That turned into a real product problem, not just a technical one: the app still needs to meter usage per page for a file it never receives. That's handled with a fileless reserve/complete/abort exchange (the client tells the server how many pages it's about to process before the work starts, the server reserves the credits for that, and the client confirms or aborts once the in-browser job actually finishes) so the credit-based business model stays intact without the server ever needing to see the file to enforce it.

The trade-off is a one-time ~4.7MB WebAssembly engine download before the in-browser mode can run at all. It's cached after that first load, and that caching is what made the installable, offline-capable version of the app possible as a natural side effect, rather than a separate feature that had to be built on its own.

The engineering process itself

This was built and operated by one person, directing AI coding agents against a written operating protocol: not an ad hoc "ask the AI to fix it" loop, but a standing document the agent is required to follow on every change, the same way a team would follow an engineering handbook.

The protocol runs every change through three explicit steps in order: explain the issue (what broke, the actual technical root cause, in plain language) before touching any code; propose the fix and name exactly which files it will touch and why; then implement, test, and document. Skipping straight to "here's the fix" isn't allowed, which matters specifically when you're the only reviewer: the explanation step is what a second engineer's code review would normally catch, done before the change lands instead of after.

Every one of the 28 issues logged during development (from the serverless native-binary failures to the security audit findings) went through the same fixed shape: a dated write-up of the symptom, the root cause, the fix, and a prevention rule, filed in its own document and indexed in a master tracker before the issue counted as closed. That discipline is what turned a nasty bug into a traceable record instead of a memory: a post-login authentication failure was fixed once by closing a session-save race condition, recurred anyway, and was fixed a second time by adding live token-refresh handling. Going back through the written RCA trail, not a fresh guess, eventually surfaced the actual cause: the database table the login route depended on had never been created in the first place, so every read had been failing silently all along and each earlier fix had correctly solved a symptom of a problem it couldn't see.

There's also a hard automated gate, not just a written guideline: ten test suites covering authentication, Stripe pricing math, upload validation, real compression runs against synthetic PDFs, and the premium/credit logic, and the protocol is explicit that if any suite fails, nothing gets pushed until it's fixed and every suite passes clean. On top of that sits a pre-push checklist scoped specifically to what an AI agent might otherwise skip under time pressure (tests green, new environment variables documented, the relevant issue doc and tracker updated, secrets excluded from git, and a commit message that actually states what changed) checked before any deployment command is even suggested, let alone run.

The protocol itself wasn't written once and left alone, either: it absorbed its own lessons. The rule that optional native modules must be guarded with try-catch fallbacks, and that serverless functions must never assume local filesystem write access, are standing instructions today specifically because ignoring both of those is what caused the original production outage this project started from.

Trade-offs

Rewriting the rendering engine instead of patching the native-binary approach cost real time up front. WASM compilation has its own quirks, and the migration touched every code path that generated a PDF. It was the right call because the alternative was chasing an open-ended list of serverless-incompatibility bugs one at a time, each looking like a one-off until the next one landed. Running the security audit as a dedicated pass, rather than fixing issues opportunistically as they were noticed, surfaced the critical webhook finding because it wasn't reachable through the app's normal usage paths. It only showed up under a deliberate line-by-line adversarial read of the whole codebase (server, routes, middleware, and client), which is a good argument for scheduling that kind of pass rather than waiting for something to trigger it.

What this shows

I built and ran this alone, with no customers. I set the requirements myself and treated them the way I would a customer's, so the work shows the habits that matter when you ship into someone else's environment:

• Work inside the real constraints. I started from a deployment that didn't run, and I fixed it within the serverless runtime's limits instead of redesigning in an ideal world.
• Own the whole path. Requirements, build, deployment, security, and day-to-day operation all sat with me, with no one else to hand a problem to.
• Put decisions on record. Choices such as self-hosting over a managed cloud, and one EC2 instance over EKS, are written down with their costs in architecture decision records and a cost comparison.
• Turn failures into records. Each of the 28 issues has a written root cause, a fix, and a rule to stop it coming back.
• Say what is verified. The security audit was one I ran myself, not an independent one, and this page says so.