about

I write the article I wish I'd found at 3am.

Fifteen years building typed systems — domain-heavy Node backends, React front ends that trust their own types, and the CI/CD that quietly carries all of it into production. I write to force my own understanding into a shape someone else can reuse.

Subscribe Follow on GitHub

Laptop displaying source code on a wooden desk beside a notebook

background

The short version

I started on jQuery-era monoliths, moved to Node when it was still a risky bet, and have spent the last decade on TypeScript codebases where the domain — not the framework — is the hard part. Payments, logistics, clinical scheduling: places where a wrong state transition costs real money or real trust.

That work taught me the same lesson repeatedly. Systems don't rot because of the language or the cloud provider; they rot because the boundaries were never drawn, and because nothing tested the behaviour anyone actually cared about. So that's what I write about.

Bashhow-i-work.sh

# every article ships as a runnable repo
git clone git@github.com:patfrancis/hexagonal-orders.git
pnpm install

pnpm test:unit      # vitest — domain, no I/O
pnpm test:integration # mocha + testcontainers
pnpm test:e2e       # playwright, seeded state

# then, and only then, it gets written up
pnpm docs:build

why i write

Three reasons this site exists

Writing is the review

An explanation that doesn't survive being written down was never a design — it was a habit. Publishing forces me to justify every boundary I draw.

The middle is missing

There is no shortage of five-minute intros or 600-page tomes. Very little sits in between: full worked examples, at production scale, with the trade-offs named out loud.

Teams inherit patterns

One good repository template outlives any consultancy engagement. I'd rather hand over the pattern than the invoice.

what's different

Architecture-first, tested, and opinionated on purpose

Tested, not asserted. Every snippet is extracted from a repository with a passing suite; the test file is part of the article, not an appendix.
Architecture before tooling. Ports, adapters and use cases come first — the framework chapter comes last, because it matters least.
Opinions with edges. I say which approach I'd ship and where I'd stop trusting it. No "it depends" as a conclusion.
Failure modes included. The 2am story is in the article: what broke, what the dashboards said, what I'd do differently.
AI treated as a tool, not a genre. Agents get used where they measurably help, and reviewed like any junior contributor.