DEV Community: Edgar Nahama Alochi

The API is a Promise: Designing for Systems You No Longer Control

Edgar Nahama Alochi — Wed, 30 Sep 2026 08:13:30 +0000

I remember the exact moment I realized I had lost control of my own code. It wasn’t a bug or a crash. It was a mobile developer in another time zone who had built an entire feature on top of a temporary field in a JSON response.

I wanted to rename that field to something more sensible. It would have taken seconds. But the moment that response left my server and reached a device I didn’t own, it stopped being my code. It became a promise. And in software, breaking a promise is far more expensive than refactoring a function.

The Illusion of Agility

In the early stages of a system, speed feels like the only thing that matters. You move quickly, reshape your database without hesitation, and adjust responses as if nothing depends on them. This works because nothing really does. The frontend and backend move together, often in the same repository, deployed at the same time. You can afford to be clever.

That illusion fades as soon as your system escapes your control.

A mobile app might sit on a user’s phone for months without an update. A partner might integrate your API into a dashboard you never see. At that point, your backend is no longer just code you can change freely. It becomes infrastructure that other people rely on.

This is where many experienced engineers still make a critical mistake. They treat APIs like private functions. A private function can change whenever you want. An API cannot. Its shape is no longer an implementation detail. It is a contract.

Design for the No

Good API design is not about flexibility. It is about constraint. Every piece of flexibility you expose becomes something you are responsible for supporting indefinitely.

A common example is the temptation to include a generic metadata or settings field that accepts arbitrary JSON:

type UserProfile struct {
    ID       string                 `json:"id"`
    Settings map[string]interface{} `json:"settings"`
}

This looks harmless, even convenient. But the moment it is released, someone will store complex, deeply nested data inside it. At that point, you have lost control. If you later need to restructure or optimize how that data is stored, you cannot do it cleanly. You are forced to carry that decision forward, parsing and maintaining a structure you never truly defined.

A more constrained design feels slower, but it preserves your ability to evolve:

type UserProfile struct {
    ID                string `json:"id"`
    IsNotificationsOn bool   `json:"is_notifications_on"`
    ThemePreference   string `json:"theme_preference"`
}

Here, the boundaries are explicit. You decide what is supported, and you retain the freedom to change how it is implemented internally. Constraint is not a limitation. It is what protects your system from accidental commitments.

Versioning is a Strategy

Versioning is often treated as a technical detail, something you solve with a path or a header. In reality, it is a long term commitment.

Every version you release becomes something you may need to support far longer than expected. As long as even one client depends on it, it cannot simply disappear. That means every additional version adds weight to your system and slows down your ability to move.

The alternative is not to avoid change, but to approach it differently.

Instead of replacing fields, add new ones. Instead of silently altering behavior, make transitions visible. Instead of exposing everything, return only what is necessary. These decisions reduce the need for hard version boundaries and allow your API to evolve without breaking existing clients.

Deprecation should also be gradual and observable. Logs, warnings, and clear communication give consumers time to adapt. Turning things off without a transition is rarely a technical failure. It is a failure of design.

The Reality of Ownership

Over time, you learn that clean code is an internal concern, but stable interfaces are external. Users do not care how your system is structured. They care that it behaves the same way today as it did yesterday.

Designing an API means accepting that you no longer control how it is used. Someone will depend on it in ways you did not expect, on systems you cannot see, and they may not update their code for a long time.

If your design can survive that reality, then you are not just writing code. You are building something that can endure. You are creating systems that keep their promises.

What Experience Teaches Engineers to Optimize

Edgar Nahama Alochi — Mon, 28 Sep 2026 07:03:09 +0000

When you are early in your career, engineering can look like a very straightforward game.

You write code.
It works.
You feel powerful.

And honestly, that phase is fun.

You learn fast, ship fast, and there is something deeply satisfying about making a machine do what you told it to do. A lot of junior engineers are focused on exactly what you would expect: learning syntax, understanding frameworks, fixing bugs, shipping features, and proving they can build things.

That makes sense. Those are the visible parts of the job.

What is less visible is how your priorities change over time.

Because the longer you stay in engineering, the more you realize the job is not just about making things work. Plenty of people can make things work. The interesting part is making them work without creating fresh chaos every time you touch them.

That is usually where senior engineers start to look strange.

A junior engineer might look at a decision and think, why are they doing it that way? That seems slower. That seems cautious. That seems a bit boring.

Meanwhile the senior engineer is quietly trying to avoid a future disaster nobody else can see yet.

That gap is one of the biggest differences between experience and enthusiasm.

It is not that juniors do not care. They do. It is just that many of the things senior engineers optimize for only become obvious after you have lived through enough painful incidents, failed rewrites, bad handoffs, confusing systems, and “quick fixes” that somehow stayed in production for three years.

You start to see the hidden costs.

And once you see them, you cannot unsee them.

Juniors often optimize for success

Senior engineers often optimize for survival.

That sounds dramatic, but it is true.

When you are newer, it is natural to focus on the immediate win. Can I build this feature? Can I fix this bug? Can I make this faster? Can I make this elegant? Can I impress the team a little without making it too obvious?

Those are perfectly normal instincts.

But senior engineers have usually learned that the first version of success is not the whole story.

A feature is not truly successful just because it shipped. It also has to be maintainable. It has to be understandable. It has to behave well in production. It has to leave enough room for future change. It has to avoid turning some future teammate into a part-time archaeologist.

That is why more experienced engineers sometimes make decisions that feel less exciting from the outside.

They are not only thinking about the code running today. They are thinking about what happens when it breaks, scales, changes hands, gets rushed, gets copied, or gets stretched far beyond its original design.

In other words, they are thinking about the life of the system, not just the launch of it.

They optimize for blast radius

This is one of the biggest mindset shifts.

Junior engineers often focus on whether a change works.

Senior engineers also think about what happens if it fails.

How much of the system can this break?
How reversible is the change?
Can we roll it back cleanly?
Will this failure be obvious or confusing?
Does it fail loudly, or does it quietly corrupt data and ruin someone’s week?

That kind of thinking can look overly cautious until you have been around long enough to see a tiny innocent change knock over half a service stack like a toddler pulling a tablecloth.

Senior engineers get twitchy about blast radius because they have seen how quickly small mistakes become expensive.

So they reach for feature flags, staged rollouts, guardrails, validation, rate limits, isolation boundaries, and boring fallback paths. Not because they love process. Mostly because they enjoy sleeping.

A lot of engineering maturity is just developing a healthy respect for how much damage “should be fine” can do.

They optimize for change, not perfection

A lot of junior engineers want to get it right.

Senior engineers want to make it easy to change later.

That difference sounds subtle, but it changes everything.

When you are newer, you can fall in love with the idea of the “correct” design. The cleanest architecture. The most complete model. The solution that feels polished and final.

Experienced engineers are usually more suspicious of anything that feels final.

They know requirements move. Teams change. Products drift. Businesses discover new priorities at exactly the moment you thought the thing was settled. The system you are building today will almost certainly be asked to do something annoying tomorrow.

So instead of aiming for perfection, senior engineers often aim for adaptability.

They want code that can be revised without causing emotional damage.
They want boundaries that make change cheaper.
They want systems that bend before they break.

Sometimes this looks less impressive in the moment. It can feel less “designed.” But over time, it is almost always the better bet.

Perfect systems are rare. Systems that need to change are guaranteed.

They optimize for clarity under pressure

A design that feels elegant during a calm architecture discussion can become completely useless during an incident.

This is another thing juniors do not always see at first: software is judged differently when people are stressed.

A senior engineer will often choose the option that is easier to trace, easier to explain, and easier to debug even if it is slightly less clever.

That choice can look conservative until you are on call, the alerts are going off, the logs are weird, and half the team is trying to understand what the system is doing before a customer notices.

That is not the time to discover that your beautifully abstracted flow requires a map, a prayer, and one specific person who is currently on leave.

Readable systems hold up better under pressure.

Predictable systems hold up better under pressure.

Systems that leave evidence behind hold up better under pressure.

At some point, senior engineers stop being impressed by code that needs a guided tour.

They start favoring code that explains itself fast enough to be useful on a bad day.

They optimize for maintenance, not applause

This one hurts a little because every engineer likes writing something clever once in a while.

But senior engineers have usually learned that the code which gets admiration in a pull request is not always the code that earns gratitude six months later.

Maintenance changes your taste.

You start preferring code that a teammate can pick up quickly.

You start valuing obviousness.

You start noticing how expensive internal cleverness becomes when it spreads through a codebase.

You stop asking whether something is “cool” and start asking whether it will become annoying.

That is a far less glamorous question, but honestly, it saves a lot more projects.

There is a quiet kind of craftsmanship in leaving behind code that nobody needs you to explain. It may not look brilliant. It may not win any architecture awards. But it lets the team move, and that counts for a lot.

Some of the best engineering decisions I have seen were almost invisible. They made future work easier without demanding attention.

That kind of maturity does not always look exciting. It looks calm.

They optimize for team speed, not individual heroics

Junior engineers often get rewarded for solving hard problems themselves.

Senior engineers eventually realize that a system which depends on individual brilliance is usually a fragile system.

If only one person can understand a service, fix a deployment, trace a workflow, or safely change a core module, the team does not have velocity. It has a dependency.

Senior engineers tend to optimize for shared understanding.

They care about naming. Documentation. Boundaries. Simple flows. Repeatable patterns. Tooling that reduces guesswork. Decisions that make it easier for other people to contribute safely.

Sometimes that means not choosing the most advanced solution.

Sometimes it means repeating a pattern instead of introducing a more abstract one.

Sometimes it means writing the extra comment, adding the extra check, or leaving a thing slightly less “smart” so it can be more widely understood.

This is the sort of work that can feel invisible to less experienced engineers because it does not always show up as technical brilliance.

What it shows up as is momentum.

The team moves faster because fewer things are mysterious.

And that is one of the most underrated optimization goals in engineering.

They optimize for tradeoffs, not ideals

This may be the biggest one.

Junior engineers are often still learning rules.

Senior engineers are mostly learning tradeoffs.

Should this be fast, or simple?
Flexible, or easy to reason about?
Shared, or isolated?
Convenient now, or cheaper later?
General, or specific?

There is rarely a perfect answer. Most engineering decisions involve choosing which pain you would rather have.

That is why senior engineers can sound annoyingly unsatisfying sometimes. They say things like “it depends,” not because they are dodging the question, but because they know the real work is in understanding which constraint matters most here.

Experience teaches you that every strong choice creates a weakness somewhere else.

So senior engineers spend less time searching for ideal patterns and more time asking which compromise the system can afford.

That mindset is easy to miss when you are early in your career because tradeoffs are hard to appreciate until you have been punished by them a few times.

Nothing sharpens engineering judgment like getting confidently wrong in production.

They optimize for boring outcomes

This might be my favorite one because it sounds so unromantic.

Senior engineers love boring outcomes.

Deployments that quietly succeed.
Incidents that stay small.
Code that behaves as expected.
Services that are easy to reason about.
Migrations that do not become company folklore.

That kind of boring is incredibly valuable.

Juniors sometimes chase interesting technical work because that is where growth lives, and they are not wrong. But seniors know the business usually does not want “interesting.” It wants stable. Predictable. Recoverable. Scalable enough. Safe to operate.

A lot of senior engineering is really the art of removing unnecessary drama from systems.

Not all drama, of course. Software will always find new and creative ways to embarrass people.

But the avoidable kind? That is worth fighting.

What changes as you grow

The funny thing is that juniors and seniors are often looking at the same code and asking very different questions.

A junior might ask:
“Does this solve the problem?”

A senior might ask:
“What problem does this create next?”

A junior might ask:
“Can we make this cleaner?”

A senior might ask:
“Can the team still change this safely in six months?”

A junior might ask:
“Is this elegant?”

A senior might ask:
“Will this wake someone up at 2 AM?”

Both perspectives matter. You need people who can build. You need people who still have ambition and curiosity and energy. But engineering maturity adds another layer. You start seeing software as something that has to live in the world, not just pass a review.

That changes what you optimize for.

You become less enchanted by technical cleverness for its own sake.

You become more interested in resilience, legibility, reversibility, and the quiet efficiency of systems that do not fight their operators.

You realize that code is only part of the work. The rest is designing for humans, uncertainty, and future change.

That is the part juniors rarely see at first.

Not because they cannot.

Mostly because nobody sees it clearly until they have paid for ignoring it.

Final thought

A lot of people think senior engineers are just faster coders with better instincts.

Sometimes that is true.

But a lot of the difference comes from what they are paying attention to.

They are scanning for risk.
They are managing complexity before it spreads.
They are protecting team speed.
They are choosing maintenance over magic.
They are trying to keep the future affordable.

That work is easy to miss because when it is done well, very little explodes.

And in engineering, that usually means somebody knew exactly what they were optimizing for.

The Cost of Cleverness: A Backend Engineer’s Guide to Strategic Simplicity

Edgar Nahama Alochi — Thu, 24 Sep 2026 04:58:09 +0000

There is a phase many backend engineers go through where making code shorter, smarter, and more abstract feels like progress.

You discover a new pattern, shave 200 lines down to 15, add a generic layer that can handle six future use cases nobody has asked for, and sit back like you have just advanced the field of computer science.

For a few minutes, it feels amazing.

Then one day production breaks, the logs are useless, the issue is hiding behind three layers of indirection, and suddenly your beautiful design starts to feel like an elaborate prank.

I’ve been on both sides of this. I’ve written code that made me feel very clever. I’ve also had to debug clever code while tired, annoyed, and increasingly convinced the original author had enemies.

That is usually when the romance ends.

Because in backend engineering, cleverness has a way of aging badly. It looks impressive when everything is calm. Under pressure, though, you start to care less about elegance and more about whether a normal human being can understand what is going on before the business catches fire.

And that, more than anything, has changed how I think about software.

Cleverness always sends an invoice

I do not think cleverness is inherently bad. Some of it is necessary. Some of it is brilliant. Some of it is the reason a system survives real scale.

But none of it is free.

Every clever decision comes with a bill attached. Sometimes you pay it immediately in added complexity. Sometimes you pay months later when a new engineer joins the team, opens the codebase, and looks like they have accidentally walked into the middle of season four of a show they have never watched.

