DEV Community: Edgar Nahama Alochi

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.

Chaos engineering essentials for small teams

Edgar Nahama Alochi — Tue, 28 Jul 2026 05:58:19 +0000

You do not need Netflix scale to deserve failure

Chaos engineering sounds like something only companies with thousands of microservices and a platform team the size of a small country should care about.

That is a myth.

Small teams break in quieter ways.

A background job silently retries forever.
A webhook endpoint times out and no one notices.
A database connection pool saturates under a traffic spike.
An external payment provider starts returning 502 and your system politely collapses.

Chaos engineering is not about drama.
It is about humility.

It is the discipline of admitting your system will fail and choosing to learn that on a Tuesday afternoon instead of during your biggest customer demo.

What chaos engineering actually is

It is not random destruction.
It is not breaking production for fun.
It is not deleting databases to prove you are brave.

Chaos engineering is controlled failure experimentation.

You form a hypothesis about how your system behaves under stress.
You introduce a small, reversible failure.
You observe.
You learn.
You improve.

That is it.

The goal is confidence.
Not coverage.
Not hero stories.
Confidence.

Why small teams need it more than big ones

Large companies have redundancy in people.

You probably do not.

If one senior engineer is on vacation and the system degrades in a weird way, you do not have a war room. You have Slack messages and mild panic.

Small teams usually have:

Limited observability.
Shared infrastructure.
One database doing everything.
A few critical integrations that must work.
Very little operational slack.

This is exactly the environment where hidden failure modes thrive.

Chaos engineering for small teams is less about sophistication and more about survival.

Essential principle one: start with failure modes, not tools

Before you install anything, answer this question.

How does this system actually die?

Not in theory.
In reality.

Make a simple list.

What happens if the database becomes slow.
What happens if Redis disappears.
What happens if Stripe times out.
What happens if DNS resolution fails.
What happens if one pod runs out of memory.
What happens if a background worker crashes mid job.

If you cannot answer these confidently, you have your starting point.

Chaos begins with thoughtfulness.

Essential principle two: write a steady state definition

You cannot detect degradation if you do not define normal.

What does healthy mean for your system?

It might be:

Ninety nine percent of requests complete under 300 milliseconds.
Error rate stays under one percent.
Checkout success rate stays above a defined threshold.
Background jobs do not accumulate beyond a certain depth.

Write this down.

Chaos engineering without a steady state definition is just creative vandalism.

Essential principle three: start small and reversible

You do not need a chaos platform.
You need discipline.

Examples a small team can run safely:

Introduce artificial latency in a single dependency.
Temporarily block outbound traffic to one third party service.
Kill one application instance.
Throttle CPU on a staging node.
Simulate a failed webhook response.

Do this in staging first.
Then do it in production with tight scope and clear rollback.

If your heart rate is too high while running the experiment, it is too large.

Essential principle four: observability is not optional

If you cannot see it, you cannot learn from it.

At minimum you need:

Request latency metrics.
Error rate metrics.
Basic logs with correlation IDs.
Health indicators for external dependencies.
Alerting tied to real user impact, not infrastructure noise.

Many small teams think they are not ready for chaos engineering.

In reality they are not ready for ignorance.

Even basic metrics change everything.

Essential principle five: automate the lessons

The point of running experiments is not to feel clever.

It is to harden the system.

After every experiment ask:

Did our alerts trigger.
Did we detect the issue quickly.
Did the system degrade gracefully.
Did users notice.
Did recovery require manual heroics.

If the answer includes the word hero, you have work to do.

Add timeouts.
Add circuit breakers.
Add retries with backoff.
Add idempotency.
Add clearer alerts.
Add runbooks.

Small teams win by building systems that fail predictably.

Essential principle six: design for graceful degradation

Perfection is unrealistic.
Grace is achievable.

If a recommendation service fails, the product page should still load.
If an analytics endpoint times out, the checkout must still complete.
If one payment provider fails, another should take over.
If email delivery fails, the core transaction should still succeed.

This is architectural thinking.
Chaos engineering simply reveals where you forgot it.

Essential principle seven: avoid chaos theater

There is a trap here.

You can make chaos engineering look impressive.

Fancy dashboards.
Dramatic experiments.
Big internal presentations.

None of that matters if your system still collapses under simple pressure.

For small teams, chaos engineering should feel boring.

Routine.
Predictable.
Methodical.

If it feels theatrical, you are optimizing for attention.

A practical starter plan for small teams

Here is a calm, realistic roadmap.

Month one.
Define steady state.
Add missing metrics.
Identify top five failure modes.

Month two.
Run one controlled experiment in staging.
Improve alerts and logging.
Document findings.

Month three.
Run one small scoped production experiment.
Fix the weakest resilience gap discovered.
Write a runbook.

Repeat quarterly.

You do not need to be aggressive.
You need to be consistent.

The uncomfortable truth

Your system is already chaotic.

You just have not observed it under stress yet.

Hardware fails.
Networks partition.
Cloud providers degrade.
External APIs rate limit.
Human operators make mistakes.

Chaos engineering is not introducing instability.

It is introducing honesty.

Final thought

Small teams often optimize for speed.

Ship fast.
Fix later.
Trust that things will hold.

Chaos engineering is how you ship fast without gambling.

It gives you confidence that when reality pushes back, your system bends instead of shatters.

You do not need scale to practice resilience.

You need maturity.

And maturity begins with the courage to ask one simple question.

