One page per topic
Each page answers one question, in 2–4 minutes. Rules come first; the reasons are bullets, not essays.
effect-lab 🧪
We read eight real Effect codebases, argued with ourselves for weeks, and wrote down who won. Here are the short versions.
What is this?
Section titled “What is this?”effect-lab is a study lab for software engineering, read through
Effect v4 codebases. Real open-source projects (hazel, slopcop,
t3code, opencode, maple, alchemy, x2mail and Effect itself) are the reading material. For each
topic we surveyed what those teams actually do, then picked one convention for our own
backend code and wrote down why the alternatives lost.
The full write-ups live in notes/. They are long, cite every line of code, and are written so an
agent can follow them. This site is the human cut: each decided topic shrunk to a handful of
rules with an example of getting it wrong and getting it right.
Impact pills
HIGH means getting it wrong costs a rewrite or a security hole. MEDIUM hurts. LOW is hygiene.
❌ then ✅
Every rule shows the shape we rejected next to the one we picked. The code uses the names the notes use today.
Deferred, on purpose
Things we chose not to build yet are listed at the bottom of a page, each with the trigger that would make us build it.
Start here 🧭
Section titled “Start here 🧭”The notes map 116 topics; that is a map, not a queue. These ten build on each other. Read them in order and the rest can be pulled in when the product asks for it.
1 · File & folder structureDecide where things go before there is anything to put there.
2 · Workspace boundariesWhat earns a package of its own.
3 · Service definitionThe unit everything else is built out of.
4 · Contract vs implementationWhere the tag lives relative to its Layer.
5 · Layer compositionHow those units get wired into a running program.
6 · Error modelingFailures are in the type; deciding late means rewriting signatures.
7 · Schema modelingThe other half of the same type.
8 · Schema at boundariesWhere untrusted data becomes trusted.
9 · HttpApi & handlersThe first surface that makes the rest real.
10 · TestingProves the nine decisions above actually hold.
Fine print
Section titled “Fine print”- Backend first. Decisions are made for server code. Frontend patterns show up only as contrast.
- Bets, written down. Every decision leans on a short list of assumptions: a long-lived server or a Cloudflare Worker, one SQL database (Postgres, SQLite or D1), a multi-org SaaS. If one of them is false for you, start there.
- Effect v4 only. No v3 idioms. Where an app repo uses an older API name, the notes follow the Effect source.
- The notes win. If this site and a note ever disagree, the note in
notes/is the source of truth, and the page is a bug.