That is the part people forget.

Clever code usually solves one problem by quietly introducing three more. You gain flexibility, speed, elegance, or abstraction. In return, you give up clarity, ease of debugging, and sometimes your weekend.

There are cases where that trade makes perfect sense.

If you are working on something close to the metal, dealing with huge throughput, brutal latency requirements, or systems where ordinary abstractions start sweating, then yes, you may need more advanced techniques. Custom memory handling, lock-free structures, tight optimizations, all of that can be justified when the problem is real and the constraints are merciless.

In those situations, cleverness is not decoration. It is survival.

But most teams are not building a database engine in a cave.

Most teams are building APIs, internal services, payment flows, dashboards, reporting jobs, queues, and all the other software that keeps companies moving. In those systems, the most valuable quality is often not brilliance. It is clarity.

You want code that can be read, changed, debugged, and trusted without requiring a spiritual guide.

How teams quietly drift into trouble

The trouble usually starts with good intentions.

Someone wants the system to be flexible. Someone else wants it to be reusable. Another person wants to make sure it can scale later. Before long, a straightforward piece of business logic has turned into a generic framework with adapters, handlers, strategies, events, and enough abstraction to power a small government.

Meanwhile the product just needs to create an order, charge a card, and send an email.

This is how you end up with architecture that sounds more ambitious than the business itself.

A company selling shoes somehow ends up with a platform designed to support every conceivable product category, every possible fulfillment flow, and a future multi-tenant expansion into industries that do not exist yet. You look at the code and think, this system is prepared for everything except the actual thing it does every day.

I have seen simple workflows turned into event chains so elaborate that tracing one request feels like following family drama across five seasons. Something as innocent as “user updates profile” becomes a journey through producers, consumers, retries, side effects, notifications, projections, and eventually a teammate whispering, “I think that service handles it, but I’m not completely sure.”

At that point, the code is no longer helping the team. The team is helping the code.

The hidden cost is almost always human

A lot of technical discussions focus on machine costs. CPU. Memory. Latency. Throughput.

Those matter, obviously.

But in everyday backend systems, the real pain usually shows up somewhere else. It shows up in the human cost.

How hard is this thing to debug?

How long does it take a new engineer to make a safe change?

Can someone follow the flow without opening twelve files and questioning their career choices?

Can the on-call engineer understand enough of the system at 3 AM to stop the bleeding?

Those questions do not sound glamorous, but they have a lot more to do with the long-term health of a backend system than whether the code looks clever in a review.

A machine will run unreadable code just fine. It has no pride. No confusion. No need for sleep. Humans are much less forgiving.

That is why I have become suspicious of code that feels too smart too early. Not because smart people wrote it, but because complex systems tend to demand complex maintenance.

And maintenance is where the real game is.

Debugging is where cleverness loses its shine

A calm code review is one thing. Production pressure is another.

There is a huge difference between reading a fancy abstraction over coffee and trying to understand it while dashboards are glowing red and someone is asking for updates every seven minutes.

That is when the gap appears.

The engineer who wrote the clever code understood every shortcut, hidden assumption, and elegant little trick at the time. Everyone else now gets the joy of reverse-engineering that thought process under stress.

This is why some systems quietly develop heroes.

There is one person who understands how the whole thing works. Everyone depends on them. People tag them in incident channels with increasing urgency. Their PTO becomes a source of organizational anxiety.

That is not a sign of architectural excellence. That is just a single point of failure wearing glasses.

When a system can only be safely changed by the person who invented its internal mythology, the problem is not staffing. The problem is design.

New engineers can feel the cleverness immediately

You do not need an audit to know whether a system carries too much cleverness. Just watch a new engineer try to work in it.

In a healthy codebase, they can follow the main paths without too much ceremony. They may not understand everything on day one, but they can answer basic questions fairly quickly.

Where does this request go?
Where is the database write?
What triggers this side effect?
What happens when this fails?

In a very clever system, those questions become archaeology.

You start at a controller, end up in a dispatcher, pass through a generic pipeline, land in a dynamically resolved strategy, then find out the actual work happens in a subscriber registered somewhere in a configuration format nobody has opened since the previous re-org.

By then, nobody is learning the business. They are just learning the maze.

And that maze has a cost.

A clear system lets a new hire contribute in weeks. A deeply clever one can make even strong engineers hesitant for months because every change feels like it might awaken something ancient.

Simplicity takes more discipline than people admit

Simple code gets unfairly judged sometimes.

People talk about it as if it is what you write when you do not know enough. In practice, I have found the opposite to be true. Simplicity often comes from experience. You have seen enough over-engineered systems, enough unnecessary abstractions, enough “future-proofing” experiments gone wrong, that you stop reaching for complexity unless reality leaves you no choice.

It is actually very easy to make a system more complicated. Give engineers a free afternoon and a little ambition and they will produce a framework.

What takes restraint is keeping things obvious.

What takes maturity is solving the problem you have instead of the conference talk you might one day give about it.

What takes confidence is writing code that does not show off.

That kind of simplicity can look almost boring from the outside. Internally, though, it is doing something quite sophisticated. It is respecting the time, attention, and sanity of the people who will come after you.

I have started to think of that as a kind of engineering kindness.

Not exciting. Not flashy. Very underrated.

A few situations where cleverness usually sneaks in

There are a few repeat offenders.

One is microservice overkill. Teams split things too early, then spend the next year paying for that decision with network complexity, deployment overhead, distributed tracing, cross-service debugging, and regular ceremonies to discuss why nothing is easy anymore. You wanted clean boundaries. You got a full-time observability hobby.

Another is deep abstraction. The code becomes so DRY and generalized that the obvious path disappears. Now every action goes through a set of reusable layers that technically make sense but somehow make simple tasks feel ceremonial. Searching the codebase for where something actually happens becomes less “grep” and more “my journey.”

Caching is another classic trap. Used well, it saves a system. Used aggressively and carelessly, it creates the kind of bug that makes you distrust reality. The system is fast, the dashboards look good, and for two terrifying seconds one user can see another user’s data. Suddenly everyone remembers that cache invalidation jokes were not really jokes.

Each of these choices can be valid. The danger is not in using them. The danger is in adopting them before the problem is large enough to deserve them.

That is how complexity enters quietly. It arrives wearing the clothes of best practice.

So when is it worth being clever?

Usually later than you think.

I like to wait until the system earns the complexity.

If a bottleneck is measurable, if the pain is recurring, if the limits are real and visible, then sure, do the hard thing. Optimize. Specialize. Build the more advanced solution. At that point you are responding to evidence, not imagination.

I also think any clever code should come with an explanation of why it exists.

Not a comment explaining the syntax. The syntax is rarely the real issue.

The useful comment explains the pressure that forced this choice. What constraint made the simpler option fail? What pain is being avoided? Why is this complexity worth carrying?

That kind of context helps future engineers decide whether the code should be preserved, improved, or deleted with enthusiasm.

And that last point matters too: if you are going to build something complex, keep it easy to remove.

Complexity becomes much more dangerous when it spreads across every layer of the system. If a highly optimized or heavily abstracted component can be isolated, replaced, or rolled back, then the risk stays manageable. If it becomes the foundation for everything else, you are now living inside the decision.

Some engineering choices should be easy to revisit. Cleverness is one of them.

What I have come to value instead

These days, I like backend systems that are easy to explain.

I like being able to trace a request without opening half the repository.

I like code that a teammate can change without needing a blessing from the original author.

I like systems that remain understandable when something goes wrong, because something always goes wrong.

That does not mean every part of a system must be primitive or painfully literal. It just means I have become much less impressed by complexity for its own sake.

A solution does not become better because it is harder to understand.

Sometimes it just becomes harder to survive.

And that, for me, is the real cost of cleverness. It rarely announces itself as disaster on day one. It shows up over time. In slower onboarding. In fragile incidents. In fearful refactors. In teams that move carefully around code nobody wants to touch. In systems that are technically impressive and operationally exhausting.

The machine, of course, does not care.

It will run loops and bitwise tricks and elegant abstractions with the same cold professionalism.

The humans are the ones who pay.

That is why I keep coming back to the same idea: code is for people first.

Not in the sentimental sense. In the practical sense.

People have to read it, trust it, debug it, extend it, and hand it to someone else someday. A backend system that ignores that reality may still work, but it will work like a difficult colleague. Brilliant, maybe. Useful, sometimes. Exhausting, always.

And honestly, I have had enough of those.

The best systems I have seen are rarely the cleverest ones in the room. They are the ones that solve real problems clearly, leave evidence behind, and do not force the next engineer to become a detective just to make one safe change.

That kind of code does not always get applause.

But it does let people sleep.

The Unboring Truth About Boring Tech: How Startups Accidentally Build Research Labs

Edgar Nahama Alochi — Mon, 14 Sep 2026 12:42:41 +0000

The Unboring Truth About Boring Tech

Or: How Startups Accidentally Build Research Labs

Last month, I found myself in a founder's kitchen. The kind of kitchen where the whiteboard was less a planning tool and more a cryptic map to a minor conspiracy, covered in enough arrows and boxes to make a cartographer weep. On the counter, a cup of coffee had clearly thrown in the towel hours ago, its contents a testament to lost battles. And the founder? He wore that particular expression – a polite, weary mask that screamed, "Sleep? What's sleep? The round closed, and so did my eyelids, apparently."

He was, of course, walking me through his architecture. And what an architecture it was! Magnificent, in the way a cathedral is magnificent: intricate, ambitious, and wildly disproportionate to the congregation it currently served. Kafka was moving data between half a dozen microservices, a GraphQL federation layer demanded its own air traffic control, and a vector database sat patiently, reserved for the AI features he was sure he'd want one day. Oh, and a Rust service, because apparently, three active users absolutely required sub-millisecond latency when updating their profile settings.

The kicker? He hadn't launched.

So, I did what any reasonable person would do: I asked what the product actually did. He described a perfectly normal B2B SaaS tool. Useful, sensible, nothing particularly exotic. The kind of thing that, at its core, was mostly a spreadsheet with permissions and a rather important "Save" button.

It was hard not to admire the sheer, glorious contrast. He had, with painstaking effort, constructed a NASA-grade launchpad for what was, at least for now, a paper airplane.

"I'm thinking ahead," he explained, a common refrain. "Don't want to get boxed in. If we take off, I need to know the architecture can handle it." It sounds responsible, doesn't it? Almost prudent. But this logic, so prevalent among founders, hides a rather nasty trade-off. The more you optimize for future scale before present demand even whispers, the more you make today expensive, slow, and surprisingly fragile.

What often masquerades as foresight is, in fact, a different kind of debt. Not the kind a bank issues, but the quiet, insidious kind you borrow from your future team, your future roadmap, your future ability to pivot with agility. And let me tell you, the interest rate on that kind of technological debt is absolutely spectacular.

This is precisely why I find myself returning, again and again, to a deeply unfashionable piece of startup wisdom:

Choose boring technology.

It's not a dismissal of ambition, nor a condemnation of novelty. It's simply an observation: most startups don't perish from a lack of technical sophistication. They run out of time, tangled in elaborate systems built for problems they haven't yet earned the right to solve.

The Quiet Charm of Boring

Let's be honest, "boring technology" rarely sparks excitement in a demo. Nobody leans in with bated breath when you declare, "We use PostgreSQL!" No investor has ever gasped in awe because your stack includes plain HTML and a smattering of JavaScript. But boring, my friends, possesses some truly wonderful properties.

Boring technology behaves predictably. It's been used, abused, fixed, and stress-tested by countless teams over the years. Its surprises are public knowledge, its quirks well-documented. When something inevitably goes sideways at 3 a.m., you're far more likely to unearth a dusty forum thread from a decade ago with a genuine solution than a GitHub issue sporting two emoji reactions and a deafening silence.

Boring is also remarkably kind to your hiring process. You get to recruit good engineers, not mythical specialists who somehow boast seven years of experience in a framework invented during the last World Cup. A new developer can join, survey the landscape, and become productive without first needing to decipher your personal theory of software architecture.

And perhaps most crucially, boring systems liberate mental energy. They free your team to focus on the one thing that truly matters: crafting a product so compelling that people will happily open their wallets for it.

PostgreSQL? Boring. A monolith? Boring. Go? Boring. Server-rendered pages with a touch of JavaScript? Utterly, gloriously boring. And that, my friends, is precisely why they continue to be the quiet backbone of so many thriving businesses.

The Hidden Cost of the Shiny New Thing

The shiny new technology itself is rarely the villain. The real problem is the hidden invoice that inevitably arrives later. A trendy stack subtly shrinks your hiring pool. It stretches out onboarding times. It limits your tooling options. It increases the cognitive load on every engineer, demanding they hold an entire universe of complexity in their heads before making even the simplest change. And once enough complexity accumulates, the system develops a personality. Small product requests transform into delicate negotiations with an ancient, moody deity.

At this point, velocity doesn't just slow down; it slams into a brick wall.

One of the more reliable early warning signs, by the way, is when your tools have better branding than your actual company. If your database boasts a cooler logo than your startup, consider it a subtle hint that events may already be unfolding, perhaps not in your favor.

Why We Fall for the Trap

Because it feels smart. That, my friends, is the trickiest part of all. Complex architecture offers the intoxicating emotional satisfaction of seriousness. It feels like you're meticulously preparing for monumental success. It feels like you're building something profoundly important. There's a comforting gravitas to diagrams overflowing with arrows; they whisper of inevitability, of boundless scale, of millions of users arriving any minute now to thank you for that message queue.

Meanwhile, the plain, sensible solution can feel embarrassingly small. A monolith might seem temporary, even when it's precisely the right fit. A simple relational database can feel unsophisticated, even when it's more than capable. Founders are particularly susceptible to this illusion because startups are inherently chaotic, and complexity offers a seductive illusion of control.

But a startup isn't a monument; it's an experiment under relentless time pressure. The stack that offers you the best chance of surviving long enough to learn is almost always the one with the fewest moving parts, the broadest hiring market, and the least amount of architectural poetry.

When to Get Fancy (and When Not To)

