DEV Community: Anton Brilliantov

Context Is Not "More Context"

Anton Brilliantov — Fri, 04 Sep 2026 06:34:51 +0000

An iteration that touched two files was burning ~350,000 tokens - not because the task was big, but because whoever executed it went looking around the repository first. What fixed it was not more context. It was writing down which context, once, and forbidding the rest.

👋 Hi, I'm Anton - a software engineer working mostly in PHP/Symfony and Go. Most of what I write about comes out of carving a live PHP monolith into Go services. This series is about a smaller, adjacent problem: how I hand work to an executor - human or model - so the result comes back correct without me re-explaining the codebase every time. Running notes live on my GitHub: github.com/brilliant-almazov.

These are my working habits, not a methodology. They're shaped by one specific codebase with very rigid conventions. Take the parts that transfer.

The number that started this

I was running a stage of work split into small iterations. Each iteration was supposed to be tiny: connect one file to an existing core, move its test, run the package's tests, done. Two files touched, maybe three.

Each of those iterations cost roughly 350,000 tokens.

I assumed the tasks were bigger than I thought. They weren't. I went back and looked at what was actually being read, and the answer was boring: the repository. Before writing a line, the executor was hunting for the type it had to embed, then for a similar file in a neighbouring package to copy the shape from, then for the error sentinel names, then for the test helper. Every single time. Nine-tenths of the spend was reconnaissance, and none of it landed in the diff.

The reflex fix is to give more: "here's the architecture doc, here's the design, here's the other domain, go." That makes it worse. Reconnaissance you pay for once is a cost. Reconnaissance you hand over as background is a cost and a hazard - the more neighbouring code is in view, the higher the chance the wrong neighbour becomes the template.

Two different things get called "context"

Separating these was the whole fix:

Task context - what has to be done and how it will be checked. This must be complete. Anything missing here gets invented.
Codebase context - how things are built around here. This must be minimal. Exactly the files named in the task, nothing else.

Almost every bad task I've written failed by getting these backwards: vague about the task, generous about the codebase. "Connect the reads to the shared core, see how the neighbouring domain does it" is exactly that shape. It says nothing checkable, and it delegates a search.

TASK CONTEXT — must be complete       CODEBASE CONTEXT — must be minimal
─────────────────────────────────     ─────────────────────────────────
files to create (exact paths)         only the files named, by path
files to change (exact paths)         no tree search, no grep
signatures it plugs into              no neighbouring packages
values: errors, env, tables           no discussion history
the acceptance command                no "how it's usually done"

What the executor must know

Five things, and they're all boring to write down:

Exact paths of every file to create and every file to change - a closed list. A file not on the list is not touched and not read.
Full signatures of whatever it plugs into: name, type parameters, methods, package, import alias. Not "the reader type" - the actual declaration.
The existing primitives it must reuse, by path, each marked do not write your own copy. This is the single highest-value line in any task I write, because the default failure of a fast executor is to write a fresh, locally-reasonable version of something that already exists twenty metres away.
Values, as values: error sentinel names, env var names, queue names, metric names, table names. Not "the usual naming" - the strings.
The acceptance command, runnable with no substitution: the exact test invocation, scoped to the package being touched.

What the executor must not know

Neighbouring iterations. The discussion that led to the design. Packages outside the list. "How we generally do things."

Every one of those is a real cost multiplied by the number of executors, and every one is a chance to copy the wrong template. A fact written into the task is paid for once. The same fact discovered by the executor is paid for on every executor - and it isn't even the same fact twice, because two searches don't land in the same place.

Where the spend actually goes

After the split I started sorting the waste. Roughly in order of size:

Source	What happens	Share
Reconnaissance	types, paths and signatures get re-discovered; neighbouring packages get read	largest
Full re-runs	every iteration runs the whole test suite and the linter over the whole repo	large
Rework	an iteration fails acceptance and gets rewritten	large
Guard trips	a copy of an existing generic gets written, a check blocks it, the cause gets hunted	medium
Duplicated rules	the shared style block is copy-pasted into every file of the set and rides along in every context	medium
Re-reading	a file that was just written gets read back to "verify"	small but constant

source              what happens                                   share
──────────────────  ─────────────────────────────────────────────  ───────
reconnaissance      types, paths, signatures re-discovered         largest
full re-runs        whole suite + linter over the whole repo       large
rework              an iteration fails acceptance, written twice   large
guard trips         a copy of an existing generic gets blocked     medium
duplicated rules    the style block pasted into every file         medium
re-reading          a just-written file is read back to verify     small

Two of those are worth calling out because they look like diligence:

Full re-runs. An iteration that touches one package does not need the whole suite. It needs go test ./internal/<package>/... -race -count=1. The full run - formatting, vet, linter, everything with -race, structure checks - happens once, by me, at the end of the stage. Running it per iteration feels responsible and costs a fortune.

Re-reading. Writing a file and then reading it back to check it landed. The edit tool reports its own failures; reading back is pure spend.

The mechanism: a facts section

So the control document for a stage carries a section called Facts, and its job is to make search unnecessary:

exact package paths, and the path of every file that will be created or changed;
full signatures of the types and interfaces the iterations plug into, with import aliases;
the list of existing generics and cross-cutting primitives that must be reused, each with path and signature and the note do not write a copy;
names of error sentinels, env vars, queues, metrics and tables - as values;
the acceptance command, one line, no substitution.

I fill it in before the first iteration runs. That is the one place where reading around the repository is allowed, and it's me doing it. When an executor asks a clarifying question, I don't answer in chat - I add the fact to the section. Answering in chat fixes one executor; adding the fact fixes every executor after it.

The other half of the same rule: the shared style block lives in exactly one document. Iterations reference it in one line instead of repeating it. When a rule changes, it changes in one file. I learned that one the hard way, having pasted the same block into fifteen files and then needing to change it.

The same task, two ways

Anonymised, but this is the real difference in shape.

Before - three lines, and every one of them delegates a search:

Move the entity reads onto the shared read core.
Look at how the neighbouring domain does it and follow the same pattern.
Run the tests.

After - the same work, nothing left to find:

Files (closed list):
  change: internal/repository/order/methods/list.go
  change: internal/repository/order/methods/list_test.go

Plug into (do not write a copy):
  internal/repository/rows.Reader[In, Out]
    fields:  executor, statement, scanner
    method:  Query(ctx context.Context, in In) (Out, error)
    import:  rows "<module>/internal/repository/rows"

Values:
  sentinel on empty result: order.ErrNotFound
  wrap format:              "list orders: %w"

Read only these files: internal/repository/order/methods/list.go,
                       internal/repository/order/methods/list_test.go

Acceptance: go test ./internal/repository/order/... -race -count=1

The second version is longer to write and shorter to run. It is also checkable: I can tell whether it was followed without reading the diff carefully, because the file list and the acceptance command are both facts.

BEFORE                                  AFTER
"move the reads onto the shared core"   closed list: 2 files + 1 signature
        │                                        │
        ├──▶ pkg a                               │        pkg a
        ├──▶ pkg b                               │        pkg b
        ├──▶ pkg order                           └──────▶ pkg order
        ├──▶ pkg d                                        pkg d
        ├──▶ pkg e                                        pkg e
        └──▶ pkg f                                        pkg f
  every executor pays the search again    the fact is written once

What it costs

Writing tasks this way is not free, and I'd rather say so than pretend.

Someone has to collect the facts, and that someone is me, by reading the code. On a stage of thirteen iterations that's an hour of my time before anything starts. On a stage of forty it's more. If the work is a one-off fix in a file I already have open, the whole apparatus is pure overhead - I just do it.

It also only works where the conventions are rigid enough to be written down. In this codebase the layout is fixed to the point of being boring: one method per file, reads and writes in separate layers, a hard file-size limit, no comments in code. That rigidity is what makes a task specifiable in a page. In a codebase where every module has its own shape, there's nothing stable to write down, and the executor genuinely does have to look around - which is a statement about the codebase, not about the executor.

The part that generalises

The uncomfortable thing is that none of this is specific to models. A task with exact paths, named signatures, forbidden shortcuts and one runnable acceptance command is a good task for a person too. The reason it shows up now is scale: a human executor absorbs a vague task and quietly does the reconnaissance for free, once, and remembers it. A fresh executor does it every time and hands you the bill.

Speed only helps when correctness is visible without running the thing. That's the discipline that gets amplified - and the lack of it is what gets exposed.

Working with agents - Part 1.

Next: how far a task gets split before it stops being splittable - and the tell that says an iteration is still too big.

Controlled and Imperfect Beats Perfect and Foreign

Anton Brilliantov — Thu, 03 Sep 2026 09:55:43 +0000

The code you can change today is worth more than the code you cannot.

👋 I'm Anton - a software engineer working mostly in PHP/Symfony and Go, currently carving Go
services out of a live PHP monolith. This is the last part of a block about the platform, the
service template and generated skeletons, and I want to close it with the one idea that decided
most of the calls in it. Maybe it is useful to you; maybe you look at this the other way round and
I'd like to hear that. Notes: github.com/brilliant-almazov.

As with every part of this series: this is what I do on one codebase, not advice for yours.

The thesis

Between a decision I can change today and a decision that is better but changes on someone else's
release, I take the first one. Not because it is written better - it usually isn't - but because
the cost of changing it is known in advance. "Foreign" here doesn't mean bad. It means not moved
by me: a shared library, a platform package, a dependency with its own release cadence. Those are
often the better piece of code. They are also the piece whose change window I don't own.

Where the rule shows up in the layout

Universal code is born in a service, because that's where you can see it is needed, and it lives
in the platform. That gives three phases, and they are deliberately two different bodies of work:

Phase A - preparation, inside the service. No imports of any domain package, the public API frozen, tests moved into the concern's own subfolder, a context-cancellation test present. Closed by a green run in the service's own repository.
Phase B - the move into the platform. Files relocate, the package name becomes the target folder's name, service imports are cleaned out. Only on a direct instruction from the platform's owner.
Phase C - the service switches to the platform version. Exactly the given tag goes into the modules, the local package is deleted, imports are replaced. No pseudo-versions, no replace. No tag - the work doesn't start.

Phase C is a separate set for one reason: it is only executable after the tag exists, and tags are
placed by one person. So the rule falls out of the layout on its own. While the package is still
ours, a fix is minutes: edit the file, run that package's tests. After the move, the same fix waits
for a tag.

That is the whole trade, and it is why a package stays in the service until it has proven it is
universal - not until it looks universal.

┌────────────────────────────┐   ┌────────────────────────────┐
│ own package in the service │   │ moved to the platform      │
│                            │   │                            │
│ ├────────────────────────┤ │   │ ├────────────────────────┤ │
│ change: minutes            │   │ change: waits for a tag    │
│                            │   │              │             │
│                            │   │              ▼             │
│                            │   │ ┌────────────────────────┐ │
│                            │   │ │ tag — one person       │ │
│                            │   │ └────────────────────────┘ │
└────────────────────────────┘   └────────────────────────────┘
              same code, different change window

How the control is actually held

Control at that scale is not a principle, it's a unit of work. The unit is an iteration: one
concern, which in practice means one code file - sometimes two of the same shape - plus the test
that covers it. If it doesn't fit in one pass, it becomes two iterations. It does not become one
long iteration.

The tell that an iteration is still too big is not its size:

The executor had to go looking for something.

Which rules out a whole family of tasks that read as perfectly reasonable: "walk the path and fix
every step where the value is lost", "find where it breaks", "work out how it's done here and
follow it", "by analogy with the neighbouring domain". Each one makes the executor discover
something first. So the path gets walked before the task is written, and what goes into the
task is the finished list - files, values, the command to run.

Batches, and stopping at any point

A batch is one executor, one pass, and the iterations inside it run strictly in order. Batches
inside a wave touch no shared files, so they run at the same time. The set that moved one service
onto the platform runtime was 13 iterations:

Batch	Iterations	Wave
A	02 → 03 → 04 → 05	1
B	06 → 07 → 08	1
C	09 → 11 → 12	2
D	10 → 13	2
E	01	3

Wave 2 starts once both batches of wave 1 are closed; wave 3 after wave 2, because iteration 01
leans on the results of 05 and 07.

The commit goes in at the batch boundary. No batch is left uncommitted - which is the part that
matters here: the work can be cut off at any boundary without losses, and nothing important is
sitting in my head.

WAVE 1  ┌───────────────────────┐  ┌───────────────────────┐
        │ A  02 → 03 → 04 → 05  │  │ B  06 → 07 → 08       │
        └───────────────────────┘  └───────────────────────┘
                    │                          │
                    ▼                          ▼
WAVE 2  ┌───────────────────────┐  ┌───────────────────────┐
        │ C  09 → 11 → 12       │  │ D  10 → 13            │
        └───────────────────────┘  └───────────────────────┘
                    │
                    ▼
WAVE 3  ┌───────────────────────┐
        │ E  01                 │
        └───────────────────────┘

        commit at the batch boundary

What it looks like in numbers

Real set sizes from the last few stages: a set of 13 iterations (moving off hand-written
runtime), a set of 12 (a skeleton generator), and a set of 40 - that one converts
forty-four copies onto a single generic core, one file per iteration.

A typical iteration is 15 to 35 minutes of executor work: 15 minutes for a schedule read from
config, 35 for a typed subscription. That's the whole reason the boundary is cheap. Losing an
iteration costs half an hour, not a day.

The honest boundary

Part of what I just described is a plan, not a result, and control includes being able to say which
part:

The skeleton generator is not written. There is a written set of 12 iterations for it and a rule not to start without a direct instruction.
The sets "move to the platform" and "apply the platform" are written and queued, not executed. Their phases are a plan; their times are estimates.
The coverage gate is at 0. The ratchet exists and can only go up, but the bar has not been raised yet. Actual coverage is 86.7%.

DONE                             PLANNED
─────────────────────────        ┌──────────────────────────────┐
 the layout                      │ skeleton generator           │
 the generic cores               │ move to platform             │
 the audit                       │ apply platform               │
 the snapshots                   │ coverage gate                │
                                 │   threshold 0 · actual 86.7% │
                                 └──────────────────────────────┘

What it costs

More writing. Forty iterations means forty written tasks, and on a simple stage writing the set
takes longer than the code it produces. All of that happens before anything runs.

A slower start. The first visible result arrives later than it would if I just went at the code in
sweeps - and for a while that feels like the wrong call, right up to the first interruption.

And it doesn't pay at all on a one-off fix. One file, one change, one afternoon: writing a
specification for that is pure overhead, and I don't.

The one conclusion

Choose by the cost of changing a decision, not by the quality of the decision.

That's my experience and my price for it, on one codebase, over a few months. If you do this
better, if you've already been through it, or if you look at it the other way round - I'd like to
hear how it's solved on your side, and what broke when you tried.

Platform and generation - Part 7. That closes this block: the layout, what the platform owns,
the audit, the generic cores, code moving both ways, the generator, and now the rule underneath all
of them.

Next block - operations out of the box: what changes when the manifest is the only place a service
declares itself.

Generating the Service Skeleton

Anton Brilliantov — Wed, 02 Sep 2026 12:02:57 +0000

The generator is written once, in code - everything but the business logic comes out of it.

👋 I'm Anton - a software engineer working mostly in PHP/Symfony and Go, currently carving a live PHP monolith into Go services. This part is about one tool I have specified: a generator that produces the skeleton of a new domain. Maybe the idea is useful to you, maybe you look at it differently - both are interesting to me. Notes: github.com/brilliant-almazov.

The generator does not exist yet. What exists is a specification split into 12 iterations and a standing rule that none of them starts without an explicit go-ahead. So this is a piece of designed work and the shape I chose for it, not a report on a working tool. Everything below is in the future tense on purpose: there is no "we generate" here, only "it will generate".

The thesis

Basic things should be generated by code, not by a model. A model writes the generator once; from
then on it is an ordinary binary - no tokens, no session, and no chance that the layout comes out
slightly different on the fifth domain than it did on the first.

Why this is possible here at all

The layout and the style are already fixed, hard. Packages go by component type with the domain as
a nested package; reads and writes live in two separate layers; a concern is expressed by a folder,
never by a prefix in a file name; a file stays under 100 lines. As of the last count that is
2733 Go files across 252 packages, average file 39 lines.

That rigidity is the whole precondition. A formalised layout is the only thing that makes
generation possible: the generator does not guess the style, it lays files out by rule. Where the
rule is a matter of taste, nothing can be generated - only suggested.

A second effect comes from the same order: the more behaviour has been pulled into generic cores,
the less there is left to generate. The generator writes wiring; the behaviour is already in the
core it wires to.

The shape of the tool

A library with two functions, plus a thin CLI on top:

Generate(cfg) (Result, error)
CheckDrift(cfg) ([]string, error)

Not a script, not a folder of templates you copy and rename. A library, because the second
function - "tell me whether what is on disk still matches" - has to run in CI.

Two inputs, and neither covers the skeleton alone

The first input is a YAML description of the domain: domain name and plural, Go types, the
account-scope flag, whether there is a slug, whether there is a batch, the header table, the
revision table, the link column, the label column, table aliases, the payload columns (Go type, SQL
type, NULL, comment), the domain event types, the set of error sentinels, and the number of the
first migration. The second is the .proto descriptor: the full gRPC service name, the list of
RPCs with their request and response types, the entity message, the batch messages.

Neither is enough on its own. The descriptor knows the wire contract and nothing about storage; the
YAML knows the tables and nothing about which RPCs exist.

┌────────────────────────┐      ┌────────────────────────┐
│ domain.yaml            │      │ proto descriptor       │
│                        │      │                        │
│  name + plural         │      │  service name          │
│  Go types              │      │  RPC list              │
│  account scope         │      │  request types         │
│  slug / batch          │      │  response types        │
│  header table          │      │  entity message        │
│  revision table        │      │  batch messages        │
│  link column           │      └────────────────────────┘
│  label column          │                   │
│  table aliases         │                   │
│  payload columns       │                   │
│  event types           │                   │
│  error sentinels       │                   │
│  first migration       │                   │
└────────────────────────┘                   │
             │                               │
             └───────────────┬───────────────┘
                             ▼
                   ┌───────────────────┐
                   │     generator     │
                   └───────────────────┘
                             │
                             ▼
         ┌───────────────────────────────────────┐
         │            service skeleton           │
         └───────────────────────────────────────┘

Rendering is string concatenation

Constant fragments, a string builder, token replacement - $domain$ , $Domain$ , $plural$ .
Template engines are explicitly ruled out. Every .go output is then run through the formatter, so
alignment and import grouping are not the renderer's problem at all.

The reason is narrow: a template hides the structure of its output behind its own syntax, and here
the output is the thing under review. When a generated file looks wrong, I want to read the code
that produced it as code.

Fully generated versus a manual body

Not everything can be generated, and pretending otherwise is how generators get abandoned. Each
layer is split in advance into what comes out complete and what comes out as a signature:

Layer	Fully generated	Manual body
domain handlers	all 5 files	none
domain codecs	`codec.go`, `mapping.go`, `request.go`, `request_patch.go`, `suite.go`, `base.go`	`payload.go`, `filter.go`, `errors.go`
domain repository	`calls.go`, `repository.go`, `revision.go`, `deps.go`, `methods/search.go`, `methods/find_all_by_ids.go`	`spec.go`, `methods/header.go`, `methods/code_taken.go`, `methods/slug_taken.go`
domain manager	`calls.go`, `deps.go`, `manager.go`, `methods/{create,update,correct,archive}.go`	`spec.go`
domain model	9 files	6 files
domain wiring in the daemon	all 4 files	none
domain test rig	all 3 files	none
migrations	all	none

A "manual body" file is still generated once: correct package, correct imports, correct
signatures, bodies marked with a panic stub. On a second run without -force it is not
overwritten. The generator owns the shape, a person owns the decisions, and it never eats the
second one.

Drift

Every generated file will carry a Code generated by … DO NOT EDIT. header. That header is a
contract, not a courtesy. The comparison mode regenerates into memory, compares against what is in
the repository, and exits non-zero on any difference. Editing a generated file by hand is
forbidden; if the generated shape is wrong, the generator changes.

         ┌──────────────────────────────────────┐
         │   Code generated by … DO NOT EDIT.   │
         └──────────────────────────────────────┘