What happens if this breaks.

Then actually finding out.

When to refactor vs rewrite

Edgar Nahama Alochi — Mon, 27 Jul 2026 19:56:55 +0000

A decision tree for grown engineers

Every engineering team eventually faces the same dramatic sentence.

We should just rewrite this.

It is usually said after a bug, a missed deadline, or a moment of emotional exhaustion while reading a file that appears to have been written during a power outage.

Rewriting feels clean. Refactoring feels responsible.

One sounds heroic. The other sounds like laundry.

But this decision is not about emotion. It is about risk, economics, and time.

Let us walk through it like adults.

First question

Does the system work

Not beautifully. Not elegantly. Not in a way that makes you proud.

Does it work.

If the system is stable, generating value, and customers depend on it daily, you are not staring at a technical problem. You are staring at a revenue engine.

Rewriting revenue engines is not bravery. It is surgery.

Refactor when the system works but hurts.

Rewrite when the system fundamentally cannot meet current or future requirements.

If it works and you just dislike the style, close the tab and drink water.

Second question

Is the problem structural or local

Local problems are ugly functions, confusing modules, long files, poor naming, duplicated logic.

Structural problems are incorrect domain models, broken abstractions, wrong architectural boundaries, impossible scaling constraints.

Refactoring fixes local problems very well.

Rewriting is justified only when the architecture itself prevents progress.

If you can improve it piece by piece without stopping delivery, refactor.

If every small change creates chaos because the foundations are wrong, then you may need a rewrite.

Be honest here. Most problems are local.

Third question

Do you fully understand the current system

This is where most rewrite projects quietly die.

If the current system is confusing, that confusion often contains business rules that no one documented.

Legacy code is frequently a fossil record of production incidents.

When you rewrite without fully understanding the behavior, you do not create a cleaner system. You create a regression generator.

If the answer is no, you do not understand it deeply, your first step is not rewrite.

Your first step is to learn.

Refactor while learning. Add tests. Document behavior. Shrink uncertainty.

Rewrite only after you can explain the old system clearly to someone else.

Fourth question

Is delivery allowed to slow down

Rewrites consume focus. They create parallel universes. You maintain old and new simultaneously.

If your company cannot afford slower feature delivery for months, rewriting is fantasy.

Refactoring allows incremental progress. You improve while shipping.

If the business needs momentum, refactor.

If the business is intentionally investing in a platform reset, and everyone understands the cost, then rewrite can be strategic.

But it must be a business decision, not a developer mood swing.

Fifth question

Are tests strong enough to protect you

Refactoring relies on safety nets.

If you do not have meaningful tests, refactoring feels dangerous and rewriting feels tempting.

But here is the uncomfortable truth.

Rewriting without tests is gambling at a higher table.

If you cannot confidently change the system today, you will not magically become confident rebuilding it from scratch.

Invest in tests first.

The decision becomes clearer once safety exists.

Sixth question

Is the pain growing or stable

Some code is ugly but stable. It does its job quietly.

Other systems become slower, harder to change, and more fragile every quarter.

If the cost of change is compounding, you are facing architectural debt.

In that case, continuing to patch may be more expensive than starting fresh.

If the cost is flat and predictable, refactoring over time is usually sufficient.

Measure change cost. Do not guess.

The practical decision tree

Here is the simplified version.

Does it work and generate value
Yes
Then prefer refactor

Does the architecture block critical future goals
Yes
Consider rewrite

Do you deeply understand current behavior
No
Learn and refactor first

Can the business tolerate slower delivery
No
Refactor

Are tests strong
No
Strengthen them before anything dramatic

Is change cost compounding
Yes
Rewrite might be strategic

Notice something.

Rewrite appears only after several gates.

That is intentional.

The emotional trap

Rewriting feels productive because it removes friction instantly.

You open a new folder. The files are clean. The abstractions are pure. You feel like an architect instead of a mechanic.

But software is not a painting. It is an evolving system embedded in reality.

The old code survived production traffic. It contains scar tissue that protects you from repeating mistakes.

Refactoring respects that history.

Rewriting erases it.

Sometimes erasing is necessary. Often it is ego.

A healthier pattern

Instead of thinking refactor or rewrite, think in layers.

Stabilize the existing system with tests.

Extract boundaries slowly.

Replace modules behind interfaces.

Strangle old components with new ones.

Over time, the system becomes new without a dramatic rewrite event.

The business never feels a reset. The engineers never freeze progress.

This is less cinematic. It is also less catastrophic.

The uncomfortable conclusion

Most teams do not need rewrites.

They need discipline.

They need tests, clearer boundaries, smaller pull requests, and patience.

Rewrites are rare strategic moves.

Refactoring is daily engineering.

If you find yourself wanting to rewrite, ask one final question.

Am I solving a structural constraint
Or am I trying to escape complexity I have not yet understood

The answer determines whether you are being an engineer

Or just emotionally refactoring your feelings.

DEV Community: Edgar Nahama Alochi

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

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

Full working code

Step 5: Test the story, not just the code

Why this structure stays sane

The Role of Clear Documentation in Team Velocity

The Speed Trap

Why Velocity Actually Stalls

The Tribal Knowledge Tax

The Regression Loop

The Decision Re-Run

What to Document (And What to Ignore)

1. Context Over Syntax

2. Record Decisions (ADRs)

3. The README Is a Map

The Discipline of the Grown Engineer

The Uncomfortable Conclusion

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`