Of course, there are always exceptions. Sometimes, a problem genuinely demands an unusual tool. If you're orchestrating real-time global collaboration at a massive scale, or venturing into truly exotic territory, then the normal rules begin to bend. Sometimes, your team possesses deep, specialized expertise in a technology that would appear risky to outsiders but is second nature to them. And sometimes, success has already arrived, your boring system is groaning under the weight of real demand, and replacing a part of it becomes a practical necessity rather than a mere personality choice.

These are legitimate scenarios. What tends to be far less compelling is the startup with twelve users and a meticulously detailed plan for handling a billion. Or when a technical decision is subtly influenced by how impressive it will sound in a fundraising deck. Investors, in my experience, are far more captivated by the part where the business actually works.

"Vector" is a nice word. "Profit," however, has a much longer and more satisfying shelf life.

A Simple Litmus Test

Whenever a new technology begins to look utterly irresistible, I like to run it through a few simple questions:

Is this solving a problem we have now, or a delightful fantasy we've penciled in for three years down the road?
If we commit to this, can we quickly find several strong engineers to work on it without turning recruitment into an epic scavenger hunt?
And if, by some chance, we're wrong, will backing out feel merely annoying, or utterly catastrophic?

These questions aren't designed to stifle innovation. They simply filter out the kind of innovation that primarily exists to make smart people feel smart.

Build for the Stage You're In

In the early days, your goal isn't to impress the internet with your architectural prowess. Your goal is to survive long enough to discover if anyone genuinely cares about what you're building. This usually means that speed, clarity, and forgiveness are far more valuable than elegance. You need tools that allow you to make rapid changes, recover gracefully from mistakes, hire without drama, and ship before your runway becomes a historical footnote.

The funny thing is, boring technology often scales far beyond what founders initially expect. Plenty of successful companies operate for years on stacks that their earlier selves would have deemed far too plain. They only earn the right to complicated solutions once the simpler ones are genuinely straining under the weight of real demand.

And that, my friends, is a truly lovely problem to have. It means customers showed up first.

A perfect architecture with no users, however, is a much harder thing to celebrate. At some point, it ceases to be a startup and transforms into a very expensive hobby.

So yes, embrace the boring.

Ship your product. Learn what truly matters. Survive long enough for the real problems to emerge. And then, much later, once you're successful and perhaps just a touch insufferable, you can always rewrite everything in a language nobody has heard of yet. It'll be your well-earned reward.

The Founder’s Trap: Shipping Fast Without Borrowing Against Your Future

Edgar Nahama Alochi — Sun, 06 Sep 2026 21:18:14 +0000

When you are building something from scratch, speed feels noble.

It feels disciplined. Necessary. Mature, even.

You tell yourself you are being practical. The customer does not care if the code is beautiful. The market is moving. Cash is finite. Momentum matters. So you make the trade that almost every founder makes at some point: ship now, clean up later.

I understand that instinct very well because I have lived inside it.

As a founder, you are not operating in the comfort of theory. You are making decisions with incomplete information, limited time, and a product that still needs to prove it deserves to exist. In that stage, a lot of engineering advice sounds suspiciously like it was written by people who have never had to get a real product out before the window closes.

So yes, you move fast.

You hardcode things that feel temporary. You defer cleanup. You choose the version that works over the version that would make your future self proud. You call it pragmatism, which it often is.

The trouble is that pragmatism has a habit of overstaying.

And that is the trap.

Because some shortcuts buy you speed. Others quietly sell off your future ability to move.

It took me time to really understand that distinction.

Founding teaches you that speed has layers

Before I started building products as a founder, speed felt simple. Ship the feature. Get the customer. Keep going.

Later, I learned that there are at least two kinds of speed.

The first kind gets you to launch.

The second kind lets you keep moving after the launch.

The first kind is exciting. It is visible. It gives you demos, momentum, first users, first revenue, first proof that you are not completely hallucinating the opportunity.

The second kind is quieter. It shows up months later when the product has more customers, more complexity, and more reasons to break. It is the speed of a system that can still change safely. A team that can still ship without fear. An architecture that has not turned every roadmap discussion into a negotiation with old shortcuts.

That second kind of speed matters more than most founders realize at the beginning.

Not because launch speed is unimportant. It is. But because a lot of early decisions are effectively loans against future product velocity. Some are cheap. Some come with absurd interest.

I have learned to care a lot about the difference.

Tinker made that lesson very real for me

A lot of my thinking about this became sharper through building Tinker.

On my site, I describe the work I do as building systems that work well, scale reliably, and last. I also say, pretty plainly, that I prefer simple, well-designed systems over clever ones. (edgar.co.ke) That sounds neat and composed on a website. In real life, those principles are usually learned while the system is trying to embarrass you.

With Tinker Payments, the public story is clear enough: it is built as a unified payment infrastructure layer that helps merchants keep their existing payment providers while improving routing, reconciliation, revenue visibility, and payment stability. The product talks directly about hard operational realities: failed transactions, multiple providers with no unified control, manual reconciliation, operational risk during expansion, and the need for failover, routing, and finance-ready visibility. (Tinker Payments)

That kind of product does not come from a world where software gets to be casual.

Payments are rude in a very educational way. They force honesty. They are full of edge cases, provider inconsistencies, operational risk, money movement, reconciliation headaches, and all the little realities that punish vague engineering. If a content site is messy, people get mildly annoyed. If a payments system is messy, the consequences become much more memorable.

That is one of the fastest ways to learn that not all technical debt behaves the same.

Some debt sits quietly in a corner.

Some debt inserts itself into every future release.

The founder’s trap is not mess. It is sticky mess.

I think founders sometimes get bad advice here from both sides.

One side says, “Move fast and break things,” which is exciting until the thing you break becomes your main business.

The other side says, “Design it properly from the beginning,” which sounds responsible but can drift into building a cathedral for customers who have not even arrived yet.

Neither extreme is very helpful.

Early-stage products are allowed to be imperfect. In fact, they usually have to be. You do not need premium architecture for a problem that has not earned it yet. You do not need six layers of abstraction to prove a customer pain point. You do not need to act like a Fortune 500 platform on day one just because you have seen enough conference talks to know the vocabulary.

But you also cannot treat every shortcut as harmless.

What matters is whether the mess stays local.

That is the phrase I keep coming back to: local mess.

If a decision creates a bit of ugliness in a low-risk part of the system, I can live with that. Maybe an internal tool is rough. Maybe a report is manual. Maybe some workflow is embarrassingly human behind the scenes. Fine. Startups do not die because an internal admin page has poor taste.

The dangerous stuff is the sticky mess.

The kind that lands in your core data model. Your money flows. Your permissions. Your deployment path. Your integration boundaries. The places where every future product decision has to pass through.

That debt does not stay local.

It spreads.

And when it spreads, it stops being a shortcut and starts becoming culture.

You learn very quickly where “later” likes to hide

One of the funniest lies in software is “we’ll clean it up later.”

Not because nobody means it. People usually do mean it. The problem is that “later” is a magical place where teams imagine they will have more time, more certainty, more energy, and fewer urgent feature requests than they currently do.

This place does not exist.

Later is usually just now, but with more customers and worse consequences.

I have seen this happen enough times that I no longer hear “temporary” the way I used to. Temporary code has an incredible survival instinct. It clings to relevance. It learns the product. It gains dependencies. Before long, a rushed workaround is sitting in the middle of a critical flow like it pays rent.

And then your roadmap starts reacting to old decisions.

A simple change takes longer because an early assumption is now everywhere.

An integration becomes painful because the original model was too narrow.

A release feels risky because operational control was never built in properly.

Finance needs clean reporting, and everyone suddenly discovers that “we’ll sort that out later” has become a monthly ritual involving spreadsheets, detective work, and unusually long sighs.

You do not feel technical debt all at once. You feel it as drag.

That is what makes it dangerous. It rarely arrives like a dramatic collapse. It arrives like friction in everything.

Building in payments sharpens your sense of where to be strict

One thing I appreciate about building in this space is that it punishes hand-wavy thinking.

Tinker’s public product language talks about routing, failover controls, revenue visibility, a unified ledger view, reconciliation, and governance controls. (Tinker Payments) Those are not decorative features. They are responses to the kinds of operational problems that appear when real businesses are moving money through multiple providers and need control without replacing their entire stack. (Tinker Payments)

And that is exactly where founders need judgment.

Because when you are building something like that, the temptation is strong to keep saying yes to the fastest route. But some parts of the system do not forgive casual decisions.

Anything close to the movement of money deserves respect early.

Anything that affects reconciliation deserves respect early.

Anything that determines system behavior under provider failure deserves respect early.

Anything that will be used to explain reality back to finance, operations, or customers deserves respect early.

You can be scrappy in a lot of areas. You cannot be vague in the parts of the product that define truth.

That lesson reaches beyond payments, by the way. Every company has some equivalent of this. Some layer where the business becomes real. That layer deserves more care than the rest, even in the early days.

Founders do not need less speed. They need better spending

This is the part I feel most strongly about now.

I do not think founders need to be told to slow down. Usually they need help spending speed more wisely.

Because speed is not free. It is budgeted.

Every rushed decision spends some of it now and may borrow some from later.

The real question is not whether to take shortcuts. You probably will. You probably should, sometimes.

The better question is: where can we afford to be messy without making the future expensive?

That is a very different conversation.

It moves the discussion away from vague arguments about craftsmanship and into something much more useful: risk placement.

If this shortcut fails, where will the pain land?

Will it land in an internal tool nobody depends on heavily? Fine.

Will it land in the company’s core workflow, where every new feature has to pass through it? Different story.

Will it create a small cleanup project later? Acceptable.

Will it quietly tax every release, every estimate, every onboarding experience, and every incident? That is not a shortcut. That is a subscription.

That is the kind of thing technical leadership is supposed to help with.

Not to be the department of “no.” Not to turn startup life into an architectural prayer circle. But to help founders distinguish between debt that buys speed and debt that steals it.

The human side of this is easy to miss

There is also a more personal side to all this that people do not always talk about.

Bad debt does not only hurt systems. It wears down teams.

You can feel it when engineers start sounding cautious in the wrong way. Not thoughtful. Guarded.

You can feel it when estimates become padded because nobody trusts how deep a “small change” might go.

You can feel it when product conversations get slower because everyone knows the system has hidden moods.

You can feel it when the business starts asking for momentum and the team, quietly and correctly, starts asking for oxygen.

That is one reason I care so much about clarity now.

Not because clarity is aesthetically pleasing, though it is.

Because clear systems are kinder to the people building them.

They lower the emotional tax of change.

They make growth feel less like carrying furniture up a staircase designed by an enemy.

And when you are building for years, not weeks, that matters a lot.

Success changes the meaning of early decisions

One of the strange things about startup success is that it makes your old shortcuts more consequential.

When nobody is using the product, a rough edge is just a rough edge.

When the product starts working, every old compromise gets promoted.

The “good enough for now” data structure suddenly supports important reporting.

The rough operational process suddenly matters to multiple teams.

The workaround that got you past one provider issue now shapes how people think about the whole system.

That is why eventual success can make early technical choices feel heavier, not lighter.

And it is also why I think founders should talk more openly about this stuff. Not in a dramatic “we suffered for our architecture” way. More in an honest way. Building companies means making tradeoffs under pressure. Some of those tradeoffs are smart. Some are survivable. Some are educational in the expensive sense.

The goal is not to pretend you can avoid all of them.

The goal is to get better at choosing which ones deserve to follow you into success.

What I believe now

I still believe in moving fast.

I just no longer confuse movement with velocity.

I have become much more interested in systems that stay clear under pressure, products that can evolve without heroic effort, and technical choices that leave room for growth instead of charging rent on it.

That is part of why my writing and work keep circling the same themes: clarity, durability, systems that last. (edgar.co.ke) Those ideas did not come from abstract admiration for neat architecture. They came from building in environments where complexity becomes real very quickly, and where the cost of bad decisions is measured not only in code, but in operational strain, business risk, and team energy.

Founders will always need speed.

The real challenge is keeping that speed from turning against you.

Because the trap is not shipping fast.

The trap is shipping in a way that makes future speed harder to afford.

And once you have felt that trade in a real system, you start treating simplicity with a lot more respect.

Routing in Go Part 3: The last upgrade

Edgar Nahama Alochi — Sat, 22 Aug 2026 20:35:24 +0000

Part 3: The last upgrade

Pagination, update endpoint, request scoped logging, and lightweight OpenAPI

By now we have a small Go API that is not embarrassing.

We have routes, a service layer, middleware, timeouts, and tests. That is already better than most code that ships.

For the last part, we are going to add the stuff that turns “cute demo” into “this could actually run”:

Pagination for GET /links
PUT /links/{id} to update the note
Structured enough logging so you can trace a request without reading tea leaves
A small OpenAPI spec so other people do not have to guess your API

Still simple. Still standard library.

Step 1: Add pagination to the store and service

We will do offset pagination because it is easy to understand. Cursor pagination is better at scale, but you can add it later when you actually have scale. Most people add it early as a personality trait.

Update `internal/links/store.go`

Replace the Store interface and add a paginated list method. Also update the memory store.

package links

import (
    "sort"
    "sync"
    "time"
)

type Store interface {
    Create(amount int, currency, note string) PayLink
    Get(id int) (PayLink, bool)
    UpdateNote(id int, note string) (PayLink, bool)
    List(offset, limit int) []PayLink
    Count() int
}

type MemoryStore struct {
    mu    sync.RWMutex
    next  int
    links map[int]PayLink
}

func NewMemoryStore() *MemoryStore {
    return &MemoryStore{
        next:  1,
        links: make(map[int]PayLink),
    }
}

func (s *MemoryStore) Create(amount int, currency, note string) PayLink {
    s.mu.Lock()
    defer s.mu.Unlock()

    l := PayLink{
        ID:        s.next,
        Amount:    amount,
        Currency:  currency,
        Note:      note,
        CreatedAt: time.Now().UTC(),
    }
    s.links[l.ID] = l
    s.next++
    return l
}

func (s *MemoryStore) Get(id int) (PayLink, bool) {
    s.mu.RLock()
    defer s.mu.RUnlock()

    l, ok := s.links[id]
    return l, ok
}

func (s *MemoryStore) UpdateNote(id int, note string) (PayLink, bool) {
    s.mu.Lock()
    defer s.mu.Unlock()

    l, ok := s.links[id]
    if !ok {
        return PayLink{}, false
    }
    l.Note = note
    s.links[id] = l
    return l, true
}