┌────────────────────────┐  =?  ┌────────────────────────┐
│ generated in memory    │      │ file in the repository │
└────────────────────────┘      └────────────────────────┘
                             │
              ┌──────────────┴──────────────┐
              ▼                             ▼
    ┌────────────────────┐       ┌─────────────────────────┐
    │   equal → exit 0   │       │ differs → non-zero exit │
    └────────────────────┘       └─────────────────────────┘

What it will not touch

The generic cores, and anything that exists once per service rather than once per domain -
publishers, the cache-invalidation consumer. They are not a unit of generation, and a generator
that tries to own singletons ends up owning the whole service.

The order of work

Twelve iterations: the YAML format first, then reading the proto descriptor, then the generator
frame, then one iteration per layer, then the comparison mode last - there is nothing to compare
until something is produced.

What it costs

A generator is another product: its own bugs, its own tests, its own review, and it has to keep up
with every change to the layout it encodes - which means the layout stops being free to change
casually.

The DO NOT EDIT header means a quick fix by hand is off the table. Every exception costs a new
iteration of the generator, and the first time that happens under time pressure is when the
decision gets tested for real.

And the double input has to be kept in agreement by someone. Two sources of truth for one skeleton
is a real cost; I took it because collapsing them would mean either inventing storage facts from
the wire contract or duplicating the contract in YAML.

The one conclusion

Generate the things that are already decided; write by hand the things that are still decisions.
The dividing line is not "how complex is this file" - it is "does this file contain a choice".

Platform and generation - Part 6.

Next: controlled versus ideal - why I keep choosing the version I can predict over the version that
is better on paper.

That's my case and my price for it. If you do this better, if you've already been through it, or if
you look at it differently - I'd like to hear how it's solved on your side, and what broke when you
tried.

Code Moves Both Ways

Anton Brilliantov — Tue, 01 Sep 2026 14:11:57 +0000

Generic code is born in a service, lives in the platform, and comes back as a tag.

👋 I'm Anton - a software engineer working mostly in PHP/Symfony and Go, currently carving a live
PHP monolith into Go services. This part is about one small piece of that: how code that turns out
to be generic gets from a single service into the shared platform library, and how it comes back.
Maybe it's useful to you, maybe you already do it better, maybe you'd cut it differently. Notes:
github.com/brilliant-almazov.

As usual: this is what I'm doing on one codebase right now, with the reasons and the price - not a
recommendation for yours.

The claim

You cannot design generic code in the platform up front. Sitting in the platform, you can't see
whether anyone needs it: there's no second caller, no second shape, nothing to generalise from. So
the generic thing is born where the need is obvious - inside a service, solving one concrete
problem - and only later moves out.

The move back is the part that surprised me. A service dropping its local copy and importing the
platform version is not the tail end of the move out. It is separate work, and the reason is
the tag: until the platform release exists, that work cannot start at all.

Phase A — prepared in the service

Nothing leaves the service yet. The package stays where it is and keeps working; what changes is
that it stops being local in every way except its address:

not a single import of a domain package;
the public API is fixed - the names it will keep after the move;
tests moved into the concern's own subfolder;
there is a context-cancellation test.

Phase A closes on a green run in the service repository. Nothing about the platform is touched, and
if the move never happens, the service is still better off.

Phase B — moved to the platform

The files move. The package name changes to the name of the target folder, and any leftover imports
of the service are cleaned out. That's the whole of it - a relocation, not a redesign, because the
design was already frozen in phase A.

One condition on top: this happens only on the direct instruction of the platform owner. The
platform is not a place anyone drops code into because it looked reusable.

Phase C — the service switches to the tag

The service now has two copies of the same thing - its own, and the one in the platform. Phase C
removes that:

the module file gets exactly the tag that was given - not a nearby one, not a resolved one;
pseudo-versions and replace directives are forbidden;
the local package is deleted;
the imports are swapped.

If the tag doesn't exist yet, the work doesn't begin. The answer is one line: waiting for the tag.
Not "let me pin a pseudo-version so the build is green in the meantime" - that turns a blocked task
into a silently wrong one, and the difference stops being visible in the diff.

Why C is a separate set, not the tail of B

Because C is executable only after the tag is cut, and tags are cut by one person.

That's a different kind of dependency from "this iteration needs that iteration". A set that stops
halfway and waits for someone else's action is in a bad state: half-applied, half-reviewable,
occupying attention. A set that hasn't started because its precondition doesn't exist is in a fine
state - it's just queued. Same waiting, very different cost, and the only way to get the second one
is to draw the boundary exactly where the external dependency sits.

◀── set 1 ────────────────────────────────▶ ╎ ◀── set 2 ─────────▶
┌──────────────────┐   ┌──────────────────┐ ╎ ┌──────────────────┐
│ A — prepared in  │   │ B — moved to the │ ╎ │ C — switches to  │
│     the service  │──▶│     platform     │ ╎ │     the tag      │
└──────────────────┘   └──────────────────┘ ╎ └──────────────────┘
 no domain imports      files relocate      ╎  exactly that tag
 public API frozen      package renamed     ╎  no pseudo-version
 tests in own folder    service imports out ╎  no replace
 cancellation test      owner's go-ahead    ╎  local copy deleted
 green run in repo                          ╎  imports swapped
                                            ╎
                                     waits for a tag

What actually moves

Seven units. None of them were written to be generic; each one earned it by being needed twice.

#	What moves	What it is
01	task running	serial and parallel `Runner[T]`
02	pagination	keyset cursor + page-size clamp
03	row reading	generic reads of arbitrary projections + collectors
04	checks	`Rule[In]` / `Guard[In,Out]` / `Each[In]` / `Nullable[T]`
05	metric ports	`Factory` / `Gauge` / `Counter` / `Histogram` / `Spec`
06	migration source merging	several embedded filesystems into one source
07	publish-target selection	exchange or queue, by the suffix of the name

Read the list from the other end and it's a decent description of what a platform library is for:
none of these are business decisions. Not one of them knows what the service does.

Estimates, not a report

To be explicit before the numbers: both sets - moving out, and switching over - are written and
queued. Neither has been executed. What follows is an estimate, not a measurement.

Set	Estimated work	Calendar with two executors
phase A, 7 units	2 h 50 min (20–30 min per unit)	≈1 h 30 min
phase B, 7 units	1 h 25 min	—

Phase C has no estimate here, and that's the honest version: it can't be scheduled against a tag
that hasn't been cut.

What it costs

Three things, and I'd rather name them than discover them later.

The package lives in two places for a while. Between B and C the service still runs its local
copy while the platform carries the moved one. Any fix in that window has to be made with both in
mind, or made twice.

The switch depends on someone else's release. That's the whole point of the split, but it's
still a cost: the finish line of the work isn't mine to cross.

"Generic" is checked by hand. The rule I use - it has to have been written twice before it
counts - is a judgement call, not a test. Until a package has genuinely been needed by a second
caller, moving it is a guess, and a guess in the platform is more expensive than a guess in a
service.

The one conclusion

The platform gets only what has already proved useful in a service; everything else stays in the
service until it has.

That's my current setup and my current price for it. If you do this better, if you've already been
through it, or if you look at it differently - I'd like to hear how it's solved on your side, and
what broke when you did it.

Platform and generation - Part 5.

Next: the skeleton generator - why the boring parts of a new service should be produced by code
rather than written by hand each time.

One Generic Core Instead of Many Copies

Anton Brilliantov — Mon, 31 Aug 2026 09:57:02 +0000

If only the type parameter differs, it is one generic — and the numbers show it.

👋 I'm Anton — a software engineer working mostly in PHP/Symfony and Go, currently carving a live
PHP monolith into Go services. This part is about one rule I now apply before writing any new type,
and what happened to the line counts when I applied it to a service that was already working.
Notes: github.com/brilliant-almazov. None of it is advice
for your codebase — one service, one audit, one set of measurements: possibly useful, possibly wrong
for your situation.

What the audit actually counted

I audited one of the Go services with a single question: where does it carry code that already exists
somewhere else in the same tree? The largest finding wasn't a bug — it was a count. 44 copies of
four row-reading shapes, on 2026-08-13:

Shape	Copies
loop over many rows (`for rows.Next()` → `rows.Err()` → error wrapper)	18
read a single row	6
`COUNT(*)` counter	8
existence probe (one `rows.Next()`)	12
total	44

Of those 44, 12 differed only in the text of the error wrapper — not in behaviour, not in the
query. None of them was bad code: every one was correct, reviewed, tested and running. They were
identical, and being identical is not something a reviewer flags, because each arrives alone, in its
own change, next to its own domain. Lined up, they differ by the result type and the dependency.
That's a generic, written by copy-paste.

The rule, in one line

If only the type parameter differs, it is one generic.

