The blueprint: an HTML-to-PDF API on Postgres, Chromium, and not much else

Adrian — Mon, 13 Jul 2026 09:55:24 +0000

PDF generation in 2026 is glued together from Puppeteer, LiquidJS, and S3. What's not solved by the glue is the production shape around it:

Documents range from 50 KB to hundreds of megabytes. Memory can't care.
Traffic arrives in bursts (10,000 documents at once). Rendering is CPU-bound.
Documents contain names, amounts, addresses. Sensitive by default.
For a solo operator, whatever you build has to be runnable by one person.

I built DocPenny around those four constraints in about twelve weeks. This is the blueprint.

The stack

SvelteKit, Hono, pg-boss, PostgreSQL, Chromium, S3-compatible storage. Nothing else. No Redis, no Kafka, no Kubernetes. No connection pooler — I ran one and deleted it.

pg-boss is the load-bearing choice: a job queue on the Postgres you already have. One database for app data and async jobs. One thing to back up, one thing to monitor. The alternative (Redis + BullMQ) adds a second stateful service whose failure modes (persistence config, eviction policies, split-brain) are exactly the kind you debug at 3 AM. For a solo product there is no on-call rotation; there's just you. Every dependency you don't have is one that can't bring the service down.

Memory-bounded streaming

A PDF can be 50 KB or 400 MB. If any stage holds the whole document in memory, RAM scales with the largest thing any customer generates. So no stage does:

Page.printToPDF({ transferMode: 'ReturnAsStream' })
  → IO.read(handle, { size: 1MB })
  → Node.js Readable (backpressure-aware)
  → S3 multipart upload (5 MB parts)

Chrome writes to a stream as it renders. Node pulls 1 MB chunks. If S3 slows down, reads from Chrome slow down — nothing accumulates. S3 starts receiving parts before Chrome finishes rendering the last page. Memory per document is a fixed ~20 MB, regardless of output size.

The default (transferMode omitted) buffers the entire PDF in Chrome's memory, then again in Node's. Works in every demo. Falls over the first time a real customer sends something big.

The queue is the load balancer

Client → API (Hono) → pg-boss queue (Postgres)
                            ↓
              Workers (N replicas, CDP pool)
                            ↓
        Chromium renders → stream → S3 multipart
                            ↓
              Webhook (HMAC-signed) → client

Ingestion: ~5,900 documents/second. Rendering: ~63/second. That 90× gap is the design. The queue absorbs spikes; workers drain at their natural rate. Nothing drops. Never couple accept rate to render rate.

Security from day one

Templates are structure, not data. Sensitive values come as JSON payloads at render time, encrypted with AES-256-GCM before touching storage. Each payload gets a fresh HKDF-derived key from the master secret and a random salt — used in memory, never persisted. No key table to leak.

Webhooks are HMAC-SHA256 signed with a constant-time verification helper. Artifacts are short-lived: previews purge in 24 hours, documents in 4 days. The best breach mitigation is data that no longer exists.

The numbers

One slice of a shared OVH server, ~€45/mo for 9 of 24 threads. k6 saturation test:

API ingestion: 8.47 jobs/s ≈ 5,938 documents/s enqueued, 100% success
Render throughput: ~63 PDFs/s (CDP pool is the bottleneck, by design)
p(95) latency under saturation: 4.7 s

Build or buy?

HTML-to-PDF is a crowded market with healthy competition. The pattern:

Buy when document generation is not your product. If PDFs are an output of your actual business (invoices, reports), the twelve weeks I spent are twelve weeks of your roadmap rebuilding a solved problem, plus permanent ops burden (Chromium upgrades, storage lifecycle, security patching). Managed APIs charge fractions of a cent per document.

Build when volumes make per-doc pricing material, data can't legally leave your infrastructure, or no vendor supports your rendering requirements. Then this blueprint is your starting point. The mistake most teams make: defaulting to the infrastructure they'd deploy at a company ten times their size. Teams don't fail by choosing the wrong queue. They fail by carrying five services when the problem needed two.

Full article with the complete business side, unit economics, build-vs-buy framework, and a note on OSS: adrianani.com/articles/html-to-pdf-api-blueprint

The hidden cost of "stepping up" (why it's a trap and what to do instead)

Adrian — Fri, 10 Jul 2026 09:19:10 +0000

Companies expect engineers to "step up" and take on architectural responsibility, without defining what that means, giving them time for it, or providing guidance. The engineers absorb the cost silently: sprint goals slip, tech debt piles up, burnout follows, and when things break there's no map to fix them.

Deferring 2-3 sprints of foundation work to hit a deadline routinely costs months of development time later, once the system breaks and the team has no structure left to recover with.

The inherited mess

At my last job before consultancy, we inherited a codebase from a contractor: an AI-generated application with no thought for DRY, security, or performance. It worked on the surface. Underneath: duplicated code with no component abstraction, circular dependencies, memory leaks, console errors, no documentation.

We rewrote it. The stack was chosen for the business, not preference: Nuxt 4 with CSR (no SEO needed behind a login), reka-ui for accessible components, Tailwind for speed, TanStack Query for sane networking against a separate .NET API, and a docs/ folder that made the codebase navigable by humans and AI both.

Result: 80% of what the client had planned for one year, delivered in four months. That took 120% capacity, which isn't sustainable long-term, but the structure is what made it possible to push hard without the codebase collapsing under the team.

The pattern

Assessment. Audit for circular dependencies, memory leaks, console errors, duplication. Quantify it: how many pages, how much duplication, how many dependencies. Frame it to product as cost (fragility, onboarding friction, delivery speed), not aesthetics.

Foundation, 2-3 sprints of non-feature work. Pick the stack from business constraints: rendering strategy from SEO needs, component library from accessibility requirements, state management from data complexity, styling from team size. Write the docs. Build the first features as examples.

Scaling. Onboard against the docs and examples. Deliver features on the clean foundation. Maintain it with continuous small investment, not big rewrites.

The diagnostic

Recognize 3+ of these and your team is absorbing dysfunction instead of negotiating it.

Code-level:

Degrading quality: workarounds, deprecations, circular dependencies, memory leaks, console errors, duplication
No documentation
No tech stack strategy driven by business needs

Process-level:

Consistent sprint delays, team running at 120%+ capacity
Engineers afraid to voice opinions or ship to production
No one owns the architecture or prioritizes tech debt
Onboarding takes weeks because knowledge lives in people's heads

Organizational:

Product doesn't see tech debt because the product still works, until it doesn't
Engineers don't understand business priorities; product doesn't understand engineering constraints
Every tradeoff conversation ends in frustration because there's no shared language for the tension

The real cost

I've been on both sides: the team where "stepping up" was never defined, and the team where we built structure and delivered. The difference wasn't the engineers. It was the system around them.

The hidden cost of "stepping up" isn't just burnout. It's the features that didn't ship, the onboarding that took weeks, the incidents that could've been prevented. It's invisible until you build the structure to see it.

DEV Community: Adrian