func (s *MemoryStore) Count() int {
    s.mu.RLock()
    defer s.mu.RUnlock()
    return len(s.links)
}

func (s *MemoryStore) List(offset, limit int) []PayLink {
    s.mu.RLock()
    defer s.mu.RUnlock()

    if offset < 0 {
        offset = 0
    }
    if limit <= 0 {
        limit = 20
    }
    if limit > 100 {
        limit = 100
    }

    ids := make([]int, 0, len(s.links))
    for id := range s.links {
        ids = append(ids, id)
    }
    sort.Ints(ids)

    if offset >= len(ids) {
        return []PayLink{}
    }

    end := offset + limit
    if end > len(ids) {
        end = len(ids)
    }

    out := make([]PayLink, 0, end-offset)
    for _, id := range ids[offset:end] {
        out = append(out, s.links[id])
    }
    return out
}

Now update the service so handlers do not have to know pagination rules.

Update `internal/links/service.go`

Add these methods and errors.

package links

import (
    "context"
    "errors"
    "strings"
)

var (
    ErrInvalidAmount   = errors.New("amount must be greater than zero")
    ErrInvalidCurrency = errors.New("currency must be a 3 letter code like USD")
    ErrInvalidLimit    = errors.New("limit must be between 1 and 100")
    ErrInvalidOffset   = errors.New("offset must be 0 or greater")
    ErrNotFound        = errors.New("link not found")
)

type Service struct {
    store Store
}

func NewService(store Store) *Service {
    return &Service{store: store}
}

func (s *Service) Create(ctx context.Context, amount int, currency, note string) (PayLink, error) {
    select {
    case <-ctx.Done():
        return PayLink{}, ctx.Err()
    default:
    }

    currency = strings.ToUpper(strings.TrimSpace(currency))
    note = strings.TrimSpace(note)

    if amount <= 0 {
        return PayLink{}, ErrInvalidAmount
    }
    if len(currency) != 3 {
        return PayLink{}, ErrInvalidCurrency
    }
    return s.store.Create(amount, currency, note), nil
}

type Page struct {
    Items  []PayLink `json:"items"`
    Total  int       `json:"total"`
    Offset int       `json:"offset"`
    Limit  int       `json:"limit"`
}

func (s *Service) ListPage(ctx context.Context, offset, limit int) (Page, error) {
    select {
    case <-ctx.Done():
        return Page{}, ctx.Err()
    default:
    }

    if offset < 0 {
        return Page{}, ErrInvalidOffset
    }
    if limit <= 0 || limit > 100 {
        return Page{}, ErrInvalidLimit
    }

    return Page{
        Items:  s.store.List(offset, limit),
        Total:  s.store.Count(),
        Offset: offset,
        Limit:  limit,
    }, nil
}

func (s *Service) Get(ctx context.Context, id int) (PayLink, error) {
    select {
    case <-ctx.Done():
        return PayLink{}, ctx.Err()
    default:
    }
    l, ok := s.store.Get(id)
    if !ok {
        return PayLink{}, ErrNotFound
    }
    return l, nil
}

func (s *Service) UpdateNote(ctx context.Context, id int, note string) (PayLink, error) {
    select {
    case <-ctx.Done():
        return PayLink{}, ctx.Err()
    default:
    }

    note = strings.TrimSpace(note)
    if note == "" {
        // Keep it simple. You can allow empty later if needed.
        return PayLink{}, errors.New("note is required")
    }

    l, ok := s.store.UpdateNote(id, note)
    if !ok {
        return PayLink{}, ErrNotFound
    }
    return l, nil
}

Step 2: Add request scoped logging that actually helps

Right now we log method, path, and duration. Good start.

Let us add request ID into the logs and also return it in error responses. Because when a user reports a bug, you want them to give you one string, not a full emotional experience.

Update `internal/httpapi/helpers.go`

package httpapi

import (
    "encoding/json"
    "net/http"
)

func WriteJSON(w http.ResponseWriter, status int, v any) {
    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(status)
    _ = json.NewEncoder(w).Encode(v)
}

func WriteError(w http.ResponseWriter, status int, msg string) {
    reqID := w.Header().Get("X-Request-Id")
    if reqID == "" {
        WriteJSON(w, status, map[string]string{"error": msg})
        return
    }
    WriteJSON(w, status, map[string]string{"error": msg, "request_id": reqID})
}

Update `internal/httpapi/middleware.go`

Change the logging middleware to include request id.

func Logging(logger *log.Logger) Middleware {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            start := time.Now()
            next.ServeHTTP(w, r)

            reqID := w.Header().Get("X-Request-Id")
            if reqID == "" {
                reqID = "-"
            }

            logger.Printf("rid=%s %s %s from=%s dur=%s",
                reqID,
                r.Method,
                r.URL.Path,
                clientIP(r),
                time.Since(start).Round(time.Millisecond),
            )
        })
    }
}

Now your logs are traceable.

Step 3: Update handlers for pagination and PUT

Update `internal/httpapi/handlers.go`

Replace the collection handler and add a new update handler.

package httpapi

import (
    "context"
    "encoding/json"
    "errors"
    "net/http"
    "strconv"
    "time"

    "example.com/paylinks/internal/links"
)

type API struct {
    Links *links.Service
}

func (a *API) Routes() http.Handler {
    mux := http.NewServeMux()

    mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
        WriteJSON(w, http.StatusOK, map[string]string{"status": "ok"})
    })

    mux.HandleFunc("/links", a.linksCollection)
    mux.HandleFunc("GET /links/{id}", a.linksGet)
    mux.HandleFunc("PUT /links/{id}", a.linksUpdateNote)

    return mux
}

func (a *API) linksCollection(w http.ResponseWriter, r *http.Request) {
    ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
    defer cancel()

    switch r.Method {
    case http.MethodGet:
        offset := parseIntQuery(r, "offset", 0)
        limit := parseIntQuery(r, "limit", 20)

        page, err := a.Links.ListPage(ctx, offset, limit)
        if err != nil {
            switch {
            case errors.Is(err, links.ErrInvalidOffset), errors.Is(err, links.ErrInvalidLimit):
                WriteError(w, http.StatusBadRequest, err.Error())
            case errors.Is(err, context.DeadlineExceeded):
                WriteError(w, http.StatusRequestTimeout, "request timed out")
            default:
                WriteError(w, http.StatusInternalServerError, "server error")
            }
            return
        }

        WriteJSON(w, http.StatusOK, page)
        return

    case http.MethodPost:
        var body struct {
            Amount   int    `json:"amount"`
            Currency string `json:"currency"`
            Note     string `json:"note"`
        }
        if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
            WriteError(w, http.StatusBadRequest, "invalid JSON body")
            return
        }

        l, err := a.Links.Create(ctx, body.Amount, body.Currency, body.Note)
        if err != nil {
            switch {
            case errors.Is(err, links.ErrInvalidAmount), errors.Is(err, links.ErrInvalidCurrency):
                WriteError(w, http.StatusBadRequest, err.Error())
            case errors.Is(err, context.DeadlineExceeded):
                WriteError(w, http.StatusRequestTimeout, "request timed out")
            default:
                WriteError(w, http.StatusInternalServerError, "server error")
            }
            return
        }

        WriteJSON(w, http.StatusCreated, l)
        return

    default:
        WriteError(w, http.StatusMethodNotAllowed, "method not allowed")
        return
    }
}

func (a *API) linksGet(w http.ResponseWriter, r *http.Request) {
    ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
    defer cancel()

    idStr := r.PathValue("id")
    id, err := strconv.Atoi(idStr)
    if err != nil || id <= 0 {
        WriteError(w, http.StatusBadRequest, "invalid link id")
        return
    }

    l, err := a.Links.Get(ctx, id)
    if err != nil {
        switch {
        case errors.Is(err, links.ErrNotFound):
            WriteError(w, http.StatusNotFound, "link not found")
        case errors.Is(err, context.DeadlineExceeded):
            WriteError(w, http.StatusRequestTimeout, "request timed out")
        default:
            WriteError(w, http.StatusInternalServerError, "server error")
        }
        return
    }

    WriteJSON(w, http.StatusOK, l)
}

func (a *API) linksUpdateNote(w http.ResponseWriter, r *http.Request) {
    ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
    defer cancel()

    idStr := r.PathValue("id")
    id, err := strconv.Atoi(idStr)
    if err != nil || id <= 0 {
        WriteError(w, http.StatusBadRequest, "invalid link id")
        return
    }

    var body struct {
        Note string `json:"note"`
    }
    if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
        WriteError(w, http.StatusBadRequest, "invalid JSON body")
        return
    }

    l, err := a.Links.UpdateNote(ctx, id, body.Note)
    if err != nil {
        switch {
        case errors.Is(err, links.ErrNotFound):
            WriteError(w, http.StatusNotFound, "link not found")
        default:
            WriteError(w, http.StatusBadRequest, err.Error())
        }
        return
    }

    WriteJSON(w, http.StatusOK, l)
}

func parseIntQuery(r *http.Request, key string, fallback int) int {
    raw := r.URL.Query().Get(key)
    if raw == "" {
        return fallback
    }
    v, err := strconv.Atoi(raw)
    if err != nil {
        return fallback
    }
    return v
}

Now you have:

GET /links?offset=0&limit=20
PUT /links/1 with body {"note":"new note"}

Step 4: Update tests for the new behavior

Update internal/httpapi/handlers_test.go by adding these tests.

func TestPagination(t *testing.T) {
    h := newTestServer()

    // Create 3 items
    for i := 0; i < 3; i++ {
        body := []byte(`{"amount":100,"currency":"usd","note":"x"}`)
        req := httptest.NewRequest(http.MethodPost, "/links", bytes.NewReader(body))
        req.Header.Set("Content-Type", "application/json")
        rec := httptest.NewRecorder()
        h.ServeHTTP(rec, req)

        if rec.Code != http.StatusCreated {
            t.Fatalf("expected 201, got %d body=%s", rec.Code, rec.Body.String())
        }
    }

    // Fetch page with limit=2
    req := httptest.NewRequest(http.MethodGet, "/links?offset=0&limit=2", nil)
    rec := httptest.NewRecorder()
    h.ServeHTTP(rec, req)

    if rec.Code != http.StatusOK {
        t.Fatalf("expected 200, got %d body=%s", rec.Code, rec.Body.String())
    }
}

func TestUpdateNote(t *testing.T) {
    h := newTestServer()

    // Create
    body := []byte(`{"amount":5000,"currency":"kes","note":"old"}`)
    req := httptest.NewRequest(http.MethodPost, "/links", bytes.NewReader(body))
    req.Header.Set("Content-Type", "application/json")
    rec := httptest.NewRecorder()
    h.ServeHTTP(rec, req)
    if rec.Code != http.StatusCreated {
        t.Fatalf("expected 201, got %d body=%s", rec.Code, rec.Body.String())
    }

    // Update
    up := []byte(`{"note":"new note"}`)
    req2 := httptest.NewRequest(http.MethodPut, "/links/1", bytes.NewReader(up))
    req2.Header.Set("Content-Type", "application/json")
    rec2 := httptest.NewRecorder()
    h.ServeHTTP(rec2, req2)

    if rec2.Code != http.StatusOK {
        t.Fatalf("expected 200, got %d body=%s", rec2.Code, rec2.Body.String())
    }
}

Run:

go test ./...

Step 5: Add an OpenAPI spec without turning into a bureaucracy

This is where teams often go wrong.

They either have no docs and everyone guesses, or they treat OpenAPI like a sacred ritual and stop shipping.

We will do a lightweight OpenAPI file by hand. Just enough so someone can integrate without calling you.

Create openapi.yaml at the project root.

openapi: 3.0.3
info:
  title: PayLinks API
  version: 1.0.0
servers:
  - url: http://localhost:8080
paths:
  /health:
    get:
      summary: Health check
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
  /links:
    get:
      summary: List payment links
      parameters:
        - in: query
          name: offset
          schema:
            type: integer
            minimum: 0
          required: false
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
          required: false
      responses:
        "200":
          description: Paginated list
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/PayLink"
                  total:
                    type: integer
                  offset:
                    type: integer
                  limit:
                    type: integer
    post:
      summary: Create a payment link
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amount, currency]
              properties:
                amount:
                  type: integer
                  minimum: 1
                currency:
                  type: string
                  example: USD
                note:
                  type: string
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PayLink"
  /links/{id}:
    get:
      summary: Get one payment link
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
            minimum: 1
      responses:
        "200":
          description: Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PayLink"
        "404":
          description: Not found
    put:
      summary: Update the note for a payment link
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
            minimum: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [note]
              properties:
                note:
                  type: string
      responses:
        "200":
          description: Updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PayLink"
components:
  schemas:
    PayLink:
      type: object
      properties:
        id:
          type: integer
        amount:
          type: integer
        currency:
          type: string
        note:
          type: string
        created_at:
          type: string
          format: date-time

Now your API has a contract.

Not perfect. Not automatic. But good enough to stop people from guessing.

Quick manual smoke test for Part 3

Run the server:

API_KEY=supersecret go run ./cmd/api

Create a few links:

curl -s -X POST http://localhost:8080/links \
  -H "X-API-Key: supersecret" \
  -H "Content-Type: application/json" \
  -d '{"amount":1200,"currency":"usd","note":"coffee"}'

curl -s -X POST http://localhost:8080/links \
  -H "X-API-Key: supersecret" \
  -H "Content-Type: application/json" \
  -d '{"amount":9000,"currency":"kes","note":"invoice 22"}'

List with pagination:

curl -s "http://localhost:8080/links?offset=0&limit=1" -H "X-API-Key: supersecret"

Update note:

curl -s -X PUT http://localhost:8080/links/1 \
  -H "X-API-Key: supersecret" \
  -H "Content-Type: application/json" \
  -d '{"note":"coffee, but make it urgent"}'

The real takeaway

If you remember one thing from all three parts, make it this:

Routing is not the hard part. The hard part is not letting routing become your entire application.

Keep handlers thin. Put rules in a service. Put shared behavior in middleware. Add tests early. Add docs before you forget what your API does.

This is how you build a Go server that does not require a rewrite the moment it gets real traffic.