The corollary is what actually holds the line: a domain-local copy next to an existing generic is
forbidden — not discouraged, and enforced by tooling checks plus tests whose only job is to fail
when the copy comes back. For the read core the closing criterion is mechanical, so a test can own
it: for rows.Next(), rows.Err(), rows.Close() and QueryRow( occur in exactly one package
in the tree. Either the grep is clean or the build is red.

Why a test and not an agreement: the correct shape was already in the tree. A Reader[In, Out]
existed, with the right fields and the right method — inside one domain package, where nobody outside
that domain found it, so everyone outside it wrote their own. A generic living in a domain package
is, for practical purposes, not a generic.

  Four shapes, one core

  loop over many rows    18 ──┐
  single-row read         6 ──┤     ┌───────────────────────────┐
  COUNT(*) counter        8 ──┼──▶  │ Reader[In, Out]           │
  existence probe        12 ──┘     │ executor                  │
                                    │ statement                 │
  44 copies · 12 differ only        │ scanner                   │
  in an error string                └───────────────────────────┘

What the core looks like

The core is deliberately small. Three fields and one method:

type Reader[In, Out any] struct {
    executor  Executor
    statement Statement[In]
    scanner   Scanner[Out]
}

func (r Reader[In, Out]) Query(ctx context.Context, in In) (Cursor[Out], error)

executor runs the query — a pool or a transaction-scoped handle. statement turns typed input into
SQL plus arguments. scanner turns one row into one Out. Around that sit the collectors: a set, a
counter, an existence probe. Before, each domain owned its own loop instead:

// one of eighteen
func (r *entityRepository) List(ctx context.Context, in ListInput) ([]Entity, error) {
    rows, err := r.pool.Query(ctx, listEntitiesSQL, in.AccountID, in.Limit)
    if err != nil {
        return nil, fmt.Errorf("query entities: %w", err)
    }
    defer rows.Close()

    out := make([]Entity, 0, in.Limit)
    for rows.Next() {
        var e Entity
        if err := rows.Scan(&e.ID, &e.Name); err != nil {
            return nil, fmt.Errorf("scan entity: %w", err)
        }
        out = append(out, e)
    }
    return out, rows.Err()
}

The order version was the same function with Order in place of Entity and a different string in
the error wrappers. After, both domains are two calls into one core:

entities := reading.NewSet(executor, listEntities, scanEntity)
orders := reading.NewSet(executor, listOrders, scanOrder)

es, err := entities.Query(ctx, ListInput{AccountID: id, Limit: 50})
ords, err := orders.Query(ctx, ListInput{AccountID: id, Limit: 50})

Each domain still owns what is genuinely its own — the statement and the scanner. What it no longer
owns is the loop, the defer, the rows.Err() check and the error wrappers that were being retyped
by hand every time.

The cores that exist besides reading

Reading is one row in a longer list. The current set in that service — twenty generic RPCs reads as
a lot until you notice that adding an entity means naming its spec, not writing twenty handlers:

Core	What it gives
generic RPC (20 of them)	`archive`, `attach`, `close`, `correct`, `create`, `create_batch`, `detach`, `find_all_by_ids`, `get`, `get_by_key`, `list_revisions`, `lookup`, `lookup_pair`, `move`, `mutation`, `save`, `search`, `set`, `update`, `walk`
codecs	`Shape`, `Selector`, `NewUnary`, `NewCollection`, `NewPaging`, `NewPairing`, `Suite`, `Spec`, `BatchSuite`
entity repository	`Base`, `Spec[H, P, V]`, `Calls`, `ScopedCalls`, `Search`, `FindAllByIds`, `Reader[In, Out]`, cursors
entity manager	`Base`, `Spec`, `Calls`, `ScopedCalls`, `Manager`, `methods/`
history	`Revisioned[T]`: `Current` / `AsOf` / `KnownAsOf` / `Append` / `Correct` / `Close` — one shape for the whole service
row reading	set, counter, existence probe, `Reader` with collectors
pagination	keyset cursor over `int64` plus a clamp on page size
domain assembly	`Builder[Repo, Mgr]`, `Domain[Repo, Mgr]`, `New`, `Input`, `ManagerInput[Repo]`, `HandlerInput[Repo, Mgr]`
task running	`Runner[T]`: serial and parallel
checks	`Rule[In]`, `Guard[In, Out]`, `Each[In]`, `Nullable[T]`
ports	`Scoped[T]`, `Self[T]`, `Creator`, `Updater`, `Corrector`, `Archiver`, `Viewer`, `Finder`, `Locator`, `Searcher`, `Historian`
test rig	scoped `Rig`, `Spec`, `StubManager`, `StubRepository`, `Port`, `NewItem`, `NewPatch`, `KeepData`

What the numbers did

I measure line counts at every tag by walking the tag history, generated code excluded. The move
onto generic cores lands on one tag, v1.0.0:

	`v0.4.0`	`v1.0.0`
lines of code	28095	25097
lines of tests	31952	35368
tests / code	1.14	1.41
code files · packages	640 · 85	683 · 94
average file	43 lines	36 lines

Code went down while the service went up. Three thousand lines left, and both the file count and
the package count rose — no feature dropped, the same behaviour in fewer lines over more files.

Tests went up — the part I'd have got wrong if I'd guessed. Collapsing 44 copies onto one core
does not collapse 44 test files with them: the core earns a suite of its own, and each domain keeps
the tests describing its statement and scanner. The ratio went 1.14 → 1.41, and across the whole tag
series it has moved from 0.45 at the first tag to 1.25 at head, never below 1.14 after v1.0.0.

Average file size dropped to 36 lines, and from there the service grows by files and packages
rather than by files getting longer. The most recent release added 1392 lines of code, 1767 lines of
tests and 20 packages — the read core plus the SQL catalogue engine, with their tests. Nothing here
measures speed, latency or defect rate; I didn't measure those, so I'm not claiming them.

Telling real commonality from a shape that merely rhymes

The rule is easy to over-apply, and over-applying it is worse than the copies.

Real commonality: the difference reduces to a type parameter and a dependency, and the behaviour
matches literally — not "roughly", not "with one flag". Line the two up and the only thing your eye catches
is the type name.

Accidental similarity: two places share a shape today and diverge on the first new requirement.
The tell is that you can already name the requirement that would split them — if you can, leave them
alone, or you'll be adding a boolean to the core within a month, and a core with behaviour flags is
worse than the two copies it replaced. The 44 gave an unusually clean signal here: 12 differed only
in error-wrapper text. When the delta between two implementations is a string constant, no
requirement is waiting to split them.

What it costs

None of this is free, and the costs are all paid in readability:

Signatures get longer and read worse. Reader[In, Out] with three typed dependencies is more to take in than func List(ctx, in) ([]Entity, error).
Compiler errors on generics are verbose — a mismatch three layers into a parameterised core produces a message you sit and parse.
Tooling handles type parameters less well than concrete types, and some of it degrades quietly.
Jump-to-definition lands in the core, not the domain. You can no longer understand one behaviour by reading one file — a real, permanent loss. The copies were worse in aggregate, better in isolation.

I'd take that trade again on this service. On a service with three read sites instead of forty-four,
I wouldn't. That's my experience on one codebase and my price for it, and I'd like to hear the other
side: if you do this better than I do, if you've been through it already, or if you look at it
differently — how is it solved in your codebase, and what broke when you tried?

Platform and generation — Part 4.

Next: what happens when the universal code stops living in the service — how it moves into the
shared platform library and comes back as a tag.

Auditing Your Own Runtime

Anton Brilliantov — Sun, 30 Aug 2026 05:20:05 +0000

Ten findings from one question: where does this service still ship its own runtime.

👋 I'm Anton - a software engineer working mostly in PHP/Symfony and Go, currently carving a live
PHP monolith into Go services. Part 2 of this series was the list of what the shared platform
library hands a service for free. This part is what happened when I turned that list into a single
question and walked the tree with it. Notes:
github.com/brilliant-almazov.

Some of this may be useful to you. Some of it you may cut differently, and I'd be glad to hear how.
These are findings from one codebase, not advice for yours.

The question

I did not go looking for bad code. I asked one question of the whole tree - 2733 Go files across
252 packages - and wrote down every place that answered yes:

Where does this service still carry code that the platform already provides?

No "good" or "bad" attached to any answer. Just a list. Ten entries came back, plus one that turned
out to be big enough to get its own section.

Two of the ten were not about style. They were about behaviour that was already wrong in
production, in a service whose tests were green.

The two that were behaviour

1. A consumer that is written and never started.

The cache-invalidation consumer exists. It has a package, it has logic, it has unit tests, and
those tests pass. What it does not have is a subscription registered in any daemon. Nothing ever
starts it. In production, invalidation does not run at all.

Nothing caught this. The package compiles - that's what a compiler checks. The unit tests exercise
its logic in isolation - that's what a unit test checks. Neither of them asks whether the component
is wired into a running process.

  DAEMONS
  ┌────────────────────────┐     ┌────────────────────────┐
  │ server                 │     │ worker                 │
  │ grpc handlers          │     │ relay · retention      │
  └────────────────────────┘     └────────────────────────┘


              ┌──────────────────────────────────────┐
              │ cache invalidation consumer          │
              └──────────────────────────────────────┘
              compiles · unit tests green · never registered

2. Publishing with empty headers.

The service publishes messages without setting headers. The consuming side picks its codec from a
header, so with no header there is nothing to dispatch on: the platform's typed receive path is
physically inapplicable. The consumer is left calling JSON decoding by hand, which is exactly the
hand-rolled runtime the audit was looking for - except here it wasn't a preference, it was forced
by the publisher.

What these two share: the code exists, the tests are green, the behaviour is absent. Compilation
and unit tests do not check that a component is connected to anything.

The other eight

The rest of the list, one line each, no verdicts:

The subscription sets no redelivery limit, no backoff and no dead-letter queue; a decode error is returned as an ordinary error, so the driver redelivers it - a poison loop.
Message deduplication is a hand-written ring of 1024 ids, instead of the platform cache with TTL and metrics.
Three hand-written caches, each a map plus an RWMutex: no TTL, no capacity bound, no metrics.
Bulk insert issues one INSERT per row instead of a multi-row VALUES.
Two different loggers, in two packages of the same service.
One repository runs its own transaction loop: Begin by hand, pgx.Tx held as a field, around the registry rather than through it.
The retention schedule is a constant in the code instead of a value from configuration.
The scheduler initialises lazily through sync.Once over captured variables, instead of the platform's init-state store.

Every one of these has a platform package that does the same job with metrics attached. None of
them was written out of disagreement with that package. They were written because writing them was
the shortest path at the moment, and nothing later asked the question.

Forty-four copies of four shapes

Then there was the finding that didn't fit on one line. Counted on 2026-08-13, the tree contained
four shapes of "read rows from the database", copied by hand:

Shape	Copies
loop over many rows (`for rows.Next()` → `rows.Err()` → wrap the error)	18
fetch a single row	6
`COUNT(*)` counter	8
existence probe (a single `rows.Next()`)	12
total	44

Of those 44, twelve differ from one another only in the text of the error wrapper.

Why this is a generic, written by copy-paste

Look at what actually varies between the copies. The result type varies. The wrapper text varies.
That is it.

A varying result type is a type parameter. A varying error wrapper is a dependency. Forty-four
copies that differ only in a type parameter and a dependency are not forty-four pieces of code -
they are one generic, typed out forty-four times.

The uncomfortable part: the correct shape was already in the tree. Reader[In, Out], with fields
executor, statement and scanner, and a single method Query(ctx, in). It existed, it worked,
and it was sitting inside one domain package - where nobody writing the forty-fifth copy would go
looking for it.

  many rows loop     18 ──┐
  single row          6 ──┤     ┌──────────────────────────┐
  count               8 ──┼──▶  │ Reader[In, Out]          │
  existence probe    12 ──┘     │ executor                 │
                                │ statement                │
  44 copies in the tree         │ scanner                  │
  12 differ only in the         │ Query(ctx, in)           │
  error wrapper text            └──────────────────────────┘

A generic that lives inside a domain package is invisible. Being written is not the same as being
reachable.

The closing criterion

"Rewrite it properly" is not a criterion. It has no state in which it is finished, so it never is.

The criterion I used instead is a grep with a fixed answer:

for rows.Next(), rows.Err(), rows.Close() and QueryRow( occur in exactly one package
in the tree.

That is checkable by anyone, at any moment, without knowing the history. And it is not checked by
hand: the work is closed by a forbidding test that stays in the repository and fails the moment a
forty-fifth copy appears anywhere else.

The rule this leaves me with

There is a ladder, and only the top rung holds:

reminder  → lives for one session
rule      → works while someone is reading it
check     → works whether or not anyone remembers it

A reminder in a chat thread is gone when the thread is. A rule in a style document works as long as
people read the document, which is a decaying function. What actually holds is a check: a linter, a
forbidding test, a structure test, a hook that blocks the write.

Which turns the audit itself into a much smaller claim than it looks. An audit without a forbidding
test at the end is a one-off tidy-up. The copies come back, because the conditions that produced
them - a shortest path, no question asked - are unchanged.

What it costs

Two things, and neither is small.

The audit is manual. There is no tool that finds "runtime this service should not own", because
hand-rolled runtime does not look like a defect. It looks like ordinary working code: readable,
tested, doing its job. The signal isn't in any one file - it's that the same shape appears in
places that never talked to each other. Finding that means walking the tree with the question in
your head.

Forbidding tests add noise. Every one of them is a test that fails for reasons unrelated to
what the code does, and sometimes it catches a legitimate exception - a place where the pattern
genuinely belongs. Then you either widen the test or argue with it, and both cost time. I still
keep them, because a rule that nobody enforces costs more, later, and quietly.

Your turn

That is what one question found in one service tree, and what I chose to pay to keep the answer
from drifting back.

If you do this better than I do - a check that catches it earlier, a cheaper way to spot the
copies - I'd like to hear it. If you've been through this and it went differently, that's the more
interesting story. And if you look at it differently and think the forbidding tests are the wrong
trade, say so.

How is this solved on your side, and what broke while you were solving it?

Platform and generation - Part 3.

Next: the read core that replaced all forty-four copies - one generic instead of four shapes, and
what the conversion actually took.

The Platform Owns the Runtime

Anton Brilliantov — Thu, 27 Aug 2026 09:46:42 +0000

The service writes input, processing and output - everything else is an import.

👋 I'm Anton - a software engineer working mostly in PHP/Symfony and Go, currently carving a live PHP monolith into Go services. This part is about one rule I now apply to every new service: where the line runs between what the shared platform gives me and what the service is allowed to write. Maybe it's useful to you; maybe you draw that line somewhere else. Notes: github.com/brilliant-almazov.

As always: this is what I'm doing right now on one codebase, with the reasons and the price - not advice for yours.

Where the line actually runs

For a long time I drew the line in the wrong place: our code on one side, third-party libraries on
the other. That split explains nothing, because "our code" ends up containing a logger, a cache, a
retry loop and a migration runner - none of which have anything to do with what the service is
for.

The line that holds is between runtime and domain. Process startup, connections,
transport, retries, observability - that's runtime, and it belongs to the platform. The service
writes three things: input (the contract, the codecs, validation), processing (domain
rules and invariants), and output (the storage model and domain events). Everything else is an
import.

What the platform hands over

Fourteen things arrive with the platform dependency, before a line of domain code exists:

What	Where it lives
application startup, graceful shutdown, `/health`, `/ready`, `/metrics`, platform info	the app package
migrations as a declared resource	the migration resource
audit - written inside the same transaction, partitioned schema, build table	the audit package
the outbox runner for outgoing messages	the outbox package
workers and their initialisation state	the worker package and its init-state store
the broker and its driver	the messaging package plus the RabbitMQ driver
transactions - a registry, an executor taken from the context	the transaction package
listing and pagination	the listing package and its result type
cache with LRU eviction, TTL and metrics	the cache package
bulk insert - multi-row `VALUES`, chunked to fit 65535 bind parameters	the statement preparer
typed message consumption	typed dispatch plus a serializer registry
Snowflake identifiers	the id package
test infrastructure - one container per run, a fresh database	the test-infra package
metric registry, tracing, connection-pool instrumentation	the observability packages

Two more things come from the same dependency without being packages the service imports: the
environment-variable and metric snapshots, taken by standalone snapshot binaries, and the build
version and commit, injected into platform symbols by the linker.

            ┌───────────────────────────────────────────────┐
   SERVICE  │   input   →   processing   →   output         │
            └───────────────────────────────────────────────┘
                              │
                              │  everything below is an import
                              ▼
            ┌───────────────────────────────────────────────┐
  PLATFORM  │  startup · shutdown · health · ready · info   │
            │  migrations · audit · outbox · workers        │
            │  messaging + driver · transactions · cache    │
            │  listing · bulk insert · ids · test infra     │
            │  metrics · tracing · pool instrumentation     │
            └───────────────────────────────────────────────┘

None of that is a suggestion the service may take or leave. It's what a service is made of before
it has a domain.

Three of them, spelled out

The table above reads like a list of conveniences. Three entries aren't conveniences, and they're
the ones that convinced me the line is in the right place.

Bulk insert, chunked to fit 65535 bind parameters. A multi-row INSERT ... VALUES is faster
than a loop of single-row inserts, and everyone knows that much. What everyone doesn't carry in
their head is that the wire protocol caps a statement at 65535 bind parameters, so the chunk size
isn't a tuning knob — it's 65535 / columns, recomputed per table. Hand-rolled bulk insert is
therefore correct on the table it was written for and quietly broken on a wider one, at a row
count nobody tests. That's not a performance detail; it's a correctness detail wearing a
performance costume.

Transactions as a registry plus an executor taken from the context. The consequence is a
shape, not a feature: a transaction never appears in a function signature. No tx pgx.Tx
threaded through five call layers, no repository method that only works if the caller remembered
to begin something first. The executor is a field, scoped when the transaction is opened, and the
code that reads and writes doesn't know whether it's inside one. Hand-rolling that is easy;
hand-rolling it consistently across a whole service is where it fails, and the audit of my own
service found exactly one repository that had gone its own way with a manual Begin and a
transaction held as a field, bypassing the registry.

Typed message consumption with a serializer registry. The consumer says which type it wants
and gets it; the codec is chosen from a message header. The property that matters is what happens
when the header is missing — the mechanism doesn't degrade gracefully, it simply cannot be used,
and the consumer falls back to parsing JSON by hand. So a publisher that ships empty headers
doesn't break loudly on its own side; it disables a platform capability on the far side of the
broker, in someone else's code. That's the kind of coupling that only becomes visible when both
ends are owned by the same platform contract.

What you don't write by hand

There is a list, and it's short enough to remember:

cache
retries
typed message consumption
the outbox
configuration
the logger
metrics
migrations

The rule sits in every control prompt I write, in those words: a hand-rolled equivalent of a
platform layer is forbidden; business code, the minimum.

Each line of that list has a specific thing it loses when it's written by hand, and the loss is
never the happy path:

Cache — a map behind a mutex has no TTL, no capacity bound and no hit-rate metric. It works until the working set grows.
Retries — a hand-written loop has no backoff and no redelivery limit, so a message that can't be decoded is retried forever. A decode error returned as an ordinary error is a poison loop with a friendly name.
Typed consumption — replaced by hand-rolled JSON parsing at every consumer, which means the message shape is asserted in as many places as there are consumers.
The outbox — a hand-rolled version usually publishes and deletes without a durable record in the same commit, which is the failure mode the outbox exists to prevent.
Configuration — values become constants. The audit found a retention schedule compiled into the binary, which makes changing it a deploy.
Logger — two different loggers in two packages of the same service, so half the events are shaped one way and half another, and neither half is complete.
Metrics — no registry means no consistent names, and no consistent names means no dashboard that survives a rename.
Migrations — as a declared resource they run in a known order at a known moment; by hand, they run wherever someone remembered to call them.

written by hand      what is lost
───────────────────  ──────────────────────────────────────────
cache                no TTL, no capacity, no hit rate
retries              no backoff, no redelivery limit
typed consumption    the shape asserted at every consumer
outbox               publish and delete outside one commit
configuration        the value becomes a constant
logger               two shapes of event in one service
metrics              no registry, so no name survives a rename
migrations           they run wherever someone called them

Why it's a ban and not a recommendation

The interesting part is that a hand-rolled layer is usually not worse at its job. A map behind a
mutex caches things. A hand-written loop retries. Functionally you can't tell.

It's worse at two other things: observability, and the number of places one fix has to be applied.

The audit of my own service found three hand-rolled caches - a map plus a read-write mutex, no
TTL, no capacity bound, no metrics. Three places to change when eviction policy changes, and zero
answers to "what is the hit rate right now". The platform cache gives TTL, capacity and metrics on
the first line of use. Nobody would have argued that the hand-rolled ones were better - they were
written because writing one was faster than looking one up, and each was written by someone who
didn't know the other two existed.

You find out on production, which is the worst possible place to find out that a cache has no
upper bound.

Where the line isn't obvious

It's not a clean cut, and pretending otherwise would be dishonest.

Input, processing and output all lean on platform primitives themselves. Writing goes through the
transaction registry. Listing uses the platform's pagination. Every identifier comes from the
platform's id package. So the service isn't "platform-free" on its own side of the line either.

What stays in the service is the decision: what counts as a domain invariant, what a valid
transition is, which events matter to anyone else. The platform doesn't know the subject area, and
it shouldn't. The moment a platform package starts knowing what a valid order looks like, it stops
being a platform.

There's a second blurry edge, and it's the one that actually costs time: test infrastructure.
It looks like service code — it's in the service's repository, it knows the service's schema — but
the expensive part of it is generic. One container for the whole run rather than one per package,
a fresh database per test rather than a fresh container, explicit teardown rather than trust in a
reaper. Every one of those is a decision nobody wants to re-litigate per service, and every one of
them is invisible until a laptop is on its knees running the suite. So it lives on the platform
side, and what the service supplies is the fixtures.

The way I decide, when it isn't obvious: ask whether the next service would need the same thing
written again. If yes, it's runtime, even if it currently sits in a file that looks domain-shaped.

What it costs

Three prices, all of them real:

You depend on someone else's release cycle. If the primitive you need isn't in the platform
yet, the work stops until the tag exists. Not "we'll pin a commit and clean it up later" - the
service carries exactly the tag it was given, so the wait is a real wait.

The platform dictates the shape. Its interface decides how your code is arranged. Bending to
it is almost always cheaper than arguing with it, and "almost always" is doing some work in that
sentence.

There's a second place to look during an incident. The behaviour you're debugging may be in
your service or in the layer under it, and the first minutes go into deciding which.

I take those three over the alternative, which is a service that contains its own private
half-observable copy of everything.

The one conclusion

The only code that should be left in the service is the code you couldn't reuse in the next
service.

That's my line and my price. If you do this better, if you've already been through it, or if you
look at it differently - I'd like to hear how it's solved on your side, and what broke when you
tried it.

Platform and generation - Part 2.

Next: how to find the hand-rolled runtime still sitting in your own service - and what turned up
when I ran that audit on mine.

Every Service Should Be Copy-Paste

Anton Brilliantov — Wed, 26 Aug 2026 09:13:29 +0000

Sameness beats elegance when a machine has to reproduce the layout.

👋 I'm Anton - a software engineer working mostly in PHP/Symfony and Go, currently carving a live PHP monolith into Go services. This is the first part of a series about the platform, the service template and what can be generated instead of typed. It starts with the least glamorous decision I've made: every service is laid out identically, on purpose. Notes: github.com/brilliant-almazov.

Maybe it's useful to you. Maybe you look at this differently - that's a conversation I'd take.

The thesis

A service should read like a copy of the previous one. The value isn't that any single arrangement
is beautiful; it's that a reader knows where the next line lives without opening the file. Once
that's true, the layout stops being taste and becomes a property you can check - and, later, one a
program can reproduce. Variety has a price, and it isn't paid once: it's paid by every service
after the first, and by every domain inside them.

Everything below is from one service I keep the samples from, measured on 2026-08-16. Domains are
renamed to neutral entity / order; the shapes and the numbers are real.

Layout is a rule, not taste

Packages are laid out by component type first, with the domain as a nested package. This is
the actual tree, not a simplified excerpt of it:

internal/repository/entity           read only
internal/repository/entity/methods   one method = one file = one type with Execute
internal/manager/entity              write only, including find-or-create
internal/manager/entity/methods
internal/model/entity
internal/grpc/codec/entity           + /methods
internal/grpc/entity                 entity-first: one folder per entity…
internal/grpc/entity/create.go       …and one file per method inside it
internal/grpc/service/report         service-first: one folder per gRPC service…
internal/grpc/service/report/build.go   …and one file per method, same shape
internal/grpc/method                 20 generic RPCs - the method bodies live here
internal/daemon/server/entity        assembles the domain's Calls
internal/daemon/worker/...           relay, retention, derived, observe
internal/publisher/entity, internal/consumer/entity
internal/job/<name>, internal/recorder/<name>
internal/port                        cross-cutting ports, one interface per file
internal/testsupport/...             stands, no asserts
<package>/test/<concern>/            package <concern>test, black box only

Substitute order for entity and that is the next entity - in this service and in the next one.
The inverse (internal/domain/<domain>/repository, internal/domain/<domain>/manager, one package
per business area holding every role) is not allowed in my codebase. Both layouts are
navigable; they differ in what stays the same when you open the next service. I put the
domain-first model on the table properly a few paragraphs down, with what it wins as well as what
it costs.

Two caveats before the picture, because the tree above is not four clean rows. The transport
layer has two shapes on purpose - grpc/<entity>/<method>.go for operations on one entity,
grpc/service/<service>/<method>.go for compositions that aren't about one entity - and both live
in the same service. Some component types need a grouping level before the entity (grpc/codec,
daemon/server, daemon/worker), and one of them holds no entity at all: grpc/method is where
the 20 generic RPC bodies live. Type-first is the rule; these are the places the rule has more than
two levels, and pretending otherwise would make the rule look tidier than it is.

  type first  (what I use)          domain first  (also works)
  ──────────────────────────────    ──────────────────────────────
  internal/                         internal/
  ├── repository/entity             └── domain/ordering/
  ├── manager/entity                    ├── model
  ├── model/entity                      ├── repository
  ├── grpc/entity/create.go             ├── manager
  ├── grpc/service/report/build.go      └── grpc/create.go
  └── grpc/method                   internal/domain/billing/…

  + one shape in every service      + one business area, one folder
  - one feature, four directories   - the shape moves service to service

The path is a chain, not two levels

"Type first, domain nested" is the short version, and it undersells the rule. The path is a chain,
and only its two ends are fixed:

internal/ → component type → (whatever grouping that type needs) → entity → the entity's own pieces

The type comes first, the entity comes last, and how many segments sit between them is
whatever that type needs. Some types need nothing in the middle. The transport types need one
level, for the entity, the service or the resource they serve. And the entity folder is not a leaf
either -
it holds the entity's own pieces, which sit next to each other because they belong to the same
thing:

internal/repository/entity/methods/search.go      read side: one method, one file
internal/manager/entity/methods/create.go         write side, the same shape
internal/manager/entity/processor/normalize.go    the entity's own processors
internal/manager/entity/mapper/row.go             and its own mappers, right beside them
internal/model/entity/patch.go
internal/grpc/entity/search.go                    entity-first: grpc → entity → method
internal/grpc/service/report/build.go             service-first: grpc → service → method
internal/http/entity/list.go                      http → resource → route
internal/http/entity/create.go                    handlers are not a special case
internal/publisher/entity, internal/consumer/entity
internal/daemon/server/entity                     the assembly of the same entity

Two things follow from that, and both are worth saying plainly.

The list of component types is open. It's plus or minus the set above - repository,
manager, model, grpc, http, publisher, consumer, daemon, job, recorder, port
happen to be the ones my services have. A service that genuinely has another kind of component
adds it as a new top-level type rather than smuggling it into an existing one, and a service that
has no HTTP surface simply has no internal/http. Some types aren't per-entity at all (job,
recorder) and name their folder after the thing itself; that's fine - the chain says the last
segment is the unit, not that the unit is always an entity.

The invariant is the ends, not the depth. Nothing here says "exactly two segments". It says
the first segment answers what kind of component this is and the last answers what it is
about - and everything in between exists because that particular type needed it. That's what
makes the shape describable in one sentence and still able to hold a transport layer, a processor
and a mapper without special cases.

On the gRPC side there are two nestings, and both are right

The transport types are where the middle of the chain earns its keep - and it's the one place where
I deliberately don't have a single answer. There are two shapes. They exist for two different
kinds of call, and they sit side by side in the same service.

Entity-first - one folder per entity, one file per method inside it - for the calls that are
about a thing: create it, read it, search it, update it.

internal/grpc/entity/create.go
internal/grpc/entity/search.go
internal/grpc/order/create.go        the next entity, same two levels

Service-first - a folder named literally after the gRPC service, one file per method inside it -
for the calls that are about a composition: an operation that orchestrates several things and
doesn't belong to any single entity.

internal/grpc/service/report/build.go
internal/grpc/service/report/export.go
internal/grpc/service/transfer/run.go

  entity-first                      service-first
  "I want to create an entity"      "I want that composite operation"
  ────────────────────────────      ────────────────────────────────
  internal/grpc/                    internal/grpc/service/
  └── entity/                       └── report/
      ├── create.go                     ├── build.go
      └── search.go                     └── export.go

  both shapes live in one service; the path says which one you are in

What stays fixed across both is the pair of units underneath. A method is the unit that changes:
a change request is never "touch the handler package", it's "Search now takes a cursor" - so the
method gets its own file, and a diff that touches Search touches exactly search.go. A service
is the unit that shares a contract: the files in one folder are precisely the RPCs declared in one
.proto service block, so the folder listing and the contract can be read against each other line
by line, and a method that exists in one and not the other is visible without a tool. Anything
flatter - grpc/handler/<domain> with the methods mixed inside - loses both properties in either
shape: the file boundary no longer matches the change boundary, and the folder no longer matches the
contract.

Both in one codebase is a fit, not a compromise. The two shapes cover different kinds of
operation, so a service that carries both isn't being inconsistent - it's being specific. The
invariant that has to hold is the copy-paste one: whichever shape a given call belongs to, it looks
the same in every service, and a reader can tell from the path alone which of the two they're in.

The deciding criterion is human perception, not purity - and this is my reading of it rather
than a law. The split is binary in the reader's head: "I want to create an entity" is one thought,
"I want that composite operation" is a different one, and I'd rather the tree match that split than
force every call into one tree for the sake of a tidier rule. Picking a single shape and using it
everywhere is defensible in both directions - all-entity-first keeps the tree flat and the domain
obvious, all-service-first keeps the folder listing and the .proto in exact correspondence
everywhere. I find the two-shape version easier to navigate because the path answers a question I
actually ask, but I wouldn't argue anyone out of the other two.

The bodies aren't there, though. The RPC flow lives in one of the 20 generic methods, which has a
single execution method, Handle(ctx, req). What either folder contains is assembly only: a
type with a deps field, a NewXxx(deps) constructor, and a Call() that returns the lambda the
transport wires in. Five method files per service, and not one hand-written body among them.

The practical consequence is that reviewing a new domain's transport layer is not reading logic.
It's checking that five files were filled in with the right names - which is exactly the kind of
work worth taking away from a person.

One method, one file, one type

Under repository/<domain>/methods and manager/<domain>/methods the unit is not a function but a
type: one method per file, one type per method, with an Execute on it. So "where does this query
live" has a mechanical answer - a path - rather than a search.

A concern is a folder, never a filename prefix

This is the rule I'd keep if I had to drop all the others:

internal/manager/entity/entity_create.go       ✗ concern as a filename prefix
internal/manager/entity/create_helpers.go      ✗ helpers file
internal/manager/entity/methods/create.go      ✓ concern as a folder

In the root of a package there are only contracts and Base; the implementation of a concern lives
in that concern's subfolder, and in methods/ there are only methods. The moment a concern is
allowed to be a filename prefix, the tree stops being predictable and becomes a naming convention
people remember with varying accuracy.

The other model, and it's a real one

Type-first is not the only layout that works, and the honest way to argue for it is to describe the
main alternative the way someone who likes it would.

First, a distinction that gets lost every time this argument is had: a domain is not an entity.
order is an entity - a thing with a table, an id and a lifecycle. ordering is a domain - a
business area that owns order, order_line and discount, plus the rules that only make sense
across all three. Putting one entity at the top of the tree isn't domain-first; it's entity-first
with the roles turned inside out, and it inherits the costs of both. Domain-first means the tree's
top level is the business area, and the entity is a level underneath it:

internal/domain/ordering/                 the business area, not a table
internal/domain/ordering/model            order, order_line, discount
internal/domain/ordering/repository       reads for everything in the domain
internal/domain/ordering/manager          writes for everything in the domain
internal/domain/ordering/grpc/create.go   the domain's transport
internal/domain/billing/…                 the next area, same five rows

That distinction is what makes the alternative worth taking seriously. A tree whose top level is
order, order_line, discount is just a flat list of tables with folders around them. A tree
whose top level is ordering, billing, catalog is a map of what the service is for, and
that's a real claim about readability, not a stylistic one.

What that layout is genuinely good at:

Everything about one domain sits in one place. Adding a field is one directory, one listing, one mental context. Nothing about ordering is anywhere except under ordering - including the three entities it owns.
A domain lifts out cleanly. If ordering later has to become its own service, the seam is already cut - the move is close to a directory copy instead of an archaeology exercise.
It matches the way people talk. Nobody says "I'm in the manager layer today"; they say "I'm on ordering". A tree that agrees with that sentence is easier to hold in your head, and easier to explain to somebody on their first day - and it names areas of the business, not tables.
It scales down well. In a service with two domains and a handful of files each, type-first is ceremony wrapped around almost nothing, and domain-first is just the shorter path.
It keeps a change local. One feature usually lands inside one folder rather than across four.

What it costs, in the situation I'm actually in:

The same file lands in a different place in each service. Nothing in domain-first says where the write path goes, so one service grows internal/domain/ordering/manager, the next one internal/domain/ordering/service, the third puts the writes in the repository. Each is defensible on its own; together they're a fleet with no shared map.
The shape stops being checkable. With roles at the top I can state a rule a program can verify - "repository reads, manager writes, for rows.Next() appears in exactly one package". With the domain at the top the same rule has to be restated per domain per service, which in practice means it's restated nowhere.
A reader has to learn each service, not just the first. The cost isn't paid once; it's paid by every service after the first, and by every new person on every one of them.
There's nothing to generate against. A generator places files by rule. If the rule is "the way this service's author preferred", there's no rule to place by and no baseline to diff drift against.

Neither column is a knockout. The choice comes down to which cost you actually pay: if you have one
service and a small team, the top list is real and the bottom list is theoretical, and domain-first
is the better answer. I have services that are supposed to be copies of each other and a generator
that has to place files by rule, so for me the bottom list is the one that bites - and I pay the
top one, including the part where following one feature means opening four directories.

This is my structure, not a rule for anyone else

I want to be blunt about the status of all of this: it's the layout I picked, for my services,
and the reason is readability in one narrow sense - I can find the next line without opening the
file. That's the whole justification. It isn't a standard, I'm not proposing it as one, and a tree
that looks nothing like mine can be the better tree in your codebase.

So lay your services out however you like. The property I'd actually argue for is the one
underneath the shape rather than the shape itself: a service should be a copy of the previous
one. Choose type-first, choose domain-first, choose something I haven't thought of - as long as
the second service is the first one with the names changed, you get the thing that matters here.
The tree above is my answer; the sameness is the point.

Exactly two layers over the database

There are two layers that touch the database, and there is no third:

repository - read only.
manager - write only, including find-or-create.

Types and packages named store, writer, dao or service for database access do not exist. If
a Store shows up in a diff, that's the error, not a naming preference - it gets split into a
repository and a manager. When a manager needs to read, it calls the repository instead of
duplicating the SQL, which is what keeps "where is this query" answerable at all.

  ┌──────────────────────────┐                 ┌──────────────────────┐
  │ manager                  │  needs to read  │ repository           │
  │ write only               │ ──────────────▶ │ read only            │
  │ incl. find-or-create     │                 │                      │
  └──────────────────────────┘                 └──────────────────────┘

  there is no third layer:  store · writer · dao · service

Transactions are a decorator, so the domain never knows

Transactions sit outside that split: a decorator applied from the outside, only on mutations, with
the executor taken from the context. tx pgx.Tx in a signature is forbidden, and the domain code
never learns it is running inside a transaction.

One package in my own service didn't follow it: a repository running its own Begin by hand with
pgx.Tx as a struct field, straight past the platform's transaction registry. Nothing broke and no
test went red. It was just a different shape from everything around it - which is the exact failure
mode the rule exists to make visible. In a codebase where every repository is allowed to look
different, that one is invisible; in this one, it stands out in a directory listing.

The rest of the mechanical rules

A layout rule that runs on good intentions decays. These are the constraints that keep it
mechanical, and each one exists because its opposite produces variety:

Rule	What it removes
a file is at most 100 lines, a line at most 80 characters	files that grow into their own little architectures
no comments in `.go` files	prose drifting away from the code it describes
`helpers.go`, `utils.go`, `common.go`, `funcs.go` are forbidden	the junk drawer every service otherwise grows
every operation is a method on a struct	package-level procedures nobody can locate
all SQL goes through a query builder; raw SQL in Go is forbidden (only migration DDL and test fixtures are exempt)	the same query hand-written twice, differently
errors are matched with `errors.Is` / `errors.As` only	direct comparisons that silently stop matching once a wrap is added
no `switch` on types in shared code - polymorphism instead	a routing table that grows a case per domain
initialisms read as ordinary words (`HttpClient`, `JsonBody`); only `ID` is uppercase	two spellings of the same field name

None of these are interesting on their own. Together they're the difference between a layout you
can describe and a layout a program can reproduce.

Two binaries, one image - and the layout mirrors it

The service ships as one image with two binaries selected at build time
(--build-arg BINARY=): server, which serves gRPC, and worker, which relays outgoing events,
runs background calculations and drops old audit partitions. The tree says so out loud:

internal/daemon/server/entity      assembly of the domain's Calls
internal/daemon/worker/relay       outgoing events
internal/daemon/worker/retention   audit partitions
internal/daemon/worker/derived     background calculations
internal/daemon/worker/observe     gauges

The count of binaries is a decision of the service owner and nothing else: new background work goes
into an existing daemon, not into a new cmd/*. That's another sameness rule that reads as
bureaucracy until you picture the alternative - a fleet where every service has a different number
of things to deploy.

Generic cores: why there's so little left to copy

Sameness is what makes deduplication possible, and deduplication is what keeps the sameness cheap.
Most behaviour lives in generic cores that every domain instantiates rather than reimplements.

The RPC flow, for instance, is 20 generic methods - and that list is the service's write and read
surface:

archive   attach    close     correct   create
create_batch        detach    find_all_by_ids
get       get_by_key          list_revisions
lookup    lookup_pair         move      mutation
save      search    set       update    walk

Around them:

Core	What it gives every domain
codecs	`Shape`, `Selector`, `NewUnary`, `NewCollection`, `NewPaging`, `NewPairing`, `Suite`, `Spec`, `BatchSuite`
entity repository	`Base`, `Spec[H, P, V]`, `Calls`, `ScopedCalls`, `Search`, `FindAllByIds`, `Reader[In, Out]`, cursors
entity manager	`Base`, `Spec`, `Calls`, `ScopedCalls`, `Manager`, `methods/`
history	`Revisioned[T]`: `Current` / `AsOf` / `KnownAsOf` / `Append` / `Correct` / `Close` - one form for the whole service
row reading	set, counter, existence probe, `Reader` with collectors
pagination	keyset cursor over `int64` plus a page-size clamp
domain assembly	`Builder[Repo, Mgr]`, `Domain[Repo, Mgr]`, `New`, `Input`, `ManagerInput[Repo]`, `HandlerInput[Repo, Mgr]`
task runs	`Runner[T]`, serial and parallel
validation	`Rule[In]`, `Guard[In, Out]`, `Each[In]`, `Nullable[T]`
ports	`Scoped[T]`, `Self[T]`, `Creator`, `Updater`, `Corrector`, `Archiver`, `Viewer`, `Finder`, `Locator`, `Searcher`, `Historian`
test rig	`TenantRig`, `Spec`, `StubManager`, `StubRepository`, `Port`, `NewItem`, `NewPatch`, `KeepData`

The rule in one line: if two things differ only in a type parameter, they are one generic. A
domain-local copy sitting next to an existing generic is forbidden, and that ban is held by tooling
checks and forbidding tests rather than by review etiquette.

What variety actually costs: 44 copies of four loops

The best argument for sameness I have isn't the tree - it's an audit I ran over my own service on
2026-08-13, hunting hand-written ways to read rows out of Postgres. It found 44 copies of four
forms:

Form	Copies
many-row loop (`for rows.Next()` → `rows.Err()` → wrap the error)	18
single row	6
`COUNT(*)` counter	8
existence probe (one `rows.Next()`)	12

They differed in exactly two things: the result type and the wording of the error wrapper - and 12
of them differed only in the wording. A type parameter and a dependency: that is a generic, typed
out by hand 44 times.

The part that stings is that the correct form was already in the tree: Reader[In, Out], with
executor, statement and scanner fields and a Query(ctx, in) method. It was just sitting
inside one domain's package instead of a shared one, so nobody reusing it was possible. Collapsing
the 44 copies onto it took a set of 40 iterations, one file each, and the closing condition is a
forbidding test rather than a promise: for rows.Next(), rows.Err(), rows.Close() and
QueryRow( may appear in exactly one package in the whole tree.

The same audit found the rest of the drift

Once you go looking for hand-written versions of things that already exist, they come in a batch.
From the same pass, each one a small deviation in shape that nothing was failing on:

What was there	What it should have been
three hand-rolled caches: `map` + `RWMutex`, no TTL, no capacity, no metrics	one cache with TTL, capacity and metrics
message dedup as a hand-written ring of 1024 ids	the same cache, with a TTL
bulk insert as one `INSERT` per row	a multi-row `VALUES`
two different loggers in two packages of one service	one
the retention schedule hard-wired as a constant	a config value
a lazy scheduler init on `sync.Once` with captured variables	the platform's init-state storage
a cache-invalidation consumer written but registered in no daemon	registered, or deleted

That last one is the sharpest. The package compiled, its unit tests were green, and invalidation
simply did not run in production, because nothing anywhere said "a consumer must be mounted
somewhere". Sameness is not an aesthetic in that story - it's the only reason the gap is findable
by looking rather than by an incident.

The numbers

None of this is a declaration. As of 2026-08-16, in the service I take these samples from:


`.go` files (excluding generated)	2733
packages	252
average file	39 lines
files over 100 lines	44 - of which 2 are non-test (105 and 102 lines)
migration files / lines	66 / 1990
line coverage	86.7%

The interesting one is the average, and it's clearer over the tag history (generated code excluded
throughout):

Tag	Code	Tests	Tests/code	Files	Packages	Average file
v0.1.0	1751	781	0.45	35	13	50
v0.2.0	5054	2817	0.56	101	20	50
v0.3.0	22765	26924	1.18	520	74	43
v0.4.0	28095	31952	1.14	640	85	43
v1.0.0	25097	35368	1.41	683	94	36
v1.1.0	29443	36272	1.23	804	109	36
v1.2.0	34523	39861	1.15	933	119	37
v1.3.0	42461	49564	1.17	1116	135	38
v1.4.0	50755	62986	1.24	1300	175	39
v1.5.0	55979	68437	1.22	1403	187	39
v1.8.0	58372	72758	1.25	1476	205	39
v1.10.0	60019	74701	1.24	1514	232	39
HEAD	61411	76468	1.25	1540	252	39

Three things I read off that table:

The service grows by files and packages, not by files getting fatter. 13 → 252 packages while the average file went 50 → 39 lines and then stopped moving. 2733 files averaging 39 lines is a different codebase from 700 files averaging 150, even at the same total size.
Deduplication is visible as a dip. At v1.0.0 lines of code dropped from 28095 to 25097 while test lines grew: repeated domain files going into generic cores. The tests-to-code ratio went 1.14 → 1.41 in that step, and hasn't gone below 1.14 since.
New cores arrive as packages, not as sprawl. The latest release increment - the row-reading core above, together with an SQL catalog engine - was +1392 lines of code, +1767 lines of tests and +20 packages.

What this is actually for

The honest reason isn't readability. It's that a formalised layout is the only thing that makes
generation possible.

A generator doesn't guess style; it places files by rule. As long as the layout is "whatever the
author preferred", there is nothing to generate - and nothing to check drift against. You can't
diff a tree against a convention that exists only in people's heads.

The census: how much of a domain is shape

Writing the spec for a skeleton generator (12 iterations, specified and not built yet - I'm
describing designed work, not a shipped tool) forced me to inventory a domain file by file. That
inventory is the most concrete answer to "how copy-paste is it, really":

Layer	Fully mechanical	Hand-written body
domain gRPC methods (`internal/grpc/<entity>/`, or `internal/grpc/service/<service>/`)	all 5 files	none
domain codecs	`codec.go`, `mapping.go`, `request.go`, `request_patch.go`, `suite.go`, `base.go`	`payload.go`, `filter.go`, `errors.go`
domain repository	`calls.go`, `repository.go`, `revision.go`, `deps.go`, `methods/search.go`, `methods/find_all_by_ids.go`	`spec.go`, `methods/header.go`, `methods/code_taken.go`, `methods/slug_taken.go`
domain manager	`calls.go`, `deps.go`, `manager.go`, `methods/{create,update,correct,archive}.go`	`spec.go`
domain model	9 files	6 files
domain assembly in the daemon	all 4 files	none
domain test stand	all 3 files	none
migrations	all	none

Read the right-hand column top to bottom and you have the whole of what a new domain actually
writes itself: two spec.go files, three codec files, three repository methods carrying its own key
rules, and 6 of its 15 model files. That list is the domain. Everything else is the shape -
which is another way of saying the copy-paste was already happening, and formalising the layout
only makes it honest.

The generator's form follows from the same idea

Two things about the design are worth naming, because both are consequences of sameness rather than
preferences:

It's a library, not a script: Generate(cfg) (Result, error) and CheckDrift(cfg) ([]string, error), with a thin CLI over them. Drift-checking is the same code path as generating, so the two can't disagree.
It renders by concatenating strings - prepared constants, a string builder, token substitution ( $domain$ , $Domain$ , $plural$ ) - and templating engines are explicitly forbidden. Every .go output goes through the formatter, so import grouping and alignment are not the renderer's problem.

The input is deliberately double, because neither source describes a domain on its own: a YAML
description (names and plural, Go types, tenant-scope flag, slug and batch flags, header and
revision tables, payload columns with SQL type, nullability and comment, event types, error
sentinels, first migration number) plus the .proto descriptor (service name, RPCs with request
and response types, entity and batch messages).

Files that need a hand-written body still get generated - correct package, imports and signatures,
bodies marked with a panic stub - and a second run without -force won't overwrite them. Generated
files carry a Code generated by … DO NOT EDIT. header, which is a contract: editing one by hand is
forbidden, and a check mode compares what would be generated against what's in the repository and
exits non-zero on a difference.

And what the generator deliberately doesn't touch: the generic cores above, and one-off pieces like
publishers or the invalidation consumer. They aren't "per domain", so they aren't a unit of
generation.

Even the migrations have one shape

Schema work is where "each author their own way" usually wins, so it gets the same treatment: goose,
embedded, forward-only (-- +goose Up, no Down), file names as NNN_description.sql, one
table per migration, a rollback expressed as a new migration forward. COMMENT ON COLUMN on
every column. VARCHAR rather than TEXT. A migration file that has already shipped is
immutable.

66 files, 1990 lines, and the reason they're the one layer the generator can emit in full: there is
nothing in them that is a matter of judgement about form.

Where the tests live

The layout rule applies to tests too, and this is the part that surprises people most: tests are not
next to the code. They live in <package>/test/<concern>/ as package <concern>test, black-box
only - the package under test is imported from outside. Stands and fixtures live in a shared
support tree with no asserts, take testing.TB as the first parameter, call t.Helper() on the
first line, and release resources through t.Cleanup. Golden files go in testdata/ next to the
test that reads them.

The price is real: longer paths, no access to unexported identifiers, and some tooling expects tests
to sit beside the code. What it buys is that a test file has exactly one possible location, and a
"test helper" can't quietly become a second implementation of the thing it helps.

What makes it stick: checks, not promises

Every rule above is either enforced by something mechanical or slowly decaying. The escalation I've
converged on is reminder → rule → check, and only the last one holds:

Instead of a rule	The check that replaces it
"don't hand-write row loops"	a forbidding test: `for rows.Next()` appears in exactly one package
"keep the generated tree in sync"	a check mode that diffs generated output against the repository and exits non-zero
"don't let coverage slide"	a ratchet: the threshold can only go up, and an attempt to lower it fails the PR
"don't use an empty context in tests"	a tool hook that blocks the write
"don't leave open questions in a task spec"	a tool hook that blocks the write when a forbidden phrase appears

Two honest footnotes. The coverage ratchet currently sits at 0 - the mechanism is in place, the
bar hasn't been raised yet, while actual coverage is 86.7%. And the empty-context rule exists
because the scale of that particular drift was 421 empty-context calls across 184 test files;
that is what a convention nobody checks looks like after a few months.

What it costs

It's unfamiliar: people arrive looking for internal/domain/<area>/ and it isn't there.
It's boring. Nothing to argue about, and an author's taste never lands in the layout. Some engineers experience that as a loss.
Following one feature means jumping between directories - repository, manager, model, the gRPC folder, codec, plus the daemon assembly, instead of one folder. That is exactly the thing domain-first gets right, and I give it up on purpose.
There are a lot of files (2733), and search-by-name matters more than scrolling one.
Tests are not next to the code, which costs unexported access and some tooling friction.
The rules only hold while the checks do. Every one of them is work to build and work to keep green.

Those are real costs, and they're the price of a choice rather than the proof of a law. I pay them
because in my situation the other bill - a fleet of services each with its own shape - is larger,
and it comes again on every service and every domain inside it. Your bill may be arranged
differently.

The one conclusion

Predictability beats elegance exactly when the code has to be reproduced by a machine rather than
rewritten by a person. Which shape you make predictable is yours to pick - mine is type-first
because I can find the next line without opening the file. The part I'd defend in anyone's
codebase is only this: the next service should be a copy of the last one.

That's my experience and my price for it. If you do this better, if you've already been through
it, or if you look at it differently - I'd like to hear how it's solved on your side, and what
broke when you tried.

Platform and generation - Part 1.

Next: what the platform hands you for free, and the list of things you're not allowed to write by
hand because of it.

One New Order Status, One Full Table Rebuild - and the Years of Magic Numbers After It

Anton Brilliantov — Mon, 24 Aug 2026 09:42:20 +0000

A new order status is a one-word change to a spec and, on MySQL, potentially a full table rewrite. The team's reaction to that scar is almost always the same: drop enums, store a tinyint, decode it in the app. That reaction costs more than the rebuild did. This is the situation, why it happens, what Postgres does instead, and the price of each option - told honestly, because Postgres enums have real limits too.

👋 Hi, I'm Anton - a software engineer working mostly in PHP/Symfony and Go, usually writing about breaking a monolith into services. This one is smaller and self-contained: a database-design decision people get wrong because they're carrying a MySQL scar into Postgres, and I carried it too for a while. Running notes live on my GitHub: github.com/brilliant-almazov. Maybe you landed somewhere else on this - I'd like to hear where.

What broke

The change request is boring: orders need one more status. partially_refunded, say, and it belongs next to refunded, not tacked on at the end - the status column is ordered and people read it in order.

On MySQL, that "belongs next to" is the expensive word.

An enum in MySQL is welded to the column. Its members are stored by position, so putting a new one in the middle renumbers the existing members. Renumbering means every row has to be written again, which means the change is not metadata - it's a full table COPY. The table gets rebuilt. It locks. And it needs as much free disk as the table itself, which is its own kind of surprise at 2 a.m.

The variant that is cheap - appending at the end - is cheap only under conditions: INSTANT, metadata-only in modern MySQL 8, if the storage size doesn't change. Cross a storage-size boundary and you get a copy anyway. And historically, before 5.6.16, even the "fast" append rebuilt the whole table.

So the real shape of the incident is not "one migration was slow". It's that an enum change in MySQL is position-, size-, and version-dependent: three conditions someone has to reason about correctly, every time, forever.

What it cost - the part that outlives the incident

Nobody wants to run that reasoning twice. So the team does what teams do: gives up on enums entirely and stores an int/tinyint plus a code map.

That's the expensive decision, and it's paid every day afterwards:

The database holds 3. To know that 3 means partially_refunded you either keep a lookup table - a JOIN on every read - or an app-side map you must keep in lockstep with the DB.
Every ad-hoc query, every support ticket, every dashboard goes through a decoding step that lives in someone's head.
When the map drifts from the database, nothing breaks loudly. It just becomes quietly wrong.

Magic numbers in every row. Remembering ints is no fun, and the drift is a source of quiet bugs.

The rebuild was one bad night. The tinyint is a tax with no end date.

Which is where my own preference comes from, and I'd rather name it than let it leak: I like it when a set of values is typed, because then the type checks the thing a person would otherwise have to check in review - and in that story nobody was checking, which is why the map drifted. It's a preference, not a law. What follows is what it costs to hold it, on each database, with the price attached.

Why Postgres doesn't have this failure mode

Postgres doesn't weld the enum to a column. An enum is an independent type living in the catalog (pg_type / pg_enum), and your column just references it. That single design difference is the whole story:

MYSQL                                   POSTGRES
enum is part of the COLUMN              enum is an independent TYPE

  ALTER TABLE ... MODIFY enum             ALTER TYPE order_status
        │                                       ADD VALUE 'refunded'
        ▼                                       │
  middle/reorder/size-cross                     ▼
        │                                 catalog change - a row in pg_enum
        ▼                                       │
  full table COPY  →  rewrite + LOCK            ▼
  (as big as the table, downtime)         no table rewrite, no table lock

ALTER TYPE ... ADD VALUE writes one row to the catalog. It does not rewrite the table the column lives in, and it doesn't lock that table's data. Since Postgres 12 it's even transactional - you can run it inside a transaction, with one caveat: the new value can't be used until the transaction commits. On PG < 12 you couldn't ADD VALUE inside a transaction at all.

And the part that makes the tinyint escape pointless here: a Postgres enum value is stored as a 4-byte OID - exactly as compact as an integer - but type-safe, human-readable, and with no JOIN to decode. The int's footprint, the string's readability, the type system's guarantee, in one column.

None of that asks you to take my word for it. The enum being its own catalog object, the 4 bytes read straight out of the row, the rollback that takes the added value back out since 12 - each one is a statement you can check on your own instance in a few minutes. That's why the preference survives here and didn't survive on the other side of the table.

Adding a value is transactional - and that's the whole point

The catalog row is the cheap part. The part that removes a whole class of deploy anxiety is when that row becomes visible.

Before Postgres 12, ALTER TYPE ... ADD VALUE could not run inside a transaction block at all - the command simply failed. Since Postgres 12 it can, and that changes what you can guarantee: roll the transaction back, and the added value vanishes with everything else in it. There is no half state left behind - no "the type gained the value, but the dictionary row never landed".

That matters because of a very ordinary setup. A system keeps a dictionary of values and an enum type that are required to agree with each other; the dictionary is what people and other services read, the type is what the column is constrained by. Drift between the two is the bug you find weeks later. So you add the dictionary row and run ALTER TYPE ... ADD VALUE in the same transaction. Commit - both exist. Roll back - neither does. The agreement is held by the transaction itself, not by the ordering of deploy steps and not by a retry loop that someone has to get right.

BEGIN;
INSERT INTO dictionary.order_status (code, title)
VALUES ('partially_refunded', 'Partially refunded');
ALTER TYPE orders.order_status ADD VALUE IF NOT EXISTS 'partially_refunded';
COMMIT;
-- the value can be written into data from the next transaction onward

ADD VALUE IF NOT EXISTS makes the whole thing idempotent, so a migration that runs twice - or a message that gets redelivered - changes nothing the second time.

Now the caveat, said out loud rather than buried: a new value cannot be used in the same transaction that added it, unless the type itself was created in that transaction. Try to insert a row carrying the new value before the commit and Postgres refuses with an error of the form unsafe use of new value of enum type. So the working order is two transactions: the first adds the value (and the dictionary row, if there is one), the second writes data with it. That's a sequencing rule, not a blocker - but you want to know it before you write the migration, not during it.

MySQL has no equivalent path. Changing an enum there can rebuild the table, which is exactly why the projects that got burned reach for an int. It works - and it leaves the database full of numbers that mean nothing on their own. To learn what 3 stands for you need either a JOIN to a dictionary or an app-side map kept in sync by hand. A Postgres enum reads straight out of the row, no JOIN. That's the difference in one line.

The honest caveats - what an enum still costs you

I'd be selling you something if I stopped at the good news. Over a long stretch since that night this has held up on my side and I haven't been burned by it - which is an observation from one system, not a promise about your next incident. The limits are real, they're what decide fit, and they belong here in the middle of the text rather than in a footnote under it:

You can't easily remove a value. There is no DROP VALUE. Retiring one means recreating the type (rename old → create new → migrate the column → drop old) or living with a dead value. Enums are add-mostly by nature.
Non-end inserts can be slightly slower. Placing a value with BEFORE/AFTER rather than at the end can make comparisons on that type marginally slower than on the original members.
A new value can't be used in the transaction that added it - unless the type was created there too. One transaction adds it, the next writes data with it.
They're for smallish, stable-ish vocabularies. Status, kind, channel - not a high-churn set, not something unbounded. There's a practical ceiling on how many values stay sensible.
They don't travel. A Postgres enum is Postgres-specific; an int moves to another engine and an enum doesn't.

One sentence of trade-off: an enum is lightweight (4 bytes) and readable, and for a small, mostly-append vocabulary I take that over the "can't easily remove" limits. When the set churns hard, needs deletion, or carries metadata, I don't - and there I reach for a lookup table or an int. On purpose, not by reflex, and with the scar accounted for rather than driving.

The fix, and the tool that came out of it

Even on Postgres, managing enum values by hand is fiddly: ALTER TYPE … ADD VALUE IF NOT EXISTS, getting idempotency right, handling schema-qualified type names, keeping the set in sync between migrations and the values the app actually produces. Small, repetitive, easy to get slightly wrong - exactly the kind of thing that deserves a helper rather than a convention.

So I wrote one: pgenum - a zero-dependency Go library (only database/sql; works with pgx, lib/pq, anything). It's small on purpose:

Idempotent - every call is ADD VALUE IF NOT EXISTS, safe to repeat.
Concurrent-safe - no shared state; Postgres serialises ALTER TYPE itself.
Schema-qualified - orders.order_status / audit.event_type work out of the box.
Injection-safe - identifier validation + quoting on every name and value.

import "github.com/brilliant-almazov/pgenum"

// the whole surface you usually need:
type Ensurer interface {
    EnsureValue(ctx context.Context, typeName, value string) error
    EnsureValues(ctx context.Context, typeName string, values ...string) error
}
func New(db *sql.DB) Ensurer
// plus helpers: SyncEnumFromColumn(...), EnumValues(...), HasValue(...)

Deploy-time (static): declare the vocabulary in YAML, apply it once at startup, right after migrations. Deterministic and reviewable.

type Config map[string][]string
func (c Config) ApplyDB(ctx context.Context, db *sql.DB) error

func seedEnums(ctx context.Context, db *sql.DB, path string) error {
    data, err := os.ReadFile(path)
    if err != nil {
        return err
    }
    var cfg pgenum.Config
    if err := yaml.Unmarshal(data, &cfg); err != nil {
        return err
    }
    return cfg.ApplyDB(ctx, db) // ensures every declared value exists
}

Runtime (event-driven): inject the Ensurer, and when an entity introduces a value, make sure the type knows it.

type OrderService struct {
    db    *sql.DB
    enums pgenum.Ensurer
}

func (s *OrderService) OnOrderCreated(ctx context.Context, order Order) error {
    if err := s.enums.EnsureValue(ctx, "orders.order_status", order.Status); err != nil {
        return fmt.Errorf("sync enum: %w", err)
    }
    // ... rest of the handler
    return nil
}

Because Ensurer is a one-method-ish interface, it mocks trivially in tests - no database needed to assert "the handler tried to ensure this value."

The decision the library refuses to make for you

Runtime, deploy-time, or both - there's no single right answer, and that's the interesting part.

Deploy-time fits when the vocabulary is known ahead of time and you want it in version control, reviewed in a PR, applied deterministically on release. Most enums are like this.
Runtime fits when values genuinely emerge - a third-party integration, a partner's status codes, user-defined-ish categories - and you don't want to ship a deploy just to accept a new one.

I run both on the same system, and each mode was built for one thing. The static dictionary gets applied at startup, right after migrations, because after that incident I wanted the set of values to live in version control and go through review like any other change - adding a status should be a diff someone reads, not a statement someone runs at 2 a.m. The event-driven EnsureValue is there for the handful of values that genuinely arrive from data; running it again is harmless, since every call is ADD VALUE IF NOT EXISTS. And on the hot path I don't call it at all - it's idempotent but still a catalog round-trip, so it's gated: ensure only on a value not seen before, or cache the known set (EnumValues / HasValue) and ensure once. How aggressively to cache follows from write load, which is exactly why it stays a judgment call and not a rule.

Your scenarios are the part I can't see from here. Which of your value sets sit in a dictionary, which sit in a type, and what pushed each one to that side?

enum vs int vs lookup table

	Postgres enum	int / tinyint	lookup table
Storage	4 bytes (OID)	1-4 bytes	int FK + the table
Readable in the DB	yes	no (magic number)	via a JOIN
Type-safe	yes	no	FK only
Read cost	none	none (opaque)	a JOIN
Add a value	cheap catalog change	trivial	one INSERT
Remove a value	hard (no DROP VALUE)	trivial	one DELETE
Values carry metadata	no	no	yes (label, i18n, flags)
Cross-database	no (PG-specific)	yes	yes

Read it as a fit test, not a winner - and here's how I read it for myself. I take a Postgres enum when I'm on Postgres, the set is smallish and mostly-append, and I want compact + readable + type-safe with no JOIN. I take a lookup table when the values carry their own metadata (labels, translations, feature flags). I take an int when I have no choice - cross-database portability, or a set that churns and needs real deletion. That's my reading of the same rows; yours can come out different.

That's my scar, that's the choice I made after it, and those limits are the price I pay for the choice. The bit I'm least sure about is where the line sits between "stable enough for an enum" and "churny enough for a lookup table" - that line moved for me more than once.

So: if you do this better, especially the retire-a-value path, I want to see how. If you've been through this - a middle-of-the-enum change on a big MySQL table, or years of decoding tinyints - the details are the useful part. And if you look at it differently and think native enums are never worth the add-mostly constraint, that's a reading I'd take seriously. How is it solved on your side, and what actually broke when you changed it?

Sources: MySQL online DDL operations · MySQL bug #72997 (enum ALTER full rebuild) · Postgres ALTER TYPE · pgenum

Snowflake IDs - Part 3: A Typed Prefix, and Two Doors

Anton Brilliantov — Sun, 23 Aug 2026 05:49:02 +0000

Part 1 settled the primary key. Part 2 got it across the wire, the URL and the browser. This part is about the thing that fell out of both and turned out to be the most useful of the three: the id is a seam. Inside the mesh it's a raw int64; on the public surface it's an opaque token. That difference isn't cosmetic - it's a line between two surfaces with different threat models, and the id is the cheapest place in the whole system to draw it. Here's what a typed prefix on the public token buys you: routing before decoding, a public surface that says nothing about your internals, and - if you want it - two front doors that never share an entry point.

👋 Hi again, I'm Anton - PHP/Symfony and Go, mostly writing about breaking a monolith into services without breaking the business. Part 1 argued for int8 + Snowflake as the primary key; Part 2 took that id out of the building - hashids at the edge, composite tokens, tenant-controlled salt rotation, and every int64 as a string before it touches a browser. This part is the structural consequence of Part 2, and it's the one I actually think about most: once the public id and the internal id are different values, you have a seam, and a seam is something you can build on. Running notes: github.com/brilliant-almazov.

As always: these are my habits on one codebase, with the trade-offs I've actually paid. Not advice for yours.

The seam nobody planned

Part 2 ended with a boundary drawn for defensive reasons: raw ints don't leave the building, so the gateway encodes on the way out and decodes on the way in. That was framed as a chore - a translation layer you maintain because browsers and attackers exist.

Look at it again and it's not a chore. It's the only place in the system where every request has to stop and be interpreted. Every public request carries an id. Every id has to be translated. So the encoding of the id is a checkpoint that nothing can route around - not a new endpoint someone added in a hurry, not a webhook, not a legacy path.

That's worth saying precisely, because "public API" and "internal API" get used as if they were two halves of one thing:

	Public surface	Internal surface
Callers	browsers, third parties, anyone with the URL	services you deploy
Identifier	opaque token	raw `int64`
Threat model	hostile by default	trusted, network-isolated
Shape leakage	must reveal nothing	reveals everything, that's the point
Contract stability	you own it forever	you can change it on Tuesday

Two surfaces, two threat models, two lifetimes. They are not tiers of the same API. And the identifier is already different between them - which means the identifier is already the marker of which surface you're on. A raw int64 arriving on the public surface is a bug by definition. An opaque token arriving on the internal surface is a bug by definition. You get that check for free, forever, without writing it.

The rest of this article is what you can build once you accept that seam as a first-class thing rather than a translation chore.

Give the public token a type

Here's the change, and it's small: the public id is not just a token, it's a prefix plus a token.

  o_kZ9mQ2xR            an order
  c_7bQ0pLMn            a comment
  iv_9Kd2mQ7rX4         an invoice
  l_3nR8tW1yA6          a one-time link

  <prefix><sep><token>
      │       │     └ the hashid from Part 2 — opaque, salted, tenant-scoped
      │       └ a character that cannot appear in the token alphabet
      └ the entity TYPE, in the clear

The token half is exactly Part 2: a salted hashid of one id or of a designed tuple. The prefix half is new, it's in the clear, and it's readable before you decode anything.

The separator is not a detail

The first thing that bites: if your prefix is o and your token alphabet contains o, you cannot parse okZ9mQ2xR back into a prefix and a token. There are exactly two honest fixes and you have to pick one on day one, because changing it later invalidates every link in the wild:

A separator character - o_kZ9mQ2xR. Pick a character excluded from the hashid alphabet (_ is the usual one, since the default alphabets are alphanumeric). Costs one character, reads well, survives copy-paste and double-click selection in most terminals.
A fixed-width prefix plus a restricted alphabet - prefixes are always exactly two characters, and those characters are removed from the token alphabet. No separator, slightly shorter, but you've now got a rule two layers deep that a future engineer has to not break.

I use the separator. It's more legible in a URL, it's obvious what it is when a customer pastes one into a support ticket, and the "why is the alphabet weird" question never comes up.

What the prefix actually buys

The prefix means the gateway knows what kind of thing the token points at before it does any work. Three things follow from that, and they compound:

Which salt cell decodes it. Part 2's salt matrix is (tenant × entity_type). Without the prefix, the entity type has to come from the route - which is fine when the route is /api/v1/orders/{id}, and useless when the route is /api/v1/l/{token} or a generic /api/v1/resolve/{id}. The prefix carries the type with the value instead of with the path.
Which handler owns it. Type-first dispatch instead of path-first dispatch. More on this below - it's the part that makes a gateway simple instead of a router with a switch statement in it.
Cross-type replay stops being possible. A token minted for an order won't decode under the comment salt - that was already true in Part 2. What the prefix adds is that the mismatch is caught before the decode, and caught explicitly: the route says "this position is an order", the prefix says c, and the request dies at the door with no decode attempted, no salt-history walk, no audit noise. You've turned a silent decode failure into a stated contract violation.

That third point is worth dwelling on. Without a prefix, "wrong type" and "wrong tenant" and "garbage string" all produce the same thing: a decode that doesn't resolve. You get one undifferentiated 404. With a prefix, you can tell a malformed id from a wrong-type id from an unknown-prefix id, and those are three different signals. The first is a broken client, the second is either a bug or someone probing, the third is either a stale link or someone guessing at your type namespace. Same 404 to the caller, three different lines in your logs.

The prefix map is configuration, not code

This is the part that surprised me, and it's a direct inheritance from Part 2's salt rotation.

The prefix isn't a constant in the codebase. It's a row in a per-tenant map, editable from the admin panel, exactly like the salt:

Public prefix	Internal type	Salt cell	Owning upstream
`o`	order	(tenant × order)	order service
`c`	comment	(tenant × comment)	comment service
`iv`	invoice	(tenant × invoice)	billing service
`l`	link	(tenant × link)	the gateway itself

Change o to ord and the outward encoding changes. Nothing else moves. The BIGINT in the database is untouched, the internal type name is untouched, the gRPC field is untouched, the index is untouched. The same property that made salt rotation a customer-facing button makes the prefix map a customer-facing setting: because the stored id is a stable BIGINT, everything on the outside of the seam is presentation.

Why would a tenant care? Mostly they don't, and the defaults ship as defaults. But two real reasons come up:

Their public API is their product. If a tenant exposes our objects through their own API to their own customers, the token is in their documentation. ord_... versus o_... is their naming decision, not mine, and it costs me a config row to let them have it.
The prefix is a deliberate alias, so it can be deliberately meaningless. Which brings us to the next section.

An anonymous public surface

The public API should say nothing about how the system is built. Not the numeric id, not the table name, not the internal route, not the service that owns it, not the number of services. That's not paranoia; it's just the honest consequence of the two-surface table above. The internal shape changes when I split a service or merge two; the public surface must not change when that happens, and it can't change if it never described the internal shape in the first place.

The prefix is a chosen public alias for an internal type. It does not have to resemble the internal name at all:

  PUBLIC (chosen alias)          INTERNAL (real shape)

    o_kZ9mQ2xR          →        order            → order service      → orders table
    c_7bQ0pLMn          →        comment          → comment service    → comments table
    x7_9Kd2mQ7rX4       →        billing_document → billing service    → invoices table
                │
                └ says nothing about "invoice", "billing", or which service answers

Three levels of naming, and only the first one is a promise to the outside world. The internal type can be renamed, the service can be split in two, the table can be partitioned into six - the public alias x7 is stable through all of it, because it was never derived from any of them.

The dull version of this rule, which is where most leaks actually live:

No numeric id anywhere public. Covered in Part 2, still the main one.
No internal type name in the public alias unless you've decided it's fine forever - because once it's in a customer's stored links, it is forever.
No internal route shape. The public path is /api/v1/orders/{id}, not /order-service/v2/orders/{id}. If your public paths mirror your service boundaries, every service split becomes a public API break.
No shape in the errors. A constraint name, a table name, or a driver message in a 400 body undoes all of the above in one line. This one gets me more often than the ids do, because it arrives through a generic error handler nobody looked at.

Routing on the prefix

Because the type is readable before the decode, the gateway can dispatch on it. That's the difference between a gateway that is a table and a gateway that is a switch statement growing one arm per feature.

// A public id is <prefix><sep><token>. Parsing is dumb on purpose: it splits,
// it does not interpret. Interpretation needs the tenant's map, which is below.
type PublicID struct {
    Prefix string
    Token  string
}

// The prefix map is per tenant and editable, exactly like the salt history.
// Current() is what we mint with; Retired() is the remap grace window (see below).
type Prefixes  interface{ For(tenant TenantID) PrefixMap }
type PrefixMap interface {
    Current(prefix string) (EntityType, bool) // inbound: prefix -> type
    Retired(prefix string) (EntityType, bool) // inbound: a prefix we recently moved off
    Alias(typ EntityType) (string, bool)      // outbound: type -> prefix, for minting
}

// Routes maps an internal TYPE to the upstream that owns it. Note what is NOT
// here: no path parsing, no per-entity handler registration, no switch.
type Routes interface{ Upstream(typ EntityType) (Upstream, bool) }

Resolution is then one straight line with no branching on entity type anywhere:

// Resolve turns a public id into an internal reference. It answers exactly two
// questions - which type, which ids - and refuses everything it cannot answer.
// It deliberately does NOT answer "is the caller allowed to", see the next section.
func (g *Gateway) Resolve(tenant TenantID, want EntityType, raw string) (Ref, error) {
    pid, err := ParsePublicID(raw) // split on the separator, nothing more
    if err != nil {
        return Ref{}, ErrUnknownID // malformed: not a shape we ever mint
    }

    m := g.prefixes.For(tenant)
    typ, ok := m.Current(pid.Prefix)
    if !ok {
        typ, ok = m.Retired(pid.Prefix)
        if !ok {
            return Ref{}, ErrUnknownID // unknown prefix: fail closed, always
        }
        g.audit.Emit(RetiredPrefixHit{Tenant: tenant, Prefix: pid.Prefix})
    }

    // The route declares what it expects; the token declares what it is.
    // A mismatch is a contract violation, not a lookup miss - and it costs no decode.
    if want != TypeAny && typ != want {
        return Ref{}, ErrWrongType
    }

    // From here it is Part 2 unchanged: the (tenant × type) salt cell decodes it,
    // walking the salt history and firing the old-salt tripwire on a retired hit.
    ids, meta, err := g.codecs.For(tenant).Type(typ).Decoder().Decode(pid.Token)
    if err != nil {
        return Ref{}, ErrUnknownID
    }
    return Ref{Tenant: tenant, Type: typ, IDs: ids, SaltAge: meta.SaltAge}, nil
}

// Dispatch is a lookup, not a decision. Adding an entity type adds a row to the
// routing table and touches no code in the gateway.
func (g *Gateway) Dispatch(ref Ref) (Upstream, error) {
    up, ok := g.routes.Upstream(ref.Type)
    if !ok {
        return nil, ErrNoRoute
    }
    return up, nil
}

Two things I want to point at in that code, because they're the whole reason I like this shape:

Resolve has no knowledge of any specific entity. No case TypeOrder:. Adding invoices is a config row and an upstream registration. The gateway does not grow.
want comes from the route, not from the token. The token never gets to tell the gateway what it is on a typed route. /api/v1/orders/{id} passes TypeOrder and a comment token dies there. Only a deliberately generic route - a share link resolver, say - passes TypeAny, and that route is exactly the one where the prefix is doing real work, because nothing else knows the type.

Two doors

Here's the deployment consequence, and it's optional in a way the rest of this isn't.

If the public surface and the internal surface are genuinely different surfaces, they can be different front doors - a public gateway and an internal gateway, sitting behind an edge router that decides which door a request is even allowed to knock on. Public tokens and raw int64 traffic then never share an entry point.

Shaped as an edge-router config, it's less clever than it sounds:

# ---- public door: opaque tokens only, open to the internet -------------------
server {
    listen 443 ssl;
    server_name api.example.com;

    # A public id is <prefix>_<token>. If it doesn't have that shape, it isn't
    # a public id, and the request never reaches an application.
    location ~ "^/api/v1/[a-z-]+/(?<prefix>[a-z]{1,3})_(?<token>[0-9A-Za-z]{6,40})$" {
        proxy_pass http://public_gateway;
    }
    location ~ "^/api/v1/" {
        proxy_pass http://public_gateway;   # collection routes: no id in the path
    }
    location / { return 404; }
}

# ---- internal door: raw int64 traffic, not reachable from outside ------------
server {
    listen 8443 ssl;
    server_name gateway.internal;

    allow 10.0.0.0/8;                       # the mesh, and nothing else
    deny  all;

    location / { proxy_pass http://internal_gateway; }
}

What that buys, concretely: a raw int64 in a path can never reach the public gateway, because the public listener has no location that matches a bare number. Not "the gateway rejects it" - the request never becomes a request. That's a different quality of guarantee than an application-level check, and it survives an application-level bug.

The thing to be careful about here

Notice what the config above does not do: it does not know your prefix map. It matches the shape [a-z]{1,3}_<token>, not the set {o, c, iv, l}.

That's on purpose, and it's the single most important line in this article's honest column. The prefix map is tenant-editable. An edge-router config is deployed. The moment you key a deployed routing rule on a value a tenant can change from an admin panel, you have built a system where a customer action can break routing, and the failure will happen at the layer with the worst observability and the slowest rollback.

So: the edge router separates doors by shape. The gateway dispatches by prefix, because the gateway is the thing that can read the map. Coarse where it's static, fine where it's dynamic. Cross that line and the tenant-editable value becomes a deploy dependency.

The honest part

Everything above is mechanism. Here's what it isn't, in the same blunt register as "a hashid is not encryption" from Part 2.

A prefix is not authentication, and routing is not authorization

The prefix tells you what kind of thing a token claims to be. That is all it tells you. It is in the clear, it's guessable in about four attempts, and anyone can put o_ in front of a string.

So the rule from Part 2 does not move an inch: after the decode, every request runs the tenant-scoped ownership check. Does this authenticated caller have the right to this object? Not "does the row exist" - the dangerous case is exactly the one where the row does exist and belongs to somebody else. Routing a request to the correct upstream is not a statement about who's allowed to be there; it's a statement about who should be asked.

Layer	What it does	What it does NOT do
Edge router	keeps public and internal traffic on separate listeners	authenticate anybody
Prefix	says which type, which salt cell, which upstream	prove the token is real
Hashid decode	turns a valid token into `int64`(s)	prove the caller may see them
Ownership check	decides	—

Only the last row is a security control. Everything above it reduces the number of ways to reach the check, and none of it replaces the check.

Fail closed, always

A prefix that isn't in the map - unknown, retired past its window, or made up - must be rejected. Not "guessed at", not "tried against every salt cell until one decodes". That fallback sounds helpful and is precisely a type-confusion oracle: try x_<token> against every type and one of them eventually resolves, and now the attacker knows what the token is.

incoming public id      "o_kZ9mQ2xR"
        │
        ▼  split on the separator
   malformed? ────────────────────────────► 404   (never a shape we mint)
        │ no
        ▼  look up the prefix in THIS tenant's map
   current prefix?  ──yes──► type
        │ no
        ▼
   retired prefix?  ──yes──► type  +  🚨 AUDIT: retired-prefix hit
        │ no
        ▼
   unknown          ────────► 404   (fail closed — never probe other types)
        │
        ▼  route says TypeOrder, token says comment?
   type mismatch    ────────► 404   (contract violation, no decode attempted)
        │
        ▼  decode under the (tenant × type) salt cell  → Part 2, unchanged
        ▼  tenant-scoped ownership check               → Part 1, unchanged
        ▼  serve

A tenant-editable routing key needs a window

If a tenant renames o to ord on Tuesday, links minted on Monday still say o. Same problem as salt rotation, same solution, and it has to be built at the same time as the feature - not after the first support ticket:

the map keeps retired prefixes with the type they used to mean, exactly like the salt history keeps retired salts;
inbound resolution tries current, then retired;
outbound minting always uses the current alias;
a hit on a retired prefix is audited, which - same as the old-salt tripwire in Part 2 - tells you how much of the wild is still on the old naming, and therefore when it's safe to actually drop it.

If you skip the retired map, a prefix rename is a hard break of every link in every email your customer ever sent. That is not a rotation, it's an outage with a settings page in front of it.

Two gateways cost two of everything

This is the trade-off I want to state plainly, because "separate the surfaces" reads like an unambiguous win and it is not.

	One gateway, strict internal split	Two gateways behind an edge router
Deploy paths	one	two, and they can skew
Configs	one	two, and they drift
The public/internal boundary	enforced by code and review	enforced by network topology
A bug that leaks internal shape	can reach the public surface	cannot cross the listener
Cost of adding an endpoint	one place	decide which door, then one place
Failure mode	a missing check	a mismatched pair of configs

Two doors buys you a structural guarantee instead of a procedural one, and structural guarantees survive bad days. It costs you a second deploy path, a second config, and one more place for drift - and drift between two gateways is a genuinely unpleasant class of bug, because each half looks correct on its own.

One gateway with a strict public/internal split inside it is a legitimate choice, and often the better one. If your team is small, if your public surface is narrow, if the internal surface is only ever reached from inside the mesh anyway - one gateway with the two surfaces as separate route trees, separate middleware chains and separate listeners in the same process gets you most of it for a fraction of the operational weight. The seam is in the id either way. Where you put the wall around the seam is a capacity question, not a correctness question.

What this is: capabilities, not a prescription

Three parts in, the pattern of this series is probably clear: I keep showing machinery and then telling you not to ship all of it. That's deliberate, and it applies here more than anywhere, because everything in this part is optional in a way Parts 1 and 2 weren't.

Typed prefix. Buys type-first dispatch, cheap wrong-type rejection, and generic resolver routes. Costs a parsing rule you can never change and one more concept for the next engineer. Worth it the moment you have more than one entity type on a shared public surface, or a single generic link-resolver route.
Prefixes as tenant configuration. Buys tenants control of their own public naming. Costs a retired-prefix map, a rotation UI, and a rule about never keying deployed infrastructure on it. Only worth it if a tenant's public API is genuinely their product.
An anonymous public surface. Buys freedom to reshape the internals without breaking anyone. Costs nothing but discipline, and I'd argue it's the one item on this list that's close to unconditional - it's cheap in advance and impossible to retrofit once customers have your internal names in their code.
Two doors. Buys a structural boundary. Costs two deploy paths, two configs, and a drift surface. Worth it when the cost of a leaked internal surface is high enough to justify running two things.

There are plenty of ways to keep a public and an internal surface apart - separate deployments, mutual TLS on the internal side, an API-management layer in front, gRPC internally and REST externally with no shared handler code at all. This is the one built on the identifier, and its whole argument is that the identifier already crosses the boundary on every request, so the boundary might as well be enforced there.

The wall that isn't a dial, and never becomes one: the tenant-scoped ownership check on every request. Everything else on this page is a trade-off you get to make on purpose.

The judgment is still the human part

Same note I closed Part 2 on, because three parts of machinery haven't changed it. Ask an assistant to design a public API and you'll get sensible-looking routes with numeric ids in them, internal type names in the paths, one gateway serving both surfaces, and error bodies that name your database constraints. Fast, clean, demos beautifully. It won't tell you, unprompted, that the identifier is the seam, that a prefix makes the token self-describing before the decode, that keying an edge-router config on a tenant-editable value builds a customer-triggered outage, or that an unknown prefix must fail closed rather than politely try every salt cell.

The mechanics are cheap. The judgment about which of these to actually run - and what each one costs you at 3am - is the part that's still yours.

If you build serious backends, this is the kind of decision I keep writing up. Follow along on github.com/brilliant-almazov. And if your public API and your internal API are the same API right now: what would it cost you to change the shape of one service? I'd genuinely like to compare notes.

Snowflake IDs - Part 2: Across the Wire, the URL, and the Browser

Anton Brilliantov — Wed, 19 Aug 2026 11:27:00 +0000

Part 1 settled the primary key: a 64-bit Snowflake in a BIGINT, generated at the edge. This part is about what happens when that id has to leave the trust boundary - into a public URL, a third-party API, a browser. Raw ints don't go out the door, a browser can't count that high without corrupting them, and a leaked link has to be revocable. Here's the whole boundary: hashids at the edge, composite tokens that carry a whole ownership chain, tenant-controlled salt rotation with a leak tripwire, and the one dull rule that saves your data - never send a naked int64 to a browser.

👋 Hi again, I'm Anton - PHP/Symfony and Go, mostly writing about breaking a monolith into services without breaking the business. Part 1 argued for int8 + Snowflake as the primary key and promised the harder half: moving that id across boundaries. That's this post. As in Part 1, I'm not writing any of these primitives by hand - hashids/Sqids libraries exist in every language; this is about where the translation lives and why. Running notes: github.com/brilliant-almazov.

Inside the mesh, the id is just an int64 and life is simple. The trouble is entirely at the edges, and there are exactly three of them: the service boundary (fine, send the int), the public boundary (never send the int), and the browser (can't even hold the int). Get any one wrong and you leak growth numbers, hand out IDOR, or silently corrupt the wrong record.

Inside the trust boundary: raw int8, no games

Between services, the ID is just an int64. gRPC carries it as int64, the proto field is int64, one service hands order_id = 7239344029703798784 to the next and nobody obfuscates anything. Inside the mesh there's no attacker to hide from and every layer of encoding is just latency and confusion. Raw ints flow freely behind the wall.

The public surface is where it all changes.

Outward: raw ints never leave the building

On the public API, in URLs, in anything a browser or a third party sees, the raw int never appears. The one exception is an admin panel that already sits behind authentication - staff can see the real id because they've earned the right to. Everyone else gets a hashid.

A hashid is a reversible, salted encoding of an int64 into a short opaque string - 7239344029703798784 becomes something like kZ9mQ2xR. Encode on the way out, decode on the way in. Off-the-shelf, every language: the classic is hashids (speps/go-hashids in Go, hashids/hashids or vinkla/hashids in PHP); the maintained successor is Sqids (sqids/sqids-go, sqids/sqids-php). Don't write your own - and notice the important property both share: they encode a list of numbers, not just one. Hold that thought, it's the composite trick below.

The salt isn't one global value - it's scoped per tenant, and within a tenant, per entity type. An order has a different salt from a project, which differs from a user, and all of them differ across tenants. So the same internal id encodes to a different string for each customer and each type - no cross-tenant correlation, no cross-type correlation, no "tenant A's id 5 looks like tenant B's id 5." Think of it as a small matrix of salts, (tenant × entity_type), with a tenant-level master salt above it - and every cell in that matrix is independently rotatable. More on why that granularity matters right below.

These are the clean URLs the outside world sees - opaque, tenant-scoped, no naked integers:

                        PUBLIC (browser / API)              INTERNAL (mesh)
  single entity   GET /api/v1/orders/kZ9mQ2xR        ->     order_id = 7239344029703798784
  another tenant  GET /api/v1/orders/7bQ0pLMn        ->     order_id = 7239344029703798784   (same id, different salt)
  admin (authed)  shows  kZ9mQ2xR  =  7239344029703798784   (raw id on purpose, behind login)

Same row, different faces. The public gets the hashid, the mesh gets the int, and the only place both are shown side by side is behind a login.

A public id is not only a hashed number - it can name its own type

Everything above shows a bare token: an opaque string and nothing else, with the URL path (/orders/…) doing the job of saying what kind of thing it points at. There's a better shape. The outward id can be <prefix><token> - a short letter or two in front that names the entity type, and then the salted hashid.

o for an order, c for a comment, p for a project, u for a user, inv for an invoice. The orders example I've been using is just an example: nothing here is orders-specific. Any entity type you expose on the public surface gets its own prefix, and the prefix is the only thing that differs between them.

  bare token       kZ9mQ2xR         the TYPE comes from the route
  prefixed token   o·kZ9mQ2xR       the TYPE comes from the ID itself
                   │ └───────────── the salted hashid: one id, or a whole tuple
                   └─────────────── public alias for an internal entity type

  o kZ9mQ2xR   order     ->  decode with the (tenant × order)   salt cell
  c 7bQ0pLMn   comment   ->  decode with the (tenant × comment) salt cell
  p 4hT1nW8s   project   ->  decode with the (tenant × project) salt cell

  one generic route is now enough:  GET /api/v1/r/o kZ9mQ2xR

The prefix makes the id self-describing at the edge

This reverses the usual order of operations. Normally you decode first and then discover what you're holding. With a prefix, the gateway knows three things from the first character, before it decodes anything:

what kind of object the token points at,
which salt cell to decode it with - the (tenant × entity_type) cell from the matrix above,
which handler owns it.

And it closes a whole class of confusion for free: a token minted for one type cannot be replayed as another. Feed an o… token to the comment path and two independent things disagree at once - the prefix says order, and the comment salt cell doesn't decode it anyway. There's no "close enough" outcome; it fails closed.

// The prefix is read BEFORE the decode: it selects the salt cell and the owner.
// The mapping is CONFIG, resolved per tenant - never a switch statement in code.
func (g *Gateway) DecodePublic(tenant TenantID, publicID string) (EntityType, []ID, error) {
    prefixes := g.prefixes.For(tenant)

    prefix, token, ok := prefixes.Split(publicID) // "okZ9mQ2xR" -> "o", "kZ9mQ2xR"
    if !ok {
        return "", nil, ErrUnknownID
    }
    typ, ok := prefixes.Type(prefix) // "o" -> order, "c" -> comment (this tenant's map)
    if !ok {
        return "", nil, ErrUnknownID // unknown prefix: reject, never try the other cells
    }

    // Same resolution chain as before - the prefix just told us which cell to use.
    ids, meta, err := g.codecs.For(tenant).Type(typ).Decoder().Decode(token)
    if err != nil {
        return "", nil, ErrUnknownID // prefix and salt cell disagree -> not ours
    }
    if meta.SaltAge > 0 && !g.policy.Accepts(tenant, typ, meta.SaltAge) {
        return "", nil, ErrLinkRevoked
    }
    return typ, ids, nil // authorization still runs after this. Always.
}

Prefixes are configuration, not code

The prefix map is data, not a deploy. It lives per tenant and is editable from the admin panel - the same self-serve surface that already rotates salts in this article. One tenant's orders are o, another's are x7, and neither needed an engineer.

That's safe for exactly the reason rotation is safe: changing a prefix changes only the outward encoding, never the stored BIGINT. No migration, no data touched, no deploy. It's the same property the whole design keeps cashing in - the id underneath is a stable int8, so everything about how it looks outside is a configuration surface.

With the same obligation attached: a prefix map needs the same history discipline as a salt. Links already in the wild carry the old prefix, so a renamed prefix has to stay resolvable, with the same three strategies as a retired salt - accept + audit, grace window, hard cutoff. Rename a prefix without keeping the old mapping and you've broken every bookmark, exactly as a destructive salt rotation would.

This is how the public surface becomes anonymous

Add it all up and the public API stops describing your system. It doesn't expose the numeric id, it doesn't expose the table, it doesn't expose the internal route or the internal type name. What goes out is a public alias for an internal type - deliberately chosen, tenant-scoped, and swappable at will.

Be honest about the kind of protection that is: it's anonymity of shape, not secrecy. Whoever holds a link can see its prefix and, with a handful of links, work out that o and c are two different kinds of thing. What they can't see is which things, how many there are, what the storage looks like, or whether two tenants' o means the same type at all. It hides your internals from a stranger reading a URL; it is not a secret channel, and - like everything else on this page - it is not authorization.

Composite hashids: put the whole ownership chain in one token

Here's the trick the "list of numbers" property unlocks, and it's my favourite. You don't have to encode just one id. Pack the master and the child together - [project_id, config_id], [order_id, line_id] - into a single opaque token.

  naive (two separate hashids)   GET /api/v1/projects/kZ9mQ2xR/configs/7bQ0pLMn
                                 two tokens, two decodes, two lookups, easy to mismatch

  composite (one token)          GET /api/v1/c/9Kd2mQ7rX4
                                       │  decode -> [project_id, config_id]
                                       ▼
                                 the token carries the WHOLE chain

On decode you get the whole chain back, so the gateway validates top-down before any handler runs: does the master exist and belong to this tenant? then is the child actually under that master? A tampered or mismatched pair fails the master -> child check at the edge - the handler never sees an inconsistent pair.

// Encoder and decoder are BOTH interfaces, reached through a resolution CHAIN.
// You never touch a salt directly - you resolve down to the thing that owns it:
//   codecs.For(tenant)           -> the tenant's codec set
//          .Type(entityType)     -> the (tenant × type) salt cell
//          .Encoder() / .Decoder()
type Codecs       interface{ For(tenant TenantID) TenantCodecs }
type TenantCodecs interface{ Type(typ EntityType) TypeCodec }
type TypeCodec    interface {
    Encoder() Encoder // encodes with the CURRENT salt
    Decoder() Decoder // decodes across the salt HISTORY (+ audit)
}
type Encoder interface{ Encode(ids ...ID) (string, error) }
type Decoder interface{ Decode(token string) ([]ID, DecodeMeta, error) } // meta carries SaltAge

// A composite [master, child] is keyed by its MASTER type; the route supplies
// the types, they're never guessed. childType names what the 2nd id must be.
func (g *Gateway) DecodeScoped(
    tenant TenantID, masterType, childType EntityType, token string,
) (Scope, error) {
    // resolve the chain: tenant -> master type -> decoder for that (tenant × type) cell.
    dec := g.codecs.For(tenant).Type(masterType).Decoder()
    ids, meta, err := dec.Decode(token) // a token minted for another type/tenant won't decode
    if err != nil || len(ids) != 2 {
        return Scope{}, ErrUnknownID
    }
    if meta.SaltAge > 0 && !g.policy.Accepts(tenant, masterType, meta.SaltAge) {
        return Scope{}, ErrLinkRevoked // retired-salt strategy; audit already fired in Decode
    }
    master, child := ID(ids[0]), ID(ids[1])

    // Ownership is an authorization, not an existence check (see next section).
    if !g.owns.Is(ctx, tenant, masterType, master) {    // master is THIS tenant's, THIS type?
        return Scope{}, ErrForbidden
    }
    if !g.owns.ChildOf(ctx, master, childType, child) { // child is childType UNDER that master?
        return Scope{}, ErrForbidden
    }
    return Scope{MasterType: masterType, Master: master, ChildType: childType, Child: child}, nil
}

// route wiring makes the types explicit, never guessed:
//   GET /api/v1/projects/{token}/... -> DecodeScoped(tenant, TypeProject, TypeConfig, token)
//   encoding is the same chain: g.codecs.For(tenant).Type(TypeOrder).Encoder().Encode(orderID)

One token, one decode, one ownership chain proven before the handler starts. That's a lot of IDOR surface closed at the door.

A token is a tuple you design - not just a pair

[master, child] is only the simplest case. The real leverage is that a hashid encodes a list of numbers, so you design the schema - pack whatever the edge needs to make one decision from one token. "Do everything through a single link": the URL carries the whole context and the gateway rebuilds it in one decode, with no extra lookups just to learn what the token even points at.

one token  =  a designed tuple of numbers, not a single id

  [ tenant_id | resource_type | resource_id | expiry_ts | nonce ]
       │             │              │             │          └ one-time guard
       │             │              │             └ self-expiry
       │             │              └ what it points at
       │             └ which KIND of thing (order? invoice? export?)
       └ who it belongs to  →  checked before anything else

Scenario: a self-describing, one-time link

The link that must (a) belong to a tenant, (b) point at exactly one resource, (c) expire, and (d) work exactly once - a share / download / magic link. Put all of it in the token:

GET /api/v1/l/9Kd2mQ7rX4kP… → decode → [tenant_id, resType, resID, expiry, nonce]

and the gateway settles all four checks before any handler runs:

// One self-describing token carries the whole decision. Decode once, check four
// things, serve. The token is a CARRIER; the security is in the server checks.
func (g *Gateway) OpenLink(caller TenantID, token string) (Resource, error) {
    ids, _, err := g.codecs.For(caller).Type(TypeLink).Decoder().Decode(token)
    if err != nil || len(ids) != 5 {
        return Resource{}, ErrUnknownID
    }
    tenant, resType, resID := TenantID(ids[0]), EntityType(ids[1]), ID(ids[2])
    expiry, nonce := time.Unix(int64(ids[3]), 0), ID(ids[4])

    if tenant != caller                    { return Resource{}, ErrForbidden } // (a) ownership
    if g.clock.Now().After(expiry)         { return Resource{}, ErrExpired }   // (c) expiry
    if !g.nonces.Burn(ctx, tenant, nonce)  { return Resource{}, ErrUsed }      // (d) one-time
    return g.load(ctx, tenant, resType, resID)                                 // (b) the resource
}

Be blunt about what the token is and isn't. A hashid/Sqids token is obfuscation, not a signature. It compresses a tuple into an opaque string; it does not prove the tuple wasn't forged by someone who knows the (public) algorithm and guesses the salt. So the security of a one-time link never rests on the encoding:

one-time-ness comes from the server-side nonce burn, not from the token;
expiry is enforced by comparing to your clock, never trusted from the number;
ownership is the authz check from the next section;
if the link must be tamper-proof (a capability an attacker must not forge), carry a real HMAC alongside - or use a signed token (PASETO / JWT) for that part. The hashid is the compact envelope; the MAC is the lock.

The composite token is a superb carrier - one URL, all the context, one decode. It is not, by itself, a security mechanism.

Even strings fit: it's numbers all the way down

Hashids encode numbers - but any string is numbers, so a short string can ride in the same token. Two standard routes:

Hex / bytes. hashids has encodeHex / decodeHex: feed it a hex string (a UUID's hex, a short byte blob) and it round-trips - the clean way to carry a UUID inside a composite.
Char codes. Map each character to its code point and encode the list. In PHP that's ord() per char (chr() to reverse); in Go a []byte / []rune. A short slug or status code becomes just more numbers in the tuple.

// PHP: a short string -> numbers -> hashid, and back
$nums  = array_map('ord', str_split("OPEN"));      // [79, 80, 69, 78]
$token = $hashids->encode(...$nums);
$back  = implode('', array_map('chr', $hashids->decode($token)));  // "OPEN"
// or, for a UUID / raw bytes as hex:
$token = $hashids->encodeHex($uuidHex);            // decodeHex() to reverse

Keep it tiny, though: a hashid grows with the count and size of the numbers, so a composite token is for ids, type codes, timestamps, short flags - not for stuffing blobs. The moment you're tempted to encode a paragraph, you want a real signed token or a lookup key, not a hashid. "Numbers all the way down" is a neat trick; the discipline is keeping the tuple small.

In a multitenant system, every lookup is an authorization - not an existence check

This is the rule the hashid and the composite token both lean on, and it has to be said explicitly because it's the one that actually keeps tenants apart. Decoding an id to an int64 tells you which row; it never tells you the caller is allowed to see it. So every request, after decode, answers a second question before the handler runs: does this authenticated caller (this tenant, this user) have the right to this object?

"Found vs not found" is not the check. In a multitenant system the dangerous case is exactly the one where the row is found - it's a perfectly real order, it just belongs to a different tenant. If your lookup is SELECT ... WHERE id = ? you've already leaked it; the query has to be WHERE id = ? AND tenant_id = ? (and for a child, AND <master>_id = ?), or the authz has to be a separate, explicit gate that runs regardless. Same for the composite: the master → child validation earlier isn't "do these ids exist," it's "does this tenant own the master, and is the child under that master." A wrong-tenant id that happens to exist must come back 403/404, never the object.

The unguessable Snowflake and the salted hashid lower the odds anyone reaches a foreign id; the tenant-scoped authorization check is what makes reaching it harmless. First wall reduces attempts, second wall is the one that must never be missing - exactly the "an id is never authorization" point from Part 1, made concrete for multitenancy.

Salt rotation - self-serve, with a history so old links still work

Salts get rotated: a leak, a policy, periodic hygiene. And here's a benefit that falls straight out of int8 + Snowflake: because the underlying id is a stable BIGINT, rotating the salt changes only the outward encoding, never the data. So rotation can be a tenant self-service action - a button in their admin panel. No engineering, no migration, no deploy: the tenant rotates their own salt and every new link they hand out uses it.

That makes leaked links revocable by the customer who owns them. But rotating naively would break every bookmark and emailed link at once - so I don't rotate destructively. I keep a salt history: current salt first, then every retired salt in order. On the way out, always encode with the current salt. On the way in, try current first; if it doesn't decode, try each historical salt until one does. Old links keep working; new links use the new salt.

Rotate anything, at any level - and always keep the history

The (tenant × entity_type) matrix plus the tenant master salt is the whole point: everything is rotatable, at whatever granularity the situation needs.

The tenant master salt - a nuclear rotate: re-scopes every type at once (a suspected full-account leak).
One entity type's salt - just order links leaked in an export? Rotate the order cell for that tenant and nothing else moves; project and user links keep resolving.
A single object - narrow blast radius when exactly one link is known-bad.

TENANT  acme-co
  master salt  ───────────────────────────────────────────────  rotate ⟳  (re-scopes everything)
     │
     ├── entity type: order    salt cell = [ current | v3 | v2 | v1 ]   rotate ⟳  (only order links move)
     ├── entity type: project  salt cell = [ current | v2 | v1 ]        rotate ⟳
     └── entity type: user     salt cell = [ current | v1 ]             rotate ⟳
                                             │        └─────────── retired: kept for back-compat + stats
                                             └── outward encoding only — the BIGINT id never moves

  salts are a (tenant × entity_type) matrix, each CELL keeps its own history.
  rotate any cell, or the master, or one object — always allowed, never touches data.
  per-cell strategy for retired salts:  accept+audit · grace window · hard cutoff

Because the id underneath is a stable BIGINT, none of these touch data - it's always only the outward encoding. Rotate the master, rotate one type, rotate one thing: always allowed, always cheap.

And historicity is mandatory, not optional. Every retired salt is kept - at every level - for two reasons: old links keep resolving (backward compatibility), and the audit trail below turns each retired salt into statistics on who's still using stale links. Whether a given retired salt still decodes is a per-level strategy, and it's worth making explicit and configurable:

accept + audit - old salt still resolves, every hit logged (default; maximum backward-compat, full visibility);
grace window - old salt resolves for N days after rotation, then hard-stops;
hard cutoff - old salt rejected immediately (a real leak you want dead now), but still recorded so you can see the leaked link being hammered.

Different levels can run different strategies (master salt on hard cutoff, a noisy order type on grace window). The rule that never bends: a retired salt is never silently forgotten - it's kept, and its use is always recorded, if only for the stats.

The point: every retired salt becomes a tripwire

Here's the part that turns a boring rotation mechanism into a security signal. When an incoming link decodes only under an old, retired salt - never the current one - that's information. Someone is walking a link minted before the last rotation: a stale bookmark, an old email, or a link that leaked and is being replayed. Rotation without audit is blind. Rotation with audit turns each retired salt into a tripwire: the moment a stale or leaked link is used, you get an audit event with the tenant, the token, and how old the salt was. Self-serve rotation gives the tenant the revoke button; the audit tells them who's still knocking with the old key.

incoming public id   "kZ9mQ2xR"
        │
        ▼
 ┌──────────────────────────┐
 │  gateway: decode hashid  │
 └──────────────────────────┘
        │  try salts in order
        ▼
   current salt   ──decodes?──►  int64   →  normal request        (no event)
        │ no
        ▼
   salt v(n-1)    ──decodes?──►  int64   →  serve  +  🚨 AUDIT: old-salt hit
        │ no
        ▼
   salt v(n-2)    ──decodes?──►  int64   →  serve  +  🚨 AUDIT: old-salt hit
        │ no
        ▼
   no salt matches  →  reject (404)  —  not a link we ever minted

  decoded ONLY under a retired salt  =  a stale / leaked / bookmarked
  link still in the wild.  Rotation without audit learns nothing.

// The concrete cell that .Encoder()/.Decoder() hand back. It IS both interfaces
// for one (tenant × type) pair: the encoder uses the current salt, the decoder
// walks the whole history. Nothing outside sees a salt - only Encode/Decode.
type typeCodec struct {
    tenant TenantID
    typ    EntityType
    salts  SaltHistory // newest-first: [current, v(n-1), v(n-2), ...]
    audit  AuditSink
    lib    HashidLib   // speps/go-hashids or sqids - the actual codec
}

func (c *typeCodec) Encoder() Encoder { return c }
func (c *typeCodec) Decoder() Decoder { return c }

// Encode always mints with the CURRENT salt.
func (c *typeCodec) Encode(ids ...ID) (string, error) {
    return c.lib.With(c.salts.Current()).Encode(ids)
}

// Decode walks this cell's history; a hit under a retired salt is a tripwire.
// The returned meta carries the SaltAge so the gateway applies its strategy.
func (c *typeCodec) Decode(token string) ([]ID, DecodeMeta, error) {
    for age, salt := range c.salts.All() { // 0 = current, then retired in order
        ids, err := c.lib.With(salt).Decode(token)
        if err != nil {
            continue // wrong salt, try the next in this cell's history
        }
        if age > 0 { // decoded under a RETIRED salt: a stale/leaked link is live
            c.audit.Emit(OldSaltHit{Tenant: c.tenant, Type: c.typ, Token: token, SaltAge: age})
        }
        return ids, DecodeMeta{SaltAge: age}, nil
    }
    return nil, DecodeMeta{}, ErrUnknownID
}

hashids is obfuscation, not encryption

I have to say this as loudly as the "id is not auth" line from Part 1, because they're the same mistake in a different hat. A hashid is obfuscation, not encryption. The salt is not a key; the encoding is reversible by anyone who knows the (public, off-the-shelf) algorithm and can guess the salt. Do not treat the opaque string as a secret. It buys you: no naked sequential ints in URLs, no trivial enumeration, no cross-tenant correlation, and - with salt history - a leak tripwire. It does not buy you authorization. Every request that arrives with a hashid still gets decoded to an int64 and then runs the exact same ownership check from Part 1. The opaque string and the authz check are partners, never substitutes.

The browser can't count that high (the castration bug)

This one bites everybody exactly once, and it's silent, which is the worst kind.

JavaScript's Number is an IEEE-754 float64. It represents integers exactly only up to 2⁵³ − 1 = 9,007,199,254,740,991. A 64-bit Snowflake id is bigger than that. So the moment it goes through JSON.parse (or any Number() in JS), the browser silently rounds it to the nearest representable float. The last digits get mangled. I call it getting castrated - the id comes back looking almost right, wrong in the tail, and nothing throws.

JavaScript Number  =  IEEE-754 float64
exact integers only up to   2^53 - 1  =  9,007,199,254,740,991

Snowflake id:   7,239,344,029,703,798,784      (19 digits, well past 2^53)
                       │
                       │   JSON.parse(...)  /  Number(...)
                       ▼
browser sees:   7,239,344,029,703,799,000      ← the tail is rounded off

  same shape, DIFFERENT record.  No error.  No warning.
  It reads, edits, or deletes the wrong row - and the logs look fine.

No exception, no NaN, no console warning. The id just quietly points at a different (or non-existent) record. You find out when a customer reports that saving one thing changed another, and you spend a day disbelieving your own database before you realise the browser did it in transit.

The fix is dull and absolute: serialize every int64 as a string in any web-facing JSON. Not "the big ones" - every int64, so there's no boundary to remember and no field that slips through. A string round-trips through JS untouched; you parse it back to an int64 on the server where 64 bits actually exist. Yes, even for the admin panel - the browser is a browser regardless of who's logged in.

{
  "order_id":  "7239344029703798784",
  "tenant_id": "7188990030102237184",
  "public_id": "kZ9mQ2xR",
  "total_cents": 4990
}

The two 64-bit ids are strings, the small total_cents stays a real number (nowhere near the ceiling), and public_id is the hashid for URLs. This isn't a hack I invented - it's exactly why proto3's canonical JSON mapping encodes int64 as a string by default. The people who designed the wire format hit this wall first and baked the fix into the standard. Follow them.

It all happens at the gateway

None of this belongs in your domain code. If your business logic knows what a hashid is, or remembers to stringify ids before responding, the concern has leaked into the wrong layer and you'll get it wrong somewhere. All of it lives in one place: the gateway / edge.

The gateway has exactly these jobs, and the services behind it have none of them:

type prefix - split the prefix off every inbound public id and resolve it, through the tenant's configured map, to an entity type: which salt cell decodes it, which handler owns it. On the way out, prepend the current prefix for that type.
hashid codec - decode every inbound public id (single or composite) to int64(s), walking the salt history and emitting an audit event on an old-salt hit; encode every outbound int64 to the current salt's hashid.
int64 ⇆ string - stringify every int64 on the way out to the browser, parse it back on the way in.

Behind that seam, services speak pure int8, end to end. The proto fields are int64, the domain objects hold int64, the SQL columns are BIGINT. Domain code never hears the words "hashid" or "string id" - it can't get the encoding wrong because it never does the encoding.

LEVEL 1   browser / public API
          sees opaque clean hashid URL strings, and every int64 as a "string"
               │  hashids in URLs, JSON with string-encoded ids
               ▼
LEVEL 2   ┌────────────────────────────────────────────────────┐
          │  GATEWAY  —  the only place any of this lives        │
          │    1. hashid codec: decode in / encode out           │
          │       + composite [master,child]  + salt history     │
          │       + audit on old-salt hits                       │
          │    2. int64  <->  string  in all web JSON            │
          └────────────────────────────────────────────────────┘
               │  raw int64  (gRPC int64)
               ▼
LEVEL 3   services  —  speak pure int8 end to end
          domain code never hears "hashid" or "string id"
               │  int64
               ▼
LEVEL 4   PostgreSQL  —  BIGINT primary keys, time-ordered inserts

One boundary, a handful of jobs, and everything inside it stays honest by never being asked to lie about a number.

The prefix is routable: one door in front, two gateways behind

Here's the part that makes the prefix more than cosmetics. Because the type is readable before the decode, the prefix is a dispatch key. One gateway can stand in front of everything and send o… to the order upstream and c… to the comment upstream - no decode first, no lookup, no need for the URL path to carry the type at all.

The more useful half is one level further out. The same property lets you split the public and the internal surface at the very edge. A front proxy - nginx-level, or any edge router - looks at the first character of the id and sends prefixed public tokens to the public gateway, while internal int64 traffic stays on the internal one. The two surfaces never share a door, and the decision costs a string prefix match.

  PUBLIC traffic                                   INTERNAL traffic
  o kZ9mQ2xR   c 7bQ0pLMn                          order_id = 7239344029703798784
        │           │                                        │
        └─────┬─────┘                                        │
              ▼                                              │
  ┌──────────────────────────┐                               │
  │  front proxy (edge)      │   matches the PREFIX only     │
  │  o… c… p…  →  public     │   no decode, no lookup, no db │
  │  unknown   →  public     │   default route is the SAFE   │
  └────────────┬─────────────┘   one, never the internal     │
               ▼                                             ▼
  ┌──────────────────────────┐              ┌──────────────────────────┐
  │  PUBLIC gateway          │              │  INTERNAL gateway        │
  │  prefix → salt cell      │              │  raw int64, no codec     │
  │  decode · authz · audit  │              │  service + staff traffic │
  │  int64 ⇆ string          │              │  authz, same as ever     │
  └────────────┬─────────────┘              └────────────┬─────────────┘
               └────────►  services - pure int8  ◄───────┘

  the prefix is a DISPATCH key. It is never the authorization decision.

Now the honest caveats, because this is the kind of mechanism that quietly turns into a security assumption:

The prefix is not authentication. Anyone can type an o. It tells you what a token claims to be, and nothing whatsoever about who is holding it. The tenant-scoped ownership check runs unchanged behind every door.
Routing must not become the authorization decision. "It arrived at the public gateway, so it's a legitimate public request" is the same error as "it decoded, so it's allowed" - just moved into the proxy config where nobody reviews it. Routing picks a handler; the handler still asks whether this caller may touch this object.
A wrong-prefix token fails closed. If the prefix and the salt cell disagree, the answer is a flat rejection - not a fallback that tries the other cells until something decodes. A router that shops a token around has rebuilt enumeration with extra steps.
A routing rule built on a tenant-editable value needs a fallback. Prefixes are self-serve, so a mapping can change while a request is in flight and while a proxy's config is stale. Two things keep that from becoming an outage or, worse, a leak: keep the retired mapping resolvable (accept + audit / grace window / hard cutoff, exactly as with salts), and make the default route the safe one - an unknown prefix goes to the public gateway and is rejected there. It must never fall through to the internal side.

And the framing I'd want kept with it: there are many patterns for keeping a public gateway and an internal gateway safely apart - separate hostnames, separate networks, mutual TLS on the internal side, a header the edge strips and the inside trusts. This one is simply the pattern built on the id itself. If you already have prefixed public ids, it's nearly free. If you don't, "I want to route by prefix" is not on its own a good reason to introduce them. It's a capability to pick from, not a prescription.

The real question: what's possible vs what's right for you

Here's the thing I want to be honest about after two parts of machinery: everything here is a capability, not a prescription. Composite tokens, self-describing one-time links, a per-(tenant × type) salt matrix with per-cell rotation strategies, typed prefixes and prefix-based routing at the edge, strings-as-numbers - it all works, and it's all optional. The question that actually matters isn't "can I?" (you can) - it's "which of these fit me?", and only you can answer it. In a lot of cases there's more than one right way; you're balancing a few forces at once:

Simplicity. Fewer moving parts = fewer ways to be wrong at 3am. A single per-tenant salt with plain hashids may be everything you need; the full matrix with three retired-salt strategies is power you pay for in complexity forever.
Security. What does a leak, an enumeration, or a replay actually cost you? A public blog's ids and a health record's ids are different threat models. Don't buy a vault for a doormat - and don't put a doormat on a vault.
A new approach. A clever composite one-time token is elegant, but every non-standard mechanism is something the next engineer has to learn, trust, and not break. Novelty carries a tax; sometimes it's worth it, sometimes "boring and obvious" wins.
Support / operations. Salt histories, audit sinks, nonce stores, rotation UIs - that's all real code to run, monitor, migrate, and hand over. The most elegant design you can't operate is a liability, not an asset.

So I'm not telling you to ship all of this. I'm showing that it's possible and how, so you can pick the subset that matches your threat model and your team's capacity. Sane default: start simple - int8 keys, plain per-tenant hashids, and the ownership check - and add each layer (composite tokens, rotation, audit, one-time links) only when a real requirement pulls it in, never because it's clever. The one dial that isn't a dial - the wall you never remove - is the tenant-scoped authorization check. Everything else on this page is a trade-off you get to make on purpose.

The judgment is the human part

I lean hard on AI assistants for work like this, and my take doesn't move: AI amplifies a good engineer and exposes a weak one. Ask a model for a data model and it'll cheerfully hand you UUIDv4 keys everywhere, raw sequential ids in your URLs, and a hand-rolled generator it didn't need to write - fast, clean-looking, passes the demo. It won't, unprompted, tell you to use int8 + Snowflake for locality, that the raw ints must stop at the trust boundary, that one composite token can carry the whole ownership chain, that a retired salt is a free tripwire, or that the browser is about to castrate every id over 2⁵³ and corrupt the wrong record in silence.

The mechanics are cheap and mostly already written - Snowflake and hashids libraries exist; you configure them, you don't author them. The judgment - int8 + Snowflake for the key, raw ints stop at the wall, composite tokens for ownership, self-serve rotation with an audit tripwire, every int64 a string at the browser - that's the part the human owns. Point the multiplier at a good design and it ships fast. Point it at "just give me some ids" and it'll help you build the leak faster than you can schedule the incident review.

If you build serious backends, this is the kind of decision I keep writing up. Follow along on github.com/brilliant-almazov. And if your URLs have raw sequential ids in them right now, or your API sends int64s as numbers: which one is going to page you first? I'd genuinely like to compare notes.

Snowflake IDs - Part 1: Why int8 + Snowflake, and Never UUID

Anton Brilliantov — Mon, 17 Aug 2026 12:19:33 +0000

An identifier is load-bearing infrastructure, not a boring column. Part 1 of a short series on how I pick identifiers and why: a 64-bit Snowflake in a BIGINT, generated at the edge, time-ordered, and small - versus a random UUID that shreds your indexes or a BIGSERIAL that prints your growth rate on every URL. No custom generator - the good implementations already exist; this is about the reasoning, not the wheel.

👋 Hi, I'm Anton - a software engineer working mostly in PHP/Symfony and Go. Most of what I write is about the slow, careful business of breaking a large PHP monolith into Go services while it keeps serving real customers, and identifiers are the one thing that has to stay coherent while everything else moves. This little two-part series pulls the ID decision out on its own. Part 1 (this one): why int8 + Snowflake is the right primary key. Part 2: how you move that id across a service mesh, a public URL, and a browser without leaking or corrupting it. Running notes live on my GitHub: github.com/brilliant-almazov. No hype, just the real work.

An ID is the most-touched value in the whole system. It's the primary key, the foreign key, the URL segment, the cache key, the gRPC field, the log line you grep at 3am. Pick it badly and the cost doesn't show up in a demo - it shows up months later as index bloat, a competitor reading your order count, or a support ticket that says "it edited the wrong record and nobody knows why." So I treat the ID as a design decision, not a default, and I make it deliberately.

An ID has to be two things at once: small and unguessable-ish

Small, because it's in every index and every join. Unguessable-ish, because it ends up in places I don't fully control. Those two pulls usually fight - the value that's cheapest to store (a sequential counter) is the one that leaks the most, and the value that leaks the least (a random 128-bit UUID) is the one that wrecks your indexes. A Snowflake in a BIGINT is the point where they stop fighting.

64-bit BIGINT: eight bytes, and the B-tree loves it

A BIGINT is 8 bytes. A UUID is 16. That 2× isn't just disk - it's every index page, every foreign key, every tuple in the cache. Double the key width and you halve how many entries fit in a B-tree page, which means more pages, deeper trees, more cache misses on every lookup.

But the width is the smaller half of the story. The bigger half is ordering. A Snowflake's high bits are a timestamp, so IDs come out time-ordered - roughly sorted by creation. New rows land at the right edge of the index, next to the last one, so inserts append to warm pages instead of scattering across cold ones. The index stays tight.

64-bit Snowflake ID   (fits in a signed BIGINT / int64)

  1 bit    41 bits                 10 bits      12 bits
 ┌──────┬─────────────────────┬───────────┬────────────┐
 │ sign │  timestamp (ms)     │ worker id │  sequence  │
 │  0   │  ms since a custom  │  0..1023  │  0..4095   │
 │      │  epoch              │  which    │  per-ms    │
 │      │                     │  node     │  counter   │
 └──────┴─────────────────────┴───────────┴────────────┘
  unused  high bits = time ->    where it   uniqueness
          IDs sort by creation   was minted within a ms

  time in the HIGH bits  =>  k-sorted IDs  =>  append-y, tight B-tree

Why not UUID

UUID is the reflexive "distributed id" answer, and it's the wrong shape for a primary key.

UUIDv4 is 128 bits of randomness. Every insert lands in a random spot in the index, forcing page splits, fragmenting the tree, and turning what should be an append into a random-write storm. On a hot table you feel it: write throughput drops and the index bloats far past the data it indexes. You pay that on every table, forever, for a property (global uniqueness) a 64-bit Snowflake already gives you at half the width.

UUIDv7 fixes the ordering problem - it puts a timestamp up front, so it's k-sorted like a Snowflake. It's a genuine improvement and a fine choice if you're wedded to the UUID type. But it's still 128 bits - twice the storage of what I need, in every index and every FK - and the timestamp-in-the-front makes it more enumerable, not less. A time-ordered 64-bit id gives me the same locality win at half the width, in a native BIGINT the database and every driver already understand, with a worker-id field that makes multi-node generation collision-proof by construction.

So: UUIDv4 loses on locality, UUIDv7 loses on width. Snowflake int8 wins both.

Already on UUIDs? They're just integers too

Here's the thing that makes this whole approach not a religious int-vs-UUID war: a UUID is only 128 bits, and 128 bits is just numbers. Any UUID can be represented as integers - two int64 (a hi/lo pair), a single 128-bit big integer, or, depending on the version, just the bytes that carry meaning (a v7's 48-bit timestamp prefix, a v4's random bits). Nothing about "it's a UUID" stops you from treating it as an int.

Which means: even if your primary keys are already UUIDs, you don't have to migrate them to get most of this. You keep the UUID column and, at the boundary, represent it as int(s) and do exactly the same thing - the same hashids/Sqids treatment (those libraries encode a list of numbers, so a 128-bit UUID is simply two numbers), the same per-(tenant × type) salt, the same rotation-with-audit, the same int64-as-string for the browser (Part 2). The principle is identical; the only thing that changes between UUID versions is which bytes you read.

Be honest about what that does and doesn't buy you, though. Representing a UUID as ints gives you the whole boundary story for free - clean URLs, hashids, salt rotation, no naked ids leaking. It does not fix the storage story: a UUID is still 128 bits in every index, so the locality and width costs from above stay until you actually move the primary key to a Snowflake int8. Treat-as-int is the zero-migration on-ramp; Snowflake int8 is the destination.

UUID versions: which bytes matter, and when a UUID actually earns it

"Represent it as ints" means read the bytes that matter for that version - and the versions are very different animals:

v1 (time + node) - a 60-bit timestamp split awkwardly (low bits first) plus a clock sequence and the machine's MAC. Time is in there but leaks the node; rarely what you want.
v4 (random) - 122 bits of pure randomness, no structure to read. Carry it as the full 128-bit (hi/lo) pair; there's nothing to sort by. This is the one that shreds index locality.
v5 (name-based, SHA-1) - deterministic: uuidv5(namespace, name) hashes a namespace + a name and always returns the same UUID for the same input. The namespace behaves like a salt. No randomness, no coordination - the id is a pure function of stable inputs.
v7 (unix-ms + random) - a 48-bit millisecond timestamp in the high bytes, then random. Read the top 48 bits and you've got a time-ordered key, k-sorted like a Snowflake - which is exactly why it's the good modern default if you're staying on UUIDs.

Why I'd actually reach for a UUID - v5 in particular. Snowflake int8 is my default for a minted primary key. But v5's determinism is a genuinely great property when you need to control the id instead of generating a fresh one: derive a stable id straight from a business key so the same input always maps to the same row (idempotency and dedup for free), content-address something, or reproduce an id across systems with no shared sequence and no lookup table. "The id comes from the data" is a real superpower for those cases - and it's precisely what a random Snowflake can't do.

Honest pros and cons, so it's a choice and not a reflex:

UUID good: a 128-bit space you'll never exhaust; fully decentralized; v5 deterministic/derivable (control the id); v7 time-ordered; a universally understood type with native columns everywhere.
UUID bad: 16 bytes in every index and FK (2× a BIGINT); v4 destroys locality; heavier logs, URLs, cache keys; and it's still not a secret, so it needs the exact same boundary treatment (hashids, per-tenant salt) as an int.

So the rule I actually use: default to Snowflake int8 for minted keys; reach for UUID v5 when I specifically need a derived, reproducible id; and whichever I hold, carry it as int(s) at the boundary and apply Part 2 unchanged. I use it this way because the id strategy should follow what the id is for - minted-and-fast versus derived-and-controllable - not which type is fashionable.

Snowflake = generate the ID at the edge, before the INSERT

The layout is the whole trick: timestamp | worker id | per-ms sequence. The timestamp gives ordering. The worker id says which node minted it, so two machines never collide. The sequence counts multiple IDs inside the same millisecond on one node. Put together, any node can mint a globally-unique, time-ordered ID locally, with no round-trip to a central sequence and no coordination.

That last part matters more than it sounds. It means the service about to create a row already knows the row's ID before it talks to the database. I can build the whole object graph - parent, children, the foreign keys between them - in memory, then insert it in one shot. No "insert, read back the generated id, insert the children" dance.

The generation is a solved problem - don't write your own. The layout is a well-known bit formula and there are mature, battle-tested libraries in every language. Pick one and move on:

Go: bwmarrin/snowflake, sony/sonyflake (a slightly different bit split), godruoyi/go-snowflake.
PHP: godruoyi/php-snowflake.
The original is Twitter's Snowflake; Instagram, Discord and Sony all shipped documented variants. Any of them is fine - what matters is the shape, not the repo.

The whole algorithm, as pseudocode, is just a couple of shifts - so you can see there's nothing to hand-roll:

# what every Snowflake library does, once you strip the mutex and clock handling
id = (ms_since_epoch << 22)   # 41 bits of time, in the high bits
   | (worker_id      << 12)   # 10 bits: which node minted it
   |  sequence                # 12 bits: per-ms counter, wraps at 4096

# time in the high bits => ids sort by creation
# worker_id => no cross-node collision
# sequence  => up to 4096 ids per node per millisecond

You configure the worker id per node and the custom epoch once, then call Next() from the library. That's it.

Where Snowflake comes from - the original, and the descendants

Snowflake isn't a pattern someone blogged into existence - it's a specific system Twitter built and open-sourced in 2010, and the choices above are load-bearing decisions from a real migration, not arbitrary bit-counting.

Twitter announced it in Announcing Snowflake (June 2010). The trigger was concrete: they were moving off MySQL (whose auto-increment handed them ids) onto Cassandra, which has no built-in id generation. They needed ids that were (1) roughly time-ordered so they'd sort, and (2) generated with no coordination - no central sequence, no lock, no single point of failure - at tens of thousands per second. That brief is the two properties this article keeps circling back to.

The original is a Scala network service (Thrift-based, predating Finagle), still readable in the archived repo twitter-archive/snowflake at the snowflake-2010 tag. Its layout is the one everyone copied: 1 sign bit · 41 bits ms timestamp (custom epoch, ~69 years of range) · 10 bits machine id (Twitter split it 5 datacenter + 5 worker = 1024 nodes) · 12 bits sequence (4096 ids per node per millisecond). It's now enough of a standard to have its own Snowflake ID writeup.

Those 10 machine bits are the whole multi-DC / multi-node story - why you can run this across datacenters with zero coordination:

  10 machine bits  =  5 datacenter  +  5 worker   =>  1024 independent minters

  DC A                      DC B                      DC C
  ┌────────────────┐        ┌────────────────┐        ┌────────────────┐
  │ worker 0 → id  │        │ worker 0 → id  │        │ worker 0 → id  │
  │ worker 1 → id  │        │ worker 1 → id  │        │ worker 1 → id  │
  │ worker 2 → id  │        │ worker 2 → id  │        │ worker 2 → id  │
  └────────────────┘        └────────────────┘        └────────────────┘
   no lock · no              no lock · no              no lock · no
   central sequence          central sequence          central sequence

  every node mints LOCALLY:  id = (time | dc | worker | sequence)
  the (dc,worker) field makes each node's id-stream DISJOINT  → collisions impossible
  no cross-node / cross-DC talk on the write path             → no bottleneck, no SPOF
  scale out = hand the new node a (dc,worker) id              → it just starts minting

The idea then spread by being re-balanced for different scale points:

Instagram - Sharding & IDs at Instagram brought the same idea inside Postgres with PL/pgSQL, minting time-ordered ids per shard (41 bits time, 13 bits shard, 10 bits per-shard sequence).
Sony - Sonyflake re-cut the bits for more machines: 39 bits of 10-ms time, 8 sequence, 16 machine bits (65,536 nodes) - a different point on the same trade-off curve.
Discord adopted the format wholesale and, tellingly, returns every id as a string in JSON to dodge the exact 2⁵³ browser bug Part 2 is about.

And you never hand-roll the bit-twiddling - mature libraries carry it: Go bwmarrin/snowflake and sony/sonyflake; every language has an equivalent. Pick an epoch and a worker id, call Next().

vs BIGSERIAL / SERIAL: three problems Snowflake doesn't have

BIGSERIAL is the reflexive default in Postgres, and it's fine right up until it isn't. It backs the column with a central sequence, and that sequence is three problems wearing a trench coat:

It's a coordination point. Every insert asks the sequence for the next value. On one box that's cheap; across shards or services it's a round-trip and a bottleneck you can't shard away.
You can't know the ID before the INSERT. The value is assigned by the database, on write. So you insert, read back the generated key, then insert anything that references it - extra round-trips, and awkward the moment you want to assemble a graph before persisting it.
Cross-shard collisions. Two shards each running their own sequence both hand out 42. Merge or federate them and the keys clash. Snowflake's per-node worker id makes that structurally impossible.

Snowflake fixes all three: no central sequence, ID known at the edge, no collision across nodes.

Property	UUIDv4	UUIDv7	BIGSERIAL	Snowflake int8
Width	128-bit / 16 B	128-bit / 16 B	64-bit / 8 B	64-bit / 8 B
Ordering	random	time-ordered	sequential	time-ordered (k-sorted)
Index locality	poor (page splits)	good	excellent	excellent
Where it's generated	client / anywhere	client / anywhere	central sequence	at the edge, per node
Know the ID before INSERT	yes	yes	no	yes
Cross-shard collision	~never	~never	possible	~never
Casual enumeration leak	none	some (time prefix)	trivial	hard

Generation performance, and the control-vs-throughput trade-off

The reason Snowflake feels free is that it is almost free. Minting an id is a couple of bit-shifts under a mutex - no I/O, no network. The mature libraries do millions of ids per second per process, and the only hard ceiling is the sequence field: 4096 ids per node per millisecond (~4M/s). Hit that ceiling inside one millisecond and the library simply waits for the next one - bwmarrin/snowflake blocks to the next ms, sony/sonyflake trades time resolution (10-ms units) for far more machine bits. Crucially it scales linearly: two nodes mint twice as fast because they share nothing. There's no contention to fight.

Now put BIGSERIAL next to that. Every id is a round-trip to a shared sequence - network latency plus lock contention on one hot object - and your id throughput is bounded by the database, not the app, and can't scale past that one authority. That's the SERIAL story in one line: the sequence is a single, coordinated, and therefore rate-limited source of truth.

Which surfaces the real axis you're choosing on - control vs generation:

Central sequence (SERIAL) - maximum control: dense, gapless, strictly monotonic, one authority that can hand you "invoice #1001 with no gaps." The price is coordination: a round-trip, a bottleneck, a single point, and no id before insert.
Snowflake int8 - maximum generation: local, uncoordinated, linear-scaling, id known before insert. The price is you give up density and a single authority - ids have gaps, ordering is only k-sorted, and it leans on the node clock.
UUID v4 - maximum independence, zero order or control (and the widest storage).
UUID v5 - control of a different kind: not dense/monotonic, but deterministic - the id is derived from the data (see the UUID section).

Balance it by the job, and don't be afraid to mix: Snowflake int8 on the hot write paths where throughput and edge-generation win, and a real sequence exactly where a business rule needs gapless, auditable numbering (invoice or receipt numbers - which are a domain concern, not a primary key). Pick control where the requirement is control; pick generation where the requirement is throughput.

The security angle - a SECOND control, never the gate

Here's where a sequential BIGSERIAL quietly hurts you, and it has nothing to do with the database.

Sequential IDs leak. Two ways:

Enumeration / IDOR. If order 41 exists, so do 40 and 42. An attacker who sees one URL can walk the whole table by adding and subtracting one. If your authorization is weak anywhere, sequential IDs hand out a map of everything to try.
The German-tank problem. In WWII the Allies estimated German tank production from the serial numbers on captured tanks - sequential numbers leak totals. Same math, your business: a competitor signs up, notes their user_id is 50100, waits a week, signs up again as 51200, and now knows you added ~1,100 users that week. Your growth rate, order volume, invoice count - all readable from the increment. That's business intelligence you're printing on every URL.

Snowflake helps because its IDs are not neatly sequential - the low bits move, the timestamp is in milliseconds off a custom epoch, so you can't add one to get the next valid id and you can't subtract two to get a count. Casual enumeration and count-leaking get much, much harder.

But - and I want to be blunt about this - an ID is NEVER a secret, and it is NEVER an authorization check. "Hard to guess" is not "safe." The real control is an ownership/authz check on every single request: does this authenticated caller have the right to touch this object? - enforced server-side, every time, no exceptions. The unguessable-ish id is defense in depth layered on top of that check, not a replacement for it. Anyone who treats a hard-to-guess id as the gate has built an IDOR with extra steps. The Snowflake shape buys you a second wall; it does not excuse a missing first one. (There's a lot more to say on the security side - a later piece can pivot fully to it.)

Next: getting the id out of the building

That's the primary key settled: 64-bit Snowflake, native BIGINT, generated at the edge by a library you didn't write. Inside the trust boundary, that raw int64 is exactly what every service should speak.

The moment it has to leave - into a public URL, a third-party API, a browser - the rules change completely. Raw ints don't go out the door, browsers can't even count that high without corrupting them, and a leaked link needs to be revocable. That's Part 2: hashids at the edge, composite tokens, self-serve salt rotation with an audit tripwire, and why every int64 becomes a string before it touches a browser.

If you build serious backends - Symfony, Go, or the messy space between a monolith and the services growing out of it - follow along on github.com/brilliant-almazov. And if your primary keys are UUIDs right now: what's the index bloat costing you that you haven't measured yet? I'd genuinely like to compare notes.