And yes, you will still rewrite parts of it later. But it will be because you chose to, not because the code forced you into a corner with a chair.

Routing in Go Part 2: Upgrading the server so it behaves like a grown up

Edgar Nahama Alochi — Sat, 22 Aug 2026 20:34:53 +0000

Part 2: Upgrading the server

Tests, auth middleware, a service layer, and request timeouts

In part 1 we built a small payment links API.

In part 2 we are going to do the things everyone promises they will do “after launch” and then never do until something catches fire.

We will add:

A service layer so handlers stop doing business decisions
Auth middleware with a simple API key
Request scoped timeouts so slow work does not hang forever
Proper handler tests with httptest

Same rule as before. No magic. Code that compiles.

Step 1: Restructure into a sane layout

Keep it small, but separate responsibilities.

Create this structure:

mkdir -p cmd/api internal/httpapi internal/links

You will end up with:

cmd/api/main.go bootstraps the server
internal/httpapi routing, middleware, helpers
internal/links store and service logic

Step 2: Move the domain and store into `internal/links`

Create internal/links/model.go

package links

import "time"

type PayLink struct {
    ID        int       `json:"id"`
    Amount    int       `json:"amount"`
    Currency  string    `json:"currency"`
    Note      string    `json:"note"`
    CreatedAt time.Time `json:"created_at"`
}

Create internal/links/store.go

package links

import (
    "sync"
    "time"
)

type Store interface {
    Create(amount int, currency, note string) PayLink
    List() []PayLink
    Get(id int) (PayLink, bool)
}

type MemoryStore struct {
    mu    sync.RWMutex
    next  int
    links map[int]PayLink
}

func NewMemoryStore() *MemoryStore {
    return &MemoryStore{
        next:  1,
        links: make(map[int]PayLink),
    }
}

func (s *MemoryStore) Create(amount int, currency, note string) PayLink {
    s.mu.Lock()
    defer s.mu.Unlock()

    l := PayLink{
        ID:        s.next,
        Amount:    amount,
        Currency:  currency,
        Note:      note,
        CreatedAt: time.Now().UTC(),
    }
    s.links[l.ID] = l
    s.next++
    return l
}

func (s *MemoryStore) List() []PayLink {
    s.mu.RLock()
    defer s.mu.RUnlock()

    out := make([]PayLink, 0, len(s.links))
    for _, l := range s.links {
        out = append(out, l)
    }
    return out
}

func (s *MemoryStore) Get(id int) (PayLink, bool) {
    s.mu.RLock()
    defer s.mu.RUnlock()

    l, ok := s.links[id]
    return l, ok
}

Step 3: Add a service layer that owns the rules

This is where you put “currency must be 3 letters” and “amount must be positive”.

Create internal/links/service.go

package links

import (
    "context"
    "errors"
    "strings"
    "time"
)

var (
    ErrInvalidAmount   = errors.New("amount must be greater than zero")
    ErrInvalidCurrency = errors.New("currency must be a 3 letter code like USD")
    ErrNotFound        = errors.New("link not found")
)

type Service struct {
    store Store
}

func NewService(store Store) *Service {
    return &Service{store: store}
}

func (s *Service) Create(ctx context.Context, amount int, currency, note string) (PayLink, error) {
    select {
    case <-ctx.Done():
        return PayLink{}, ctx.Err()
    default:
    }

    currency = strings.ToUpper(strings.TrimSpace(currency))
    note = strings.TrimSpace(note)

    if amount <= 0 {
        return PayLink{}, ErrInvalidAmount
    }
    if len(currency) != 3 {
        return PayLink{}, ErrInvalidCurrency
    }

    // Pretend we might do more work here later.
    time.Sleep(5 * time.Millisecond)

    return s.store.Create(amount, currency, note), nil
}

func (s *Service) List(ctx context.Context) ([]PayLink, error) {
    select {
    case <-ctx.Done():
        return nil, ctx.Err()
    default:
    }
    return s.store.List(), nil
}

func (s *Service) Get(ctx context.Context, id int) (PayLink, error) {
    select {
    case <-ctx.Done():
        return PayLink{}, ctx.Err()
    default:
    }
    l, ok := s.store.Get(id)
    if !ok {
        return PayLink{}, ErrNotFound
    }
    return l, nil
}

Notice what happened.

Handlers no longer need to know the rules. They only translate HTTP into method calls.

That is how you stop your routing from turning into a soap opera.

Step 4: HTTP helpers and middleware

Create internal/httpapi/helpers.go

package httpapi

import (
    "encoding/json"
    "net/http"
)

func WriteJSON(w http.ResponseWriter, status int, v any) {
    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(status)
    _ = json.NewEncoder(w).Encode(v)
}

func WriteError(w http.ResponseWriter, status int, msg string) {
    WriteJSON(w, status, map[string]string{"error": msg})
}

Create internal/httpapi/middleware.go

package httpapi

import (
    "log"
    "math/rand"
    "net"
    "net/http"
    "strconv"
    "strings"
    "time"
)

type Middleware func(http.Handler) http.Handler

func Chain(h http.Handler, m ...Middleware) http.Handler {
    for i := len(m) - 1; i >= 0; i-- {
        h = m[i](h)
    }
    return h
}

func RequestID(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        id := r.Header.Get("X-Request-Id")
        if id == "" {
            id = newRequestID()
        }
        w.Header().Set("X-Request-Id", id)
        next.ServeHTTP(w, r)
    })
}

func Logging(logger *log.Logger) Middleware {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            start := time.Now()
            next.ServeHTTP(w, r)
            logger.Printf("%s %s from=%s dur=%s",
                r.Method,
                r.URL.Path,
                clientIP(r),
                time.Since(start).Round(time.Millisecond),
            )
        })
    }
}

func APIKeyAuth(expected string) Middleware {
    expected = strings.TrimSpace(expected)
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            // Let health stay public. Your uptime monitor is not your enemy.
            if r.URL.Path == "/health" {
                next.ServeHTTP(w, r)
                return
            }

            if expected == "" {
                // If no key is configured, do not pretend you are secure.
                WriteError(w, http.StatusInternalServerError, "server missing API key configuration")
                return
            }

            got := strings.TrimSpace(r.Header.Get("X-API-Key"))
            if got != expected {
                WriteError(w, http.StatusUnauthorized, "unauthorized")
                return
            }

            next.ServeHTTP(w, r)
        })
    }
}

func clientIP(r *http.Request) string {
    host, _, err := net.SplitHostPort(r.RemoteAddr)
    if err != nil {
        return r.RemoteAddr
    }
    return host
}

func newRequestID() string {
    return strconv.FormatInt(time.Now().UnixNano(), 36) + "-" + strconv.Itoa(rand.Intn(1000000))
}

Step 5: Handlers that use the service layer

Create internal/httpapi/handlers.go

package httpapi

import (
    "context"
    "encoding/json"
    "errors"
    "net/http"
    "strconv"
    "time"

    "example.com/paylinks/internal/links"
)

type API struct {
    Links *links.Service
}

func (a *API) Routes() http.Handler {
    mux := http.NewServeMux()

    mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
        WriteJSON(w, http.StatusOK, map[string]string{"status": "ok"})
    })

    mux.HandleFunc("/links", a.linksCollection)
    mux.HandleFunc("GET /links/{id}", a.linksGet)

    return mux
}

func (a *API) linksCollection(w http.ResponseWriter, r *http.Request) {
    ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
    defer cancel()

    switch r.Method {
    case http.MethodGet:
        items, err := a.Links.List(ctx)
        if err != nil {
            WriteError(w, http.StatusRequestTimeout, "request timed out")
            return
        }
        WriteJSON(w, http.StatusOK, items)
        return

    case http.MethodPost:
        var body struct {
            Amount   int    `json:"amount"`
            Currency string `json:"currency"`
            Note     string `json:"note"`
        }
        if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
            WriteError(w, http.StatusBadRequest, "invalid JSON body")
            return
        }

        l, err := a.Links.Create(ctx, body.Amount, body.Currency, body.Note)
        if err != nil {
            switch {
            case errors.Is(err, links.ErrInvalidAmount), errors.Is(err, links.ErrInvalidCurrency):
                WriteError(w, http.StatusBadRequest, err.Error())
            case errors.Is(err, context.DeadlineExceeded):
                WriteError(w, http.StatusRequestTimeout, "request timed out")
            default:
                WriteError(w, http.StatusInternalServerError, "server error")
            }
            return
        }

        WriteJSON(w, http.StatusCreated, l)
        return

    default:
        WriteError(w, http.StatusMethodNotAllowed, "method not allowed")
        return
    }
}

func (a *API) linksGet(w http.ResponseWriter, r *http.Request) {
    ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
    defer cancel()

    idStr := r.PathValue("id")
    id, err := strconv.Atoi(idStr)
    if err != nil || id <= 0 {
        WriteError(w, http.StatusBadRequest, "invalid link id")
        return
    }

    l, err := a.Links.Get(ctx, id)
    if err != nil {
        switch {
        case errors.Is(err, links.ErrNotFound):
            WriteError(w, http.StatusNotFound, "link not found")
        case errors.Is(err, context.DeadlineExceeded):
            WriteError(w, http.StatusRequestTimeout, "request timed out")
        default:
            WriteError(w, http.StatusInternalServerError, "server error")
        }
        return
    }

    WriteJSON(w, http.StatusOK, l)
}

Step 6: Wire it all together in `cmd/api/main.go`

Create cmd/api/main.go

package main

import (
    "context"
    "errors"
    "log"
    "net/http"
    "os"
    "os/signal"
    "syscall"
    "time"

    "example.com/paylinks/internal/httpapi"
    "example.com/paylinks/internal/links"
)

func main() {
    logger := log.New(os.Stdout, "", log.LstdFlags)

    apiKey := os.Getenv("API_KEY")
    store := links.NewMemoryStore()
    service := links.NewService(store)

    api := &httpapi.API{Links: service}
    routes := api.Routes()

    handler := httpapi.Chain(
        routes,
        httpapi.RequestID,
        httpapi.Logging(logger),
        httpapi.APIKeyAuth(apiKey),
    )

    srv := &http.Server{
        Addr:              ":8080",
        Handler:           handler,
        ReadHeaderTimeout: 5 * time.Second,
        ReadTimeout:       10 * time.Second,
        WriteTimeout:      10 * time.Second,
        IdleTimeout:       60 * time.Second,
    }

    go func() {
        logger.Println("listening on http://localhost:8080")
        if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
            logger.Fatalf("server error: %v", err)
        }
    }()

    waitForShutdown(logger, srv)
}

func waitForShutdown(logger *log.Logger, srv *http.Server) {
    stop := make(chan os.Signal, 1)
    signal.Notify(stop, os.Interrupt, syscall.SIGTERM)

    <-stop
    logger.Println("shutting down...")

    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()

    if err := srv.Shutdown(ctx); err != nil {
        logger.Printf("shutdown error: %v", err)
    }
    logger.Println("bye")
}

Run it:

API_KEY=supersecret go run ./cmd/api

Try without auth:

curl -s http://localhost:8080/links

You should get unauthorized.

Try with auth:

curl -s http://localhost:8080/links -H "X-API-Key: supersecret"

Now it works.

This is the exact point where a lot of people tell themselves they have “security”. You do not. You have a locked door. It is still a wooden door. But it is better than a sign that says “please do not hack”.

Step 7: Write tests that prove your routes behave

This is where confidence comes from. Not vibes.

Create internal/httpapi/handlers_test.go

package httpapi

import (
    "bytes"
    "net/http"
    "net/http/httptest"
    "testing"

    "example.com/paylinks/internal/links"
)

func newTestServer() http.Handler {
    store := links.NewMemoryStore()
    service := links.NewService(store)
    api := &API{Links: service}
    return api.Routes()
}

func TestHealth(t *testing.T) {
    h := newTestServer()

    req := httptest.NewRequest(http.MethodGet, "/health", nil)
    rec := httptest.NewRecorder()

    h.ServeHTTP(rec, req)

    if rec.Code != http.StatusOK {
        t.Fatalf("expected 200, got %d", rec.Code)
    }
}

func TestCreateAndGetLink(t *testing.T) {
    h := newTestServer()

    // Create
    body := []byte(`{"amount":5000,"currency":"kes","note":"invoice 183"}`)
    req := httptest.NewRequest(http.MethodPost, "/links", bytes.NewReader(body))
    req.Header.Set("Content-Type", "application/json")
    rec := httptest.NewRecorder()

    h.ServeHTTP(rec, req)

    if rec.Code != http.StatusCreated {
        t.Fatalf("expected 201, got %d body=%s", rec.Code, rec.Body.String())
    }

    // Get
    req2 := httptest.NewRequest(http.MethodGet, "/links/1", nil)
    rec2 := httptest.NewRecorder()

    h.ServeHTTP(rec2, req2)

    if rec2.Code != http.StatusOK {
        t.Fatalf("expected 200, got %d body=%s", rec2.Code, rec2.Body.String())
    }
}

func TestCreateValidation(t *testing.T) {
    h := newTestServer()

    body := []byte(`{"amount":0,"currency":"usd"}`)
    req := httptest.NewRequest(http.MethodPost, "/links", bytes.NewReader(body))
    req.Header.Set("Content-Type", "application/json")
    rec := httptest.NewRecorder()

    h.ServeHTTP(rec, req)

    if rec.Code != http.StatusBadRequest {
        t.Fatalf("expected 400, got %d body=%s", rec.Code, rec.Body.String())
    }
}

Run tests:

go test ./...

If it passes, congrats. You now have a codebase that can be changed without praying.

Step 8: Test auth middleware without hating your life

Right now tests call api.Routes() directly, so they bypass middleware.

That is good. You should test handlers and middleware separately.

Create internal/httpapi/middleware_test.go

package httpapi

import (
    "net/http"
    "net/http/httptest"
    "testing"
)

func TestAPIKeyAuth(t *testing.T) {
    final := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.WriteHeader(http.StatusOK)
    })

    h := APIKeyAuth("secret")(final)

    // Missing key
    req := httptest.NewRequest(http.MethodGet, "/links", nil)
    rec := httptest.NewRecorder()
    h.ServeHTTP(rec, req)

    if rec.Code != http.StatusUnauthorized {
        t.Fatalf("expected 401, got %d", rec.Code)
    }

    // Correct key
    req2 := httptest.NewRequest(http.MethodGet, "/links", nil)
    req2.Header.Set("X-API-Key", "secret")
    rec2 := httptest.NewRecorder()
    h.ServeHTTP(rec2, req2)

    if rec2.Code != http.StatusOK {
        t.Fatalf("expected 200, got %d", rec2.Code)
    }

    // Health is public
    req3 := httptest.NewRequest(http.MethodGet, "/health", nil)
    rec3 := httptest.NewRecorder()
    h.ServeHTTP(rec3, req3)

    if rec3.Code != http.StatusOK {
        t.Fatalf("expected 200 for health, got %d", rec3.Code)
    }
}

Run:

go test ./...

What we fixed, in human terms

You now have:

Routing that stays clean because handlers are thin
Business rules that live in a service, not scattered around
Middleware that centralizes behavior like auth
Timeouts so requests do not hang forever
Tests that turn fear into evidence

Also, you avoided the classic trap where the router becomes your entire application.

Your router is now just traffic control. As it should be.

Routing in Go Part 1: A small server you can grow without rewriting at midnight

Edgar Nahama Alochi — Sat, 22 Aug 2026 20:30:50 +0000

A small server you can grow without rewriting at midnight

Let me tell you how most “simple” Go servers die.

Day one: you ship a tiny API. One file. Three routes. Clean. You feel like a responsible adult.

Day fourteen: product asks for “just one more endpoint.” You add it.

Day twenty: you add auth. You copy paste auth into every handler because it is faster than thinking. You promise to clean it up later.

Day thirty: you have ten endpoints and three different authentication schemes, all apparently designed on mornings fueled by Cuban coffee, bold, chaotic, and deeply regrettable. Someone reports a bug, you fix it in one handler, and it still pops up because the other handler is running the vintage copy pasted Cuban roast edition.

If this had been built on calm, methodical Kenyan coffee, bright, balanced, and actually consistent, we might have one auth flow and far fewer existential crises

Then you do the most dangerous thing an engineer can do.

You say, “It is fine, it is just a small server.”

That phrase is how small servers become unmaintainable servers. Not because Go is hard. Because routing becomes a junk drawer.

So in this note, we are going to build a Go server with routing that stays boring and predictable. Boring is good. Boring survives.

The case we are building

You run a tiny payments product. Merchants hit your API to create payment links, list them, and fetch one link.

You have these routes:

GET /health so uptime monitors stop emailing you at 3am
POST /links create a payment link
GET /links list payment links
GET /links/{id} fetch one payment link

You are going to do this using the standard library, plus a small amount of structure so you do not end up with spaghetti handlers.

Everything compiles. No hidden magic.

Step 0: Create the project

mkdir go-routing-paylinks
cd go-routing-paylinks
go mod init example.com/paylinks

Create a file called main.go.

Step 1: Start with a server that is not allergic to production

Most examples online start with this:

http.ListenAndServe(":8080", nil)

That is fine for a tutorial. It is also how you end up with timeouts that do not exist and shutdowns that happen by accident.

We are going to start with sane defaults.

Paste this full program first. Run it. Confirm it works. Then we will add routes.

package main

import (
    "context"
    "encoding/json"
    "errors"
    "log"
    "math/rand"
    "net"
    "net/http"
    "os"
    "os/signal"
    "strconv"
    "syscall"
    "time"
)

func main() {
    logger := log.New(os.Stdout, "", log.LstdFlags)

    mux := http.NewServeMux()

    mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
        writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
    })

    handler := chain(
        mux,
        requestIDMiddleware,
        loggingMiddleware(logger),
    )

    srv := &http.Server{
        Addr:              ":8080",
        Handler:           handler,
        ReadHeaderTimeout: 5 * time.Second,
        ReadTimeout:       10 * time.Second,
        WriteTimeout:      10 * time.Second,
        IdleTimeout:       60 * time.Second,
    }

    go func() {
        logger.Println("listening on http://localhost:8080")
        if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
            logger.Fatalf("server error: %v", err)
        }
    }()

    waitForShutdown(logger, srv)
}

func waitForShutdown(logger *log.Logger, srv *http.Server) {
    stop := make(chan os.Signal, 1)
    signal.Notify(stop, os.Interrupt, syscall.SIGTERM)

    <-stop
    logger.Println("shutting down...")

    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()

    if err := srv.Shutdown(ctx); err != nil {
        logger.Printf("shutdown error: %v", err)
    }
    logger.Println("bye")
}

func writeJSON(w http.ResponseWriter, status int, v any) {
    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(status)
    _ = json.NewEncoder(w).Encode(v)
}

func writeError(w http.ResponseWriter, status int, msg string) {
    writeJSON(w, status, map[string]string{"error": msg})
}

type middleware func(http.Handler) http.Handler

func chain(h http.Handler, m ...middleware) http.Handler {
    for i := len(m) - 1; i >= 0; i-- {
        h = m[i](h)
    }
    return h
}

func requestIDMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        id := r.Header.Get("X-Request-Id")
        if id == "" {
            id = newRequestID()
        }
        w.Header().Set("X-Request-Id", id)
        next.ServeHTTP(w, r)
    })
}

func loggingMiddleware(logger *log.Logger) middleware {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            start := time.Now()
            next.ServeHTTP(w, r)
            logger.Printf("%s %s from=%s dur=%s",
                r.Method,
                r.URL.Path,
                clientIP(r),
                time.Since(start).Round(time.Millisecond),
            )
        })
    }
}

func clientIP(r *http.Request) string {
    host, _, err := net.SplitHostPort(r.RemoteAddr)
    if err != nil {
        return r.RemoteAddr
    }
    return host
}

func newRequestID() string {
    return strconv.FormatInt(time.Now().UnixNano(), 36) + "-" + strconv.Itoa(rand.Intn(1000000))
}

Run it:

go run .

Test it:

curl -s http://localhost:8080/health

If you get {"status":"ok"}, you are alive. The server is alive. Your monitoring tool is calm. Your inbox is safe for now.

Step 2: The pain we are fixing

Here is the most common routing mistake.

You start adding endpoints and you mix routing with business logic in one place. Then you add validation. Then you add auth. Then you add “just a quick special case.” Then it becomes a bowl of logic noodles.

We are going to avoid that by doing something boring:

define our data model
define a store
build handlers that only do HTTP work
keep shared behavior in middleware

This is not “enterprise architecture.” This is “I would like to sleep.”

Step 3: Build the payment link store

We will use an in memory store for the tutorial, but we will write it like it could become a database later.

Add this under the imports in main.go, after the imports.

type PayLink struct {
    ID        int       `json:"id"`
    Amount    int       `json:"amount"`
    Currency  string    `json:"currency"`
    Note      string    `json:"note"`
    CreatedAt time.Time `json:"created_at"`
}

type linkStore struct {
    mu    sync.RWMutex
    next  int
    links map[int]PayLink
}

func newLinkStore() *linkStore {
    return &linkStore{
        next:  1,
        links: make(map[int]PayLink),
    }
}

func (s *linkStore) create(amount int, currency, note string) PayLink {
    s.mu.Lock()
    defer s.mu.Unlock()

    l := PayLink{
        ID:        s.next,
        Amount:    amount,
        Currency:  currency,
        Note:      note,
        CreatedAt: time.Now().UTC(),
    }
    s.links[l.ID] = l
    s.next++
    return l
}

func (s *linkStore) list() []PayLink {
    s.mu.RLock()
    defer s.mu.RUnlock()

    out := make([]PayLink, 0, len(s.links))
    for _, l := range s.links {
        out = append(out, l)
    }
    return out
}

func (s *linkStore) get(id int) (PayLink, bool) {
    s.mu.RLock()
    defer s.mu.RUnlock()

    l, ok := s.links[id]
    return l, ok
}

Important: you need to add sync to your imports.

So your imports should include:

"sync"

Step 4: Add routes that do not turn into a crime scene

Now we wire up handlers.

Modern Go’s ServeMux supports patterns like GET /links/{id} and lets you extract {id} using r.PathValue("id").

Inside main(), add the store:

store := newLinkStore()

Then add these routes after the health route.

mux.HandleFunc("/links", func(w http.ResponseWriter, r *http.Request) {
    switch r.Method {
    case http.MethodGet:
        writeJSON(w, http.StatusOK, store.list())
        return

    case http.MethodPost:
        var body struct {
            Amount   int    `json:"amount"`
            Currency string `json:"currency"`
            Note     string `json:"note"`
        }
        if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
            writeError(w, http.StatusBadRequest, "invalid JSON body")
            return
        }

        body.Currency = strings.ToUpper(strings.TrimSpace(body.Currency))
        body.Note = strings.TrimSpace(body.Note)

        if body.Amount <= 0 {
            writeError(w, http.StatusBadRequest, "amount must be greater than zero")
            return
        }
        if body.Currency == "" {
            writeError(w, http.StatusBadRequest, "currency is required")
            return
        }
        if len(body.Currency) != 3 {
            writeError(w, http.StatusBadRequest, "currency must be a 3 letter code like USD")
            return
        }

        l := store.create(body.Amount, body.Currency, body.Note)
        writeJSON(w, http.StatusCreated, l)
        return

    default:
        writeError(w, http.StatusMethodNotAllowed, "method not allowed")
        return
    }
})

mux.HandleFunc("GET /links/{id}", func(w http.ResponseWriter, r *http.Request) {
    idStr := r.PathValue("id")
    id, err := strconv.Atoi(idStr)
    if err != nil || id <= 0 {
        writeError(w, http.StatusBadRequest, "invalid link id")
        return
    }

    l, ok := store.get(id)
    if !ok {
        writeError(w, http.StatusNotFound, "link not found")
        return
    }

    writeJSON(w, http.StatusOK, l)
})

You will also need to add strings to imports.

So imports should include:

"strings"

At this point you have all the routes you need. But let’s not pretend we are done. We still need the full file to compile.

To keep you from hunting missing imports, here is the full working main.go in one piece.

Full working code

Copy this whole file and run go run .

package main

import (
    "context"
    "encoding/json"
    "errors"
    "log"
    "math/rand"
    "net"
    "net/http"
    "os"
    "os/signal"
    "strconv"
    "strings"
    "sync"
    "syscall"
    "time"
)

type PayLink struct {
    ID        int       `json:"id"`
    Amount    int       `json:"amount"`
    Currency  string    `json:"currency"`
    Note      string    `json:"note"`
    CreatedAt time.Time `json:"created_at"`
}

type linkStore struct {
    mu    sync.RWMutex
    next  int
    links map[int]PayLink
}

func newLinkStore() *linkStore {
    return &linkStore{
        next:  1,
        links: make(map[int]PayLink),
    }
}

func (s *linkStore) create(amount int, currency, note string) PayLink {
    s.mu.Lock()
    defer s.mu.Unlock()

    l := PayLink{
        ID:        s.next,
        Amount:    amount,
        Currency:  currency,
        Note:      note,
        CreatedAt: time.Now().UTC(),
    }
    s.links[l.ID] = l
    s.next++
    return l
}

func (s *linkStore) list() []PayLink {
    s.mu.RLock()
    defer s.mu.RUnlock()

    out := make([]PayLink, 0, len(s.links))
    for _, l := range s.links {
        out = append(out, l)
    }
    return out
}

func (s *linkStore) get(id int) (PayLink, bool) {
    s.mu.RLock()
    defer s.mu.RUnlock()

    l, ok := s.links[id]
    return l, ok
}

func main() {
    logger := log.New(os.Stdout, "", log.LstdFlags)
    store := newLinkStore()

    mux := http.NewServeMux()

    mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
        writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
    })

    mux.HandleFunc("/links", func(w http.ResponseWriter, r *http.Request) {
        switch r.Method {
        case http.MethodGet:
            writeJSON(w, http.StatusOK, store.list())
            return

        case http.MethodPost:
            var body struct {
                Amount   int    `json:"amount"`
                Currency string `json:"currency"`
                Note     string `json:"note"`
            }
            if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
                writeError(w, http.StatusBadRequest, "invalid JSON body")
                return
            }

            body.Currency = strings.ToUpper(strings.TrimSpace(body.Currency))
            body.Note = strings.TrimSpace(body.Note)

            if body.Amount <= 0 {
                writeError(w, http.StatusBadRequest, "amount must be greater than zero")
                return
            }
            if body.Currency == "" {
                writeError(w, http.StatusBadRequest, "currency is required")
                return
            }
            if len(body.Currency) != 3 {
                writeError(w, http.StatusBadRequest, "currency must be a 3 letter code like USD")
                return
            }

            l := store.create(body.Amount, body.Currency, body.Note)
            writeJSON(w, http.StatusCreated, l)
            return

        default:
            writeError(w, http.StatusMethodNotAllowed, "method not allowed")
            return
        }
    })

    mux.HandleFunc("GET /links/{id}", func(w http.ResponseWriter, r *http.Request) {
        idStr := r.PathValue("id")
        id, err := strconv.Atoi(idStr)
        if err != nil || id <= 0 {
            writeError(w, http.StatusBadRequest, "invalid link id")
            return
        }

        l, ok := store.get(id)
        if !ok {
            writeError(w, http.StatusNotFound, "link not found")
            return
        }

        writeJSON(w, http.StatusOK, l)
    })

    handler := chain(
        mux,
        requestIDMiddleware,
        loggingMiddleware(logger),
    )

    srv := &http.Server{
        Addr:              ":8080",
        Handler:           handler,
        ReadHeaderTimeout: 5 * time.Second,
        ReadTimeout:       10 * time.Second,
        WriteTimeout:      10 * time.Second,
        IdleTimeout:       60 * time.Second,
    }

    go func() {
        logger.Println("listening on http://localhost:8080")
        if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
            logger.Fatalf("server error: %v", err)
        }
    }()

    waitForShutdown(logger, srv)
}

func waitForShutdown(logger *log.Logger, srv *http.Server) {
    stop := make(chan os.Signal, 1)
    signal.Notify(stop, os.Interrupt, syscall.SIGTERM)

    <-stop
    logger.Println("shutting down...")

    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()

    if err := srv.Shutdown(ctx); err != nil {
        logger.Printf("shutdown error: %v", err)
    }
    logger.Println("bye")
}

func writeJSON(w http.ResponseWriter, status int, v any) {
    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(status)
    _ = json.NewEncoder(w).Encode(v)
}

func writeError(w http.ResponseWriter, status int, msg string) {
    writeJSON(w, status, map[string]string{"error": msg})
}

type middleware func(http.Handler) http.Handler

func chain(h http.Handler, m ...middleware) http.Handler {
    for i := len(m) - 1; i >= 0; i-- {
        h = m[i](h)
    }
    return h
}

func requestIDMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        id := r.Header.Get("X-Request-Id")
        if id == "" {
            id = newRequestID()
        }
        w.Header().Set("X-Request-Id", id)
        next.ServeHTTP(w, r)
    })
}

func loggingMiddleware(logger *log.Logger) middleware {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            start := time.Now()
            next.ServeHTTP(w, r)
            logger.Printf("%s %s from=%s dur=%s",
                r.Method,
                r.URL.Path,
                clientIP(r),
                time.Since(start).Round(time.Millisecond),
            )
        })
    }
}

func clientIP(r *http.Request) string {
    host, _, err := net.SplitHostPort(r.RemoteAddr)
    if err != nil {
        return r.RemoteAddr
    }
    return host
}

func newRequestID() string {
    return strconv.FormatInt(time.Now().UnixNano(), 36) + "-" + strconv.Itoa(rand.Intn(1000000))
}

Step 5: Test the story, not just the code

Run:

go run .

Create a link:

curl -s -X POST http://localhost:8080/links \
  -H "Content-Type: application/json" \
  -d '{"amount":5000,"currency":"kes","note":"invoice 183"}'

List links:

curl -s http://localhost:8080/links

Fetch one:

curl -s http://localhost:8080/links/1

You now have a small API that demonstrates clean routing, basic validation, a store layer, middleware, and graceful shutdown.

And importantly, you did not create a handler that is half router, half therapist.

Why this structure stays sane

The rule is simple.

Handlers should be boring.

A handler should do three things:

parse and validate input
call a store or service
write a response

Middleware should handle cross cutting behavior like logging, request IDs, and auth.

If you keep that boundary, your routes do not rot. If you blur it, you will eventually spend a Saturday rewriting a server that “was just a small server.”

The Role of Clear Documentation in Team Velocity

Edgar Nahama Alochi — Sat, 01 Aug 2026 06:07:50 +0000

Most teams treat documentation like a speed bump.

They are wrong.

Documentation is engine oil.

When a team says “we don't have time to document,” what they are really saying is:

“We prefer to finance our progress with high-interest technical debt.”

Velocity is not about how fast you can type.

It is about how rarely you stop, stare at a function, and wonder what the developer who wrote it six months ago was trying to accomplish.

Documentation is not paperwork.

It is the preservation of intent.

The Speed Trap

There is a persistent myth in engineering:

“The code is the documentation.”

This is partially true.

Code explains what the system does. It is the ultimate source of truth for implementation.

But code is silent about why it does it that way.

Code tells you the implementation.

Documentation tells you the trade-offs.

When the why disappears, velocity disappears with it.

Every time a new engineer joins the team — or an old engineer returns to a forgotten module — they must perform digital archaeology. They dig through commit history, Slack threads, and half-remembered conversations trying to reconstruct the missing context.

This is not speed.

It is friction disguised as progress.

Why Velocity Actually Stalls

Velocity rarely dies because engineers type slowly.

Velocity dies because of uncertainty.

It shows up in predictable ways.

The Tribal Knowledge Tax

Critical information exists only in the heads of three senior engineers.

To move forward, you must interrupt them.

Your progress comes at the cost of their focus. The team slows down while pretending to move faster.

The Regression Loop

You see a line of code that looks redundant.

You remove it.

Two days later production breaks because that “redundant” line was quietly preventing an edge case discovered during a 2022 incident.

Documentation would have saved you two days and a few grey hairs.

The Decision Re-Run

The team spends three hours debating an architectural decision.

Six months later, the exact same meeting happens again.

No one remembers why the first decision was made.

So the debate starts from zero.

Again.

Documentation shrinks the time-to-understanding.

If a system takes ten minutes to understand instead of two hours, the team does not just move faster.

It moves confidently.

What to Document (And What to Ignore)

Most documentation fails because it documents the wrong things.

It explains syntax instead of decisions.

Useful documentation follows three simple rules.

1. Context Over Syntax

Do not explain that a loop iterates over an array.

Engineers already know that.

Explain why the system uses an array instead of a stream, or why a synchronous call was chosen over an asynchronous one.

The value of documentation is not repeating the code.

It is explaining the reasoning behind it.

2. Record Decisions (ADRs)

Architectural Decision Records are one of the highest leverage tools in engineering teams.

Every significant design decision should answer three questions:

What did we choose?
What alternatives did we consider?
Why did we reject them?

Without this, every new engineer eventually believes they have discovered a brilliant idea.

Often it is simply the same idea the team rejected two years ago.

3. The README Is a Map

A good README should get a new engineer from:

git clone

to a running, tested environment in five minutes.

If onboarding takes an hour, the documentation is broken.

If it takes two days, the architecture probably is too.

The Discipline of the Grown Engineer

Writing good documentation feels like a chore.

That is because it forces clarity.

You can hide confusion inside complicated code.

You cannot hide it inside a clear sentence.

If you cannot explain the intent of your system in writing, there is a good chance you do not fully understand it yet.

Documentation is not busywork.

It is an act of empathy for:

your future self
your teammates
the engineer who will inherit the system three years from now

(Who, statistically speaking, might also be you.)

The Uncomfortable Conclusion

Velocity is a function of clarity.

If your team claims to be moving fast but:

the architecture is a mystery
onboarding feels like a two-week hazing ritual
and every change requires consulting the “one person who knows the system”

then the team is not fast.

It is fragile.

Real velocity is sustainable.

It comes from a shared, written understanding of the system — one that survives beyond any individual developer.

Stop thinking of documentation as extra work.

Documentation is the work.

Everything else is just typing.

Designing for Change, Not Control

Edgar Nahama Alochi — Fri, 31 Jul 2026 17:21:11 +0000

There is a quiet lie we tell ourselves when we design systems.

We call it structure. We call it governance. We call it standards, frameworks, alignment. But beneath all those respectable words is a single desire: control.

I understand the temptation. I have felt it myself. When you are responsible for a system, a product, a team, or an organisation, you want predictability. You want to believe that if you think hard enough and design carefully enough, you can eliminate surprises. You want the future to behave.

It never does.

Architecture, whether technical or organisational, is temporal. A decision that is correct today can become a liability tomorrow. What solves a constraint at one stage often becomes the bottleneck at the next. That is not failure. That is the nature of growth.

The problem begins when we design as though today’s constraints will last forever.

Control is a snapshot. It captures the present and freezes it. But the world is not static. Markets move. Teams change. Customers evolve. Technology ages. Even our own understanding matures. Designing for control assumes stability. Designing for change assumes movement.

And movement is the more honest assumption.

When I design systems now, I do not ask, “How do I make this perfect?” I ask, “How will this need to evolve?” The first question leads to rigidity. The second leads to resilience.

Perfection is brittle. Resilience bends.

There is a particular kind of comfort that comes from tightly coupling everything. When components depend deeply on each other, when processes are heavily standardised, when decisions must pass through a single authority, things appear orderly. It feels safe. But that safety is deceptive. It works beautifully until the first significant change arrives. Then the cost of altering one part ripples through the entire structure.

Loose coupling, on the other hand, can feel untidy. It requires trust. It requires clarity at the boundaries rather than micromanagement at the centre. But when change inevitably comes, the system absorbs it rather than shattering under it.

Designing for change also demands humility. It means admitting that we do not fully understand the future. It means recognising that our current models are provisional. I have seen teams spend months polishing a grand design, only to discover that real users behave in ways no whiteboard session predicted. Feedback is not an interruption to design. It is design.

The deeper lesson is human. Systems do not change themselves. People change them. If the people inside a system do not understand it, cannot question it, or are afraid to adjust it, then no amount of architectural elegance will save it. Real adaptability comes from shared understanding, not from tighter control mechanisms.

There is a difference between clarity and control. Clarity defines purpose, principles, and constraints. Control dictates every action. The former enables autonomy. The latter suffocates it.

When I think about architecture over time, I see phases. Early on, we optimise for speed. Later, we optimise for stability. Eventually, we must optimise for adaptability. The mistake is assuming one optimisation strategy works forever. It does not. Every stage of growth creates new pressures. The structures that enabled momentum in one phase can quietly inhibit it in the next.

The irony is that designing for change often results in calmer systems. When flexibility is built in, emergencies decrease. When experimentation is safe, innovation becomes routine rather than disruptive. When failure is expected and contained, it does not escalate into catastrophe.

Control, by contrast, creates fragility. The tighter we grip, the more dramatic the break when something slips through.

This does not mean abandoning discipline. Designing for change is not the same as chaos. It requires clear interfaces, explicit assumptions, measurable outcomes, and thoughtful boundaries. It demands observability so that when the system shifts, we can see it. It demands modularity so that change in one area does not infect the whole. It demands continuous reflection so that decisions are revisited rather than fossilised.

In practice, this means making decisions that are reversible where possible. It means favouring principles over prescriptions. It means documenting intent, not just implementation. It means building teams capable of evolving the system rather than depending on a single architect to guard it.

Most importantly, it means letting go of the illusion that control equals competence.

Competence is the ability to adapt.

When I look back at systems I am proud of, they share a common trait. They survived change. They were not flawless. They were not static. They evolved without collapsing. The decisions within them were not perfect, but they were adjustable.

That is the standard I aim for now. Not control, but capacity. Not rigidity, but resilience. Not permanence, but progression.

The tide will always come in. The only real question is whether what we have built can endure its arrival and reshape itself when it does.

Design for that.

How to write technical posts that survive AI noise

Edgar Nahama Alochi — Wed, 29 Jul 2026 23:08:29 +0000

There is a new kind of content pollution on the internet.

It is clean looking.
It is fast.
It is confident.
It is usually correct in the same way instant noodles are usually a meal.

You have seen it.

Twenty posts explaining distributed systems with suspiciously identical examples.
Thirty threads about performance that all end with the same advice about caching.
A flood of technical content that sounds useful until you try to build anything from it and realize you were given a polished summary of someone else’s summary of someone else’s blog post from 2018.

This is the AI noise era.

Which is not the same thing as saying AI is bad.
It is not.
It is useful.
It is fast.
It can help good writers think better and move faster.

But it has changed the publishing environment in one important way.

Average content is now almost free.

That means the old strategy of writing a technically correct post with generic advice is no longer enough. If your post can be recreated in six seconds by a prompt and a decent model, your post is competing in a commodity market. Commodity markets are not kind to authors.

So the question is not how to write more posts.

The question is how to write technical posts that still matter when everyone can publish instantly.

The answer is depth.
But not the fake kind.

Real depth.

The kind that comes from contact with reality.

The first rule is simple

Write from experience before you write from explanation.

Most technical posts fail because they start with the concept and never arrive at the problem.

They explain what a thing is.
They list benefits.
They define terms.
They sound educational.
They leave the reader unchanged.

People do not remember definitions.
They remember tension.

A post survives AI noise when it begins with something the model cannot fake well on its own.
A real incident.
A painful trade off.
A mistake that cost time.
A decision that looked smart and later failed in production.
A problem that refused to behave the way the docs promised.

This does not mean every post needs a war story.

It means every post needs friction.

If you are writing about retries, do not begin with a textbook explanation of retries.

Begin with the duplicate payout incident.
Begin with the customer who got charged twice.
Begin with the queue that politely melted your downstream service because you retried immediately and at scale.
Now the reader cares.

AI can summarize concepts.
It struggles to replace earned judgment.

That is your advantage.
Use it.

Write for people who have to make decisions

A lot of technical writing is written for imaginary readers who have infinite time, full context, and no budget pressure.

That reader does not exist.

Real readers are trying to decide something.

Should we adopt this tool.
Should we refactor this service.
Should we split the database.
Should we introduce a queue.
Should we keep the monolith another year.
Should we trust this benchmark.
Should we hire for this skill.

If your post does not help someone make a decision, it will be skimmed, bookmarked, and forgotten. Which is a very polite way of saying ignored forever.

Strong technical posts are decision support documents disguised as articles.

They help the reader answer questions like these.

What problem is this actually good at solving.
What does it cost to run in the real world.
What breaks first.
What team maturity is required.
What signs tell me I am too early.
What signs tell me I am already late.

This is where experience shows.

A junior writer often explains what is possible.
A seasoned writer explains what is advisable.

That second one survives.

Stop writing encyclopedias

One of the easiest ways to sound intelligent and be useless is to write the complete guide.

The complete guide is often just a long apology for not making choices.

It includes everything.
It excludes judgment.
It is impossible to disagree with because it refuses to commit.

In an AI heavy internet, completeness is no longer a moat.
Machines are very good at exhaustive overviews.

What they are worse at is useful reduction.

Readers do not need more information.
They need better compression.

Write narrower.
Cut harder.
Choose a point of view.

Not this.

This article explains everything about observability.

Write this.

If your team has fewer than ten engineers, start observability with latency, error rate, and one business metric before buying a dashboard that requires its own onboarding ceremony.

That sentence has blood pressure.
It has a user.
It has constraints.
It has a recommendation.
Someone can disagree with it.
Good.
Now you are writing.

A post that survives AI noise usually has a spine.
It stands for something.

Originality is not being weird

Many people hear originality and immediately produce chaos.

No.
That is not originality.
That is just caffeine with formatting.

Original technical writing is usually familiar truth described with sharper honesty.

You do not need a revolutionary theory.
You need a real observation stated clearly.

For example.

Most teams do not have a scaling problem. They have a coordination problem wearing a scaling costume.

That is not a new law of physics.
But it is useful.
It is pointed.
It reflects reality many engineers have seen and few say out loud.

Originality often comes from pattern recognition.

After enough years, you notice that the same failure keeps returning in different clothes.
Different stack.
Same mistake.
Different logo.
Same organizational issue.
Different tooling.
Same missing ownership.

Write that pattern down.

That is the work.

AI can recombine language.
It cannot easily replace years of noticing.

Be specific where it matters and abstract where it helps

This is a craft skill and it changes everything.

Weak technical posts stay abstract for too long.
Strong ones move between concrete detail and general principle at the right moments.

If you stay abstract, the post feels airy.
If you stay too concrete, the post becomes a diary entry no one else can use.

You want both.

Show the concrete case.
Then extract the principle.
Then show where the principle breaks.

Example rhythm.

We moved retries into the worker and accidentally multiplied load during provider degradation.

The principle is that resilience mechanisms can increase failure pressure if they are not bounded.

The practical fix was backoff, jitter, idempotency keys, and a hard retry budget tied to business value.

Now the reader gets story, lesson, and implementation direction in one pass.

That survives because it teaches more than facts.
It teaches thinking.

Explain trade offs like an adult

AI generated technical content often has a familiar smell.
Everything is beneficial.
Every tool is powerful.
Every pattern improves scalability, reliability, developer experience, and perhaps your posture.

Real systems do not work like that.

Every technical decision creates winners and losers.
Every abstraction moves complexity somewhere.
Every convenience has a bill.
Usually monthly.

If you want your writing to survive, be the person who names the bill.

Do not just say event driven systems improve decoupling.

Say they also make debugging harder, make data consistency more social than technical, and require teams to care about contracts long after the launch excitement is gone.

Do not just say microservices improve scalability.

Say they can improve scaling for parts of the system while making ownership, testing, and incident response dramatically worse if your team structure is still operating like one monolith with more meetings.

This is what mature readers trust.

Not optimism.
Calibration.

A good technical post should feel like advice from someone who has paid for at least one bad decision.

Add the things AI usually leaves out

If you compare a lot of human technical writing with AI generated writing, one pattern appears quickly.

The machine often covers the what and the why.
It is much weaker on the when, the if, and the what happens next.

That gap is where your writing can become durable.

Include timing.

When should a team adopt this.
What stage is too early.
What symptoms suggest readiness.

Include prerequisites.

What must already be true for this approach to work.
Team skills.
Operational maturity.
Traffic patterns.
Business constraints.

Include failure modes.

How this goes wrong in practice.
What people underestimate.
What breaks during incidents.
What gets expensive quietly.

Include maintenance reality.

Who owns it in month nine.
How upgrades happen.
What knowledge becomes concentrated in one person and ruins everyone’s weekend when that person is offline.

Include reversibility.

Can the team back out.
How expensive is rollback.
What decisions become sticky.

These are not decorative details.
They are the difference between technical writing and technical marketing.

Your readers know the difference, even if they cannot always explain why one felt more trustworthy.

Use examples that reveal judgment, not just syntax

Code examples are good.
Tiny toy snippets with no context are often not.

There is a place for syntax teaching, but if the goal is a post that survives noise, examples should do more than compile.

They should expose design choices.

Instead of showing only how to implement a retry loop, show why you capped retries at a low number for non critical operations and used a dead letter queue for the rest.

Instead of showing only a cache wrapper, show how stale data tolerance changes by domain.
A product catalog can tolerate minutes.
A wallet balance cannot.
Now the reader learns architecture, not just code.

The most valuable examples are the ones that answer the hidden question in every engineer’s mind.

Yes, but how would you do this in a system that people actually use.

Write for that question.

Make your writing falsifiable

This sounds academic.
It is actually practical.

A lot of forgettable content survives only because it says nothing testable.
It is all vibes and verbs.

Robust technical writing makes claims that can be challenged.

For small teams, adding a service mesh before basic observability usually increases operational complexity faster than it increases reliability.

That is a claim.
People can debate it.
People can test it against experience.
People can add nuance.
That is healthy.

When your writing can be disagreed with, it has shape.
When it has shape, it gets remembered.

Do not hide behind endless caveats.
Yes, context matters.
It always matters.
You still have to say something.

The job is not to be impossible to criticize.
The job is to be useful enough to risk criticism.

Write like a human who has met other humans

There is a strange trend in technical writing where people remove all personality in order to sound serious.

This usually produces text that sounds like a compliance document explaining a toaster.

You do not need stand up comedy.
You do need a voice.

Humour helps because it compresses shared pain.

Everyone who has maintained a legacy system understands a line like this.

The code worked perfectly until we looked at it.

That line does work.
It creates rapport.
It signals experience.
It gives the reader a reason to continue.

Sarcasm helps too, in controlled doses.
The keyword is controlled.
You are seasoning a meal, not setting the kitchen on fire.

The goal is not to perform personality.
The goal is to sound like a competent person thinking clearly in public.

That tone survives because readers can feel the difference between a writer and a generator.

Structure matters more now than before

AI noise has trained readers to scan aggressively.

They are not rude.
They are adapting.

If your post has no shape, they will leave before your best point appears.

Give the reader a path.

Open with tension.
Name the problem.
State the claim.
Walk through reasoning.
Show examples.
Acknowledge trade offs.
End with a practical takeaway.

Good structure is not decoration.
It is respect.

It tells the reader you did the sorting before asking for their time.

A useful test is this.

If someone reads only your headings and first sentence of each section, do they still learn something meaningful.

If not, the post may be full of words and low on signal.

The strongest moat is lived specificity

There is a type of detail that instantly increases trust.

Not random detail.
Relevant detail.

We discovered the issue because checkout success rate dropped while API error rate looked normal, which meant the failure was happening in a dependency path our alerting did not treat as critical.

That sentence tells me the writer has been inside a real system.

It tells me they measure the right things.
It tells me they noticed a mismatch.
It tells me the lesson came from operations, not just reading.

This kind of specificity is hard to mass produce at scale.
Which is exactly why it works.

If you want durable writing, keep a notebook of incidents, decisions, and mistakes.
Not just outcomes.
Context too.

What you believed at the time.
What data you had.
What pressure existed.
What trade off you accepted.
What changed your mind.

That notebook becomes future articles.
More importantly, it becomes evidence.

Evidence beats volume.

Do not fight AI by pretending it does not exist

The winning move is not purity.
It is leverage.

Use AI for roughing out outlines.
Use it to challenge your blind spots.
Use it to generate counterarguments.
Use it to find gaps in your explanation.
Use it to clean phrasing after the thinking is done.

But do not outsource judgment.

If the model writes the core argument and you lightly edit it, you may publish faster.
You will also sound like everyone else publishing faster.

The right workflow for technical writing now is something like this.

Think from experience.
Draft from judgment.
Use tools for refinement.
Return with taste.
Cut aggressively.
Add reality.
Publish.

AI can increase your speed.
Only you can increase your signal.

A practical checklist before you publish

Read your draft and ask these questions.

Is there a real problem in the opening or did I start with generic explanation

Have I made at least one clear claim that someone could disagree with

Did I include trade offs or only benefits

Did I write for a decision maker or for an imaginary student of everything

Is there a section that could only come from direct experience

Did I include timing, prerequisites, and failure modes

Did I reduce the scope enough to be useful

Does the post sound like me or like a very polite documentation bot

If the answer to the last one hurts a little, good.
That means the test is working.

Final thought

AI noise is not the end of technical writing.

It is the end of lazy technical writing getting rewarded for existing.

Which is honestly fair.

The bar is different now.
Higher in some ways.
Better in others.

If average content is free, then judgment becomes premium.
If summaries are instant, then lived insight becomes scarce.
If everyone can publish, then the people who last will be the ones who can still say something real.

Write the post only you can write.

Not because it is precious.
Because it is useful.

And useful is still very hard to automate.

The Weekend Gold Rush and the Graveyard It Leaves Behind

Edgar Nahama Alochi — Wed, 29 Jul 2026 04:20:32 +0000

I have seen this movie before. Several times. The actors change. The soundtrack improves. The promises get louder. The ending stays the same.

Around 2000 it was this.

Everyone needs a website. Learn HTML in a weekend.

Suddenly the internet was full of blinking text, broken navigation, tables inside tables inside more tables, and a mysterious visitor counter at the bottom proudly displaying the number 7. Most of those sites died quietly. Some are still out there, fossilized in forgotten hosting accounts, whispering in Comic Sans.

Then 2008 arrived.

Mobile apps are printing money. Just learn iOS development.

Every developer with a MacBook became a visionary founder. To do lists. Flashlight apps. Another to do list but this one is social. The App Store filled up. So did the graveyard. Turns out shipping version one is easy. Maintaining version twelve while Apple changes everything and users demand perfection is not.

Then 2015.

Blockchain will change everything. Smart contracts. Decentralize the world.

Whitepapers were written. Tokens were minted. Conferences were attended. Most projects never launched. Many quietly shut down. The few that survived did so not because of hype, but because someone somewhere treated it like real engineering instead of a lottery ticket.

Now it is 2024.

AI will replace developers. Build a GPT wrapper this weekend. Launch an AI SaaS by Sunday. Retire by Wednesday.

Result?

Still loading.

The pattern is so predictable it should come with documentation.

First, a new technology emerges. It is genuinely powerful. It solves something real. It unlocks new capability.

Early adopters see opportunity. They experiment. They struggle. They learn the sharp edges. They build things that actually work.

Then the get rich quick crowd floods in.

Tutorials appear. Build X in 30 minutes. Ship your AI startup in a day. Passive income while you sleep.

Reality, as it always does, shows up uninvited.

Infrastructure costs are not passive. Hallucinations are not a feature. Latency is not just a vibe. Security matters. Data privacy matters. Customers do not care that you used the latest model if their invoice is wrong.

Then 90 percent fail. Not because the technology was useless. Because they skipped the fundamentals.

This is the part that is boring and therefore ignored.

What actually succeeds is deeply unfashionable.

People who understand the technology, not just the API.

People who solve a real problem instead of wrapping a model around a landing page.

People who build maintainable systems that survive version two.

People who think about cost before the first viral tweet.

People who apply engineering principles that worked before the hype cycle and will work long after it.

Clean architecture still matters.

Proper error handling still matters.

Cost management matters even more when your variable expense is a model that charges per token.

Security matters when your system is literally generating output from user input.

Testing matters. Monitoring matters. Observability matters. Especially when the output is probabilistic and your users expect determinism.

And perhaps most controversial of all, talking to customers still matters.

You cannot prompt engineer your way out of building something nobody wants.

I am not saying AI is not transformative. It is. It changes what is possible. It changes how we work. It changes the leverage a small team can have.

What it does not change is the physics of building durable systems.

After twenty years of watching waves come and go, here is the lesson.

New technology does not obsolete good engineering.

It makes it more important.

Because when the barrier to building drops, the barrier to competing drops with it. When anyone can launch in a weekend, the only thing that differentiates you is depth. Discipline. Taste. Restraint.

The gold rush is always loud.

The people who last are usually quiet.

So the question is simple.

Are you building for the long term.

Or are you building for the demo.

DEV Community: Edgar Nahama Alochi

The API is a Promise: Designing for Systems You No Longer Control

The Illusion of Agility

Design for the No

Versioning is a Strategy

The Reality of Ownership

What Experience Teaches Engineers to Optimize

Juniors often optimize for success

They optimize for blast radius

They optimize for change, not perfection

They optimize for clarity under pressure

They optimize for maintenance, not applause

They optimize for team speed, not individual heroics

They optimize for tradeoffs, not ideals

They optimize for boring outcomes

What changes as you grow

Final thought

The Cost of Cleverness: A Backend Engineer’s Guide to Strategic Simplicity

Cleverness always sends an invoice

How teams quietly drift into trouble

The hidden cost is almost always human

Debugging is where cleverness loses its shine

New engineers can feel the cleverness immediately

Simplicity takes more discipline than people admit

A few situations where cleverness usually sneaks in

So when is it worth being clever?

What I have come to value instead

The Unboring Truth About Boring Tech: How Startups Accidentally Build Research Labs

The Unboring Truth About Boring Tech

Or: How Startups Accidentally Build Research Labs

The Quiet Charm of Boring

The Hidden Cost of the Shiny New Thing

Why We Fall for the Trap

When to Get Fancy (and When Not To)

A Simple Litmus Test

Build for the Stage You're In

The Founder’s Trap: Shipping Fast Without Borrowing Against Your Future

Founding teaches you that speed has layers

Tinker made that lesson very real for me

The founder’s trap is not mess. It is sticky mess.

You learn very quickly where “later” likes to hide

Building in payments sharpens your sense of where to be strict

Founders do not need less speed. They need better spending

The human side of this is easy to miss

Success changes the meaning of early decisions

What I believe now

Routing in Go Part 3: The last upgrade

Part 3: The last upgrade

Pagination, update endpoint, request scoped logging, and lightweight OpenAPI

Step 1: Add pagination to the store and service

Update internal/links/store.go

Update internal/links/service.go

Step 2: Add request scoped logging that actually helps

Update internal/httpapi/helpers.go

Update internal/httpapi/middleware.go

Step 3: Update handlers for pagination and PUT

Update internal/httpapi/handlers.go

Step 4: Update tests for the new behavior

Step 5: Add an OpenAPI spec without turning into a bureaucracy

Quick manual smoke test for Part 3

The real takeaway

Routing in Go Part 2: Upgrading the server so it behaves like a grown up

Part 2: Upgrading the server

Tests, auth middleware, a service layer, and request timeouts

Step 1: Restructure into a sane layout

Step 2: Move the domain and store into internal/links

Step 3: Add a service layer that owns the rules

Step 4: HTTP helpers and middleware

Step 5: Handlers that use the service layer

Step 6: Wire it all together in cmd/api/main.go

Step 7: Write tests that prove your routes behave

Step 8: Test auth middleware without hating your life

What we fixed, in human terms

Routing in Go Part 1: A small server you can grow without rewriting at midnight

A small server you can grow without rewriting at midnight

The case we are building

Step 0: Create the project

Step 1: Start with a server that is not allergic to production

Step 2: The pain we are fixing

Step 3: Build the payment link store

Update `internal/links/store.go`

Update `internal/links/service.go`

Update `internal/httpapi/helpers.go`

Update `internal/httpapi/middleware.go`

Update `internal/httpapi/handlers.go`

Step 2: Move the domain and store into `internal/links`

Step 6: Wire it all together in `cmd/api/main.go`