DEV Community: Nsikan Patrick Adaowo

Coupling vs. Cohesion: The Two Forces That Shape Good Software

Nsikan Patrick Adaowo — Thu, 17 Sep 2026 04:31:45 +0000

Good software is not only about making each component work.

It is also about deciding:

What belongs together?
What should stay separate?
Which modules should know about each other?
How much knowledge should one component have about another?
What should happen when one part of the system changes?

Two concepts help answer these questions:

Cohesion: how closely related the responsibilities inside a module are.

Coupling: how dependent one module is on other modules.

The goal is usually simple:

High cohesion within modules and low coupling between modules.

This sounds like a theoretical software engineering principle, but it directly affects how easy your system is to understand, test, scale, and change.

It works, but is that enough?

When developers build a feature under pressure, the first goal is usually to make it work.

That is understandable.

A client needs the feature. A product manager wants the release. A deadline is approaching. You write the endpoint, connect the database, call the external provider, return the response, and move on.

At that moment, the code may look perfectly fine.

The trouble starts when the system grows.

A simple order service begins to:

Validate customer information.
Calculate prices.
Apply discounts.
Check inventory.
Process payment.
Send emails.
Publish events.
Write audit logs.
Generate invoices.

A small change to the payment provider now requires opening the order service. A change to email behaviour affects order creation. A new discount rule breaks an unrelated checkout flow.
The code still works—but it has become expensive to change.

This is often a design problem involving coupling and cohesion.

What is cohesion?

Cohesion describes how closely related the responsibilities inside a module are.

A highly cohesive module focuses on one clear purpose.

For example, an authentication module may contain:

Login.
Logout.
Token refresh.
Password reset.
Session validation.

These responsibilities are related because they all belong to identity and access management.

A module that contains authentication, invoice generation, image resizing, and product recommendations has low cohesion.

The code may still compile, but the module does not have a clear identity.

A simple analogy
Imagine a toolbox.

A toolbox containing screwdrivers, pliers, measuring tape, and a wrench has a clear purpose: helping you perform repairs.

Now imagine opening the same toolbox and finding:

Cooking utensils.
Medical supplies.
Office stationery.
Car keys.
Gardening tools.

The box may contain useful things, but it is no longer organized around one meaningful purpose.

Low-cohesion software feels the same way.

You find unrelated functionality in the same class or module, and you are never sure where the next responsibility should go.

High cohesion in code
Consider this service:

The name UserService does not explain the actual boundaries.

Some methods deal with users. Others deal with communication, billing, and reporting.

A more cohesive design might separate them:

Now each module has a clearer purpose.

When a developer needs to change password-reset behavior, they know where to look.

When invoice requirements change, authentication code is less likely to be affected.

That is the practical benefit of cohesion: related things stay together, and unrelated things stay apart.

What is coupling?

Coupling describes the degree of dependency between different modules.

Two modules are tightly coupled when one knows too much about the other or depends heavily on its internal details.

A change in one module may force changes in several others.

Consider:

This service is coupled to:

Paystack.
Prisma.
A specific payment response format.
A specific database implementation.

If you replace Paystack, change the database library, or alter the payment workflow, this service must change.

That is tight coupling.

A loosely coupled design depends on stable contracts instead:

The order service depends on capabilities, not concrete infrastructure:

Now the payment provider and database implementation can change behind the abstractions.

Cohesion and coupling work together

Cohesion and coupling are not competing goals.

They describe two sides of software structure:

Cohesion looks inside a module.
Coupling looks between modules.

A healthy design aims for:

High cohesion inside
Low coupling between

Think of a well-organized company.

Each department focuses on a specific responsibility:

Finance handles finances.
Human resources handles people operations.
Sales handles customers and revenue.
Engineering handles product development.

The departments still communicate, but they do so through clear responsibilities and defined processes.

If every department performs every task, the organization becomes chaotic.

If departments cannot communicate at all, work also stops.

Software modules behave similarly.

The goal is not zero coupling.

The goal is controlled coupling.

Why zero coupling is impossible

Every useful system contains dependencies.

An order system needs payment information. A dashboard needs reporting data. A notification service needs information about events. A controller needs an application service.

The goal is not to remove every dependency.

The goal is to make dependencies:

Necessary.
Explicit.
Stable.
Small.
Easy to replace.
Easy to test.
Easy to understand.

A controller depending on an application service is normal.

An application service knowing the private implementation details of three databases, two payment providers, and an email server is a warning sign.

Types of coupling

Coupling can appear in different forms.

Content coupling
One module directly accesses or modifies the internal data of another module.

This is highly dangerous because the consuming module depends on implementation details.

If internalState changes, the order service breaks.

Common coupling
Multiple modules depend on shared global state.

Global state can make behavior difficult to predict and test.

One module may modify the state while another module assumes it has not changed.

Control coupling
One module tells another how to behave by passing flags.

This can become problematic when the receiving service accumulates many branches:

Sometimes a strategy or channel abstraction is clearer.

Data coupling
One module passes only the data another module needs.

This is generally healthier because the dependency is explicit and limited.

Message coupling
Modules communicate through messages or events without depending heavily on each other’s internal structure.

Message-based communication can reduce direct coupling, though it introduces other concerns such as event versioning, delivery guarantees, retries, and eventual consistency.

Types of cohesion

Cohesion can also vary in strength.

Functional cohesion
A module contains elements that work together to perform one well-defined task.

Example:

Both methods belong to password hashing.

Sequential cohesion
One operation produces data consumed by another operation within the same module.

For example:

These operations form a clear sequence in a file-import workflow.

Communicational cohesion
Several operations work on the same data.

For example, a profile module may validate, update, and format user-profile data.

Coincidental cohesion
A module contains unrelated utilities simply because they were created around the same time.

This kind of module often grows into a dumping ground.

The problem with utility folders is not that utilities are always bad. The problem is that unrelated behaviour becomes difficult to own, test, and discover.

A practical example: order processing
Let us compare two designs.

Low cohesion and high coupling

This service has many responsibilities.

It is also coupled to several infrastructure systems.

Possible consequences:

Large and slow tests.
Difficult mocking.
High risk of regression.
Unclear error handling.
Difficult reuse.

Every change affects the same class.

High cohesion and controlled coupling

Each component owns a focused responsibility.

The use case still coordinates the workflow, but the details are distributed across meaningful boundaries.

This design is not automatically perfect.

It may introduce more files and abstractions.

But if the application is complex and these concerns change independently, the separation creates value.

Coupling in a NestJS application

NestJS encourages dependency injection, which can help reduce coupling.

A service can receive dependencies through its constructor:

This is better than constructing concrete dependencies inside the service:

Constructor injection makes dependencies visible.

It also makes testing easier:

The service can be tested without connecting to a real database or sending real emails.

However, dependency injection alone does not guarantee low coupling.

You can still inject a massive concrete service that exposes too many responsibilities.

The quality of the boundary matters more than the presence of the injection mechanism.

Coupling in modular monoliths

A modular monolith may run as one deployable application while maintaining strong internal boundaries.

For example:

The modules can communicate through:

Public application interfaces.
Domain events.
Commands.
Queries.
Shared contracts.

They should avoid reaching directly into one another’s internal repositories or private tables without a clear reason.

A modular monolith can provide many benefits of good boundaries without immediately introducing the operational complexity of microservices.

This is especially useful for early-stage SaaS products.

You can keep deployment simple while keeping responsibilities organized.

Coupling in microservices

Microservices do not automatically create low coupling.

A system can have separate deployable services and still be tightly coupled if:

Every request requires five synchronous service calls.
Services share the same database tables.
One service depends on another’s internal schema.
All services must deploy together.
A small contract change breaks many consumers.
A single service failure brings down the entire workflow.

This is distributed coupling.

The services are separate in code and deployment,but tightly connected in behaviour.

A well-designed microservice should own a meaningful capability and communicate through stable contracts.

But even then, network communication introduces costs:

Latency.
Timeouts.
Retries.
Partial failures.
Versioning.
Observability.
Eventual consistency.

Sometimes a well-modularized monolith has less harmful coupling than a poorly designed microservice architecture.

The number of services is not a measure of design quality.

Cohesion and database design

Coupling and cohesion also apply to data.

A module should ideally own the data required for its responsibility.

For example:

Billing module → subscriptions, invoices, billing transactions
Inventory module → stock levels, reservations, warehouses
Identity module → users, credentials, sessions, permissions

If every module directly reads and writes every table, the database becomes a hidden integration layer.

Changes become risky because nobody knows which services depend on which columns, indexes, or status values.

This does not mean every module must have a separate database.

A modular monolith can use one database while still enforcing ownership boundaries.

The important question is:

Who owns this data, and how should other modules access it?

Clear ownership improves cohesion.
Controlled access reduces coupling.

Coupling and event-driven design

Events can reduce direct dependency between modules.

Instead of the order module directly calling the notification module:

it may publish an event:

The notification module subscribes to that event.

This creates looser direct coupling because the order module does not need to know how notifications work.

However, event-driven systems introduce new trade-offs:

Events may be delayed.
Events may be delivered more than once.
Consumers may process events out of order.
Event schemas must evolve carefully.
Debugging requires tracing across asynchronous flows.
Data may become eventually consistent.

Events reduce some forms of coupling, but they do not eliminate system complexity.

They move the complexity from direct calls to contracts, delivery, and observability.

Signs of high coupling

Your codebase may be tightly coupled when:

A small change requires edits across many modules.
Tests need the entire application to run.
Classes instantiate their own dependencies.
Modules access one another’s private data.
A shared utility module contains business logic for everything.
Multiple services depend on the same database schema.
Replacing a provider requires changing business logic.
One failed dependency causes unrelated features to fail.
Developers avoid refactoring certain areas because the impact is unpredictable.

High coupling creates a change ripple.

One adjustment travels through the system, touching code that should not have been affected.

Signs of low cohesion

A module may have low cohesion when:

Its name is vague, such as CommonService or Utils.
Its methods serve unrelated business functions.
It changes frequently for different reasons.
Developers are unsure where to add new functionality.
The module has too many dependencies.
Its tests cover unrelated behaviour.
Removing one method leaves the remaining methods unrelated.
The module requires a long explanation before anyone understands its purpose.

A useful question is:

If I had to describe this module in one sentence, would the description be clear?

If the answer is no, the module may need a better boundary.

How to improve cohesion

Group behavior by business capability
Instead of organizing everything by technical type:

controllers/
services/
repositories/
utils/

consider also thinking in terms of capabilities:

The best structure depends on the application, but grouping related behavior makes ownership clearer.

Keep related data and behavior close
If a business rule always operates on a particular concept, consider keeping the rule near that concept.

For example, order status transitions may belong to an order domain model or order service rather than a general utility file.

Separate unrelated reasons to change
If one module changes because of payment requirements, email requirements, and reporting requirements, it probably contains multiple responsibilities.

Split it around those change patterns.

Avoid generic dumping grounds
Be cautious with:

utils.
helpers.
common.
misc.
shared-service.

These folders can be useful, but they often become places where code is stored without a clear owner.

How to reduce coupling

Depend on abstractions
Define contracts around capabilities:

The application service should not need to know the database library.

Use dependency injection
Pass dependencies into a component instead of constructing them internally.

This makes dependencies explicit and replaceable.

Encapsulate internal details
Expose what another module needs, not everything the module knows.

A module should not expose its internal database models, private state, and implementation-specific helper methods unnecessarily.

Prefer messages for some workflows
Events and commands can reduce direct knowledge between modules.

Use them where asynchronous behavior and eventual consistency are acceptable.

Define stable contracts
Use clear request and response models.

Avoid passing internal database entities everywhere. Internal data structures change more frequently than business contracts.

Limit shared mutable state
Shared mutable state is one of the easiest ways to create unpredictable coupling.

Prefer explicit inputs and outputs.

The balance: cohesion versus coupling

It is possible to overcorrect.

Suppose you split one simple function into ten classes.

You may reduce local responsibilities, but create excessive coordination and indirection.

This is sometimes called accidental complexity.

A good architecture balances:

Cohesion.
Coupling.
Simplicity.
Performance.
Team understanding.
Operational cost.

You do not want modules so large that everything is mixed together.

You also do not want modules so fragmented that understanding one workflow requires jumping through twenty files.

The right boundary is usually where:

Responsibilities change together.
Data is accessed together.
Business rules belong together.
The module can be explained clearly.
The dependency is meaningful.

A useful code review framework

When reviewing a module, ask:

About cohesion

Do these methods belong to the same business capability?
Do they use the same data?
Do they change for similar reasons?
Does the module have one clear purpose?

About coupling

What does this module know about other modules?
Does it depend on implementation details?
Can a dependency be replaced easily?
Does a small change here affect many consumers?
Are dependencies explicit?

About boundaries

Who owns this business rule?
Who owns this data?
Is this communication synchronous or asynchronous?
Is the contract stable?
Is the abstraction solving a real problem?

These questions help you evaluate design beyond whether the code is syntactically clean.

The connection to SOLID

Coupling and cohesion are closely connected to SOLID principles.

Single Responsibility improves cohesion.
Open/Closed reduces unnecessary changes to stable modules.
Liskov Substitution creates reliable contracts.
Interface Segregation reduces unnecessary dependencies.
Dependency Inversion reduces coupling to infrastructure.

They are also related to:

Encapsulation.
Separation of concerns.
Domain-driven design.
Modular architecture.
Clean architecture.
Hexagonal architecture.
Event-driven design.

But the underlying idea remains simple:

Put related responsibilities together, and prevent unrelated components from knowing too much about one another.

Final thoughts

Good software is not made of isolated components that never communicate.

It is made of focused components that communicate intentionally.

High cohesion gives each module a clear identity.

Low coupling prevents changes from spreading unnecessarily.

When cohesion is low, modules become confusing.

When coupling is high, the entire system becomes fragile.

When both are poor, every feature becomes a negotiation with the existing codebase.

The goal is not to eliminate dependencies.

The goal is to make dependencies deliberate, visible, and manageable.

So, the next time you create a service, module, class, or microservice, ask two questions:

Does everything inside this component belong together?

And:

Does this component know more about the outside world than it needs to know?

Those two questions can prevent a lot of future pain.

Because maintainable software is not software with no complexity.

It is software where complexity has been given a clear place to live.

When Abstraction Becomes a Bottleneck: The Real Cost of Overengineering

Nsikan Patrick Adaowo — Thu, 10 Sep 2026 14:04:08 +0000

Abstraction is one of the most powerful tools in software engineering.

It hides complexity. It reveals intent. It reduces duplication. It makes systems easier to understand, test, and change.
But abstraction has a shadow side.

When applied too early, too generically, or without a clear problem, abstraction can become a bottleneck.

It can make code harder to read, harder to debug, and harder to evolve.

It can turn simple workflows into mazes of indirection.

It can create the illusion of flexibility while introducing hidden coupling.

And perhaps most dangerously, it can make engineers feel productive while actually reducing the team’s ability to ship.

This article explores when abstraction becomes harmful, why overengineering is more expensive than duplication, and how to recognize the signs that your design is working against you.

The promise of abstraction

Abstraction is how we manage complexity.

Instead of thinking in terms of bits and bytes, we work with concepts like users, orders, payments, and notifications.

Instead of repeating the same logic in ten places, we extract a function.

Instead of coupling business rules to a specific database, we define a repository interface.

Good abstractions:

Reduce cognitive load.
Clarify intent.
Make change safer.
Enable reuse.
Protect core logic from infrastructure details.

They are essential for building maintainable systems.

But not every abstraction is good.

And not every problem needs an abstraction.

The hidden cost of premature abstraction

Premature abstraction happens when you generalize a solution before you fully understand the problem.

You see a pattern that appears twice. You assume it will appear a third time. You create an interface, a factory, a strategy, and a configuration object to support every possible future variation.

The code looks sophisticated.

But the abstraction is built on assumptions, not evidence.

The asymmetry of technical debt

There is an important asymmetry between premature optimization and premature abstraction.

Premature optimization usually affects a localized part of the code.

For example, you implement a complex caching layer for a function that is called a few times per day. The optimization is unnecessary, but its impact is limited.

Premature abstraction, on the other hand, can affect the entire architecture.

When you introduce semantic boundaries and logical coupling before the problem domain is understood, you create a mesh of dependencies that resists evolution.

The cost of unwinding a wrong abstraction is not linear.

It is often geometric.

You may need to dismantle entire subsystems, update multiple layers, and reconcile conflicting mental models.

The cost of removing a premature optimization is typically isolated to a specific function or block.

The cost of removing a premature abstraction can ripple through the entire codebase.

Signs that abstraction has become a bottleneck

1. Too many layers of indirection
You need to jump through five files to understand a simple operation.

Controller → Service → UseCase → Handler → Processor → Adapter

Each layer adds indirection without adding clarity.

The call chain is deep, but the business intent is unclear.

2. Overly complex class hierarchies
Your class hierarchy has multiple levels of abstract classes and interfaces.

BaseService → AbstractCrudService → EntityService → UserService

Each layer introduces hooks, configuration options, and extension points that are rarely used.

New developers cannot tell which methods are important and which are legacy.

3. Methods with too many parameters
A method signature looks like this:

The method tries to support every possible scenario.

As a result, it is difficult to call, difficult to test, and difficult to understand.

4. Generic components that handle everything
A single component or service tries to support every use case.

The class becomes a dumping ground for unrelated functionality.

Its name no longer communicates intent.

5. Configuration objects that hold everything
A configuration object accumulates settings for multiple concerns:

The configuration becomes unreadable and impossible to evolve safely.

Changing one setting may affect unrelated parts of the system.

6. Names that hide intent
Classes and functions are named with generic terms:

Manager
Processor
Handler
Service
Controller
Provider

The names do not convey what the component actually does.

A developer must read the implementation to understand its purpose.

7. Conditional branches that proliferate
A single function contains many conditional branches to support different scenarios:

The function tries to be versatile, but it becomes complex and fragile.

Adding a new type requires modifying the central function and understanding all existing branches.

8. Onboarding becomes extremely difficult
New developers take weeks to understand the codebase.

They must decipher multiple layers of abstraction before they can make a simple change.

The joy of building yields to the chore of deciphering.

9. Breaking one abstraction breaks the whole
A single abstraction is used by many parts of the system.

When you change it, multiple features break.

The abstraction has become a concentration risk.

10. Domain intent disappears
The code no longer reflects the business domain.

Instead of Order, Payment, and Invoice, you have Entity, Resource, and Model.

Instead of chargePayment, you have executeAction.

The connection between the code and the problem it solves is lost.

The real cost of overengineering

Overengineering is not just an aesthetic problem.

It has real costs.

- Slower development
Features take longer to implement because engineers must navigate multiple layers of abstraction.

Simple changes require understanding complex call chains.

Estimates slip because the cognitive surface is larger than it appears.

- More bugs
Abstractions that try to support too many scenarios introduce edge cases.

Conditional branches multiply.

Configuration options interact in unexpected ways.

The system becomes harder to reason about, and bugs become harder to locate.

- Higher maintenance cost
Maintaining an overengineered system requires more effort.

Developers must understand not only what the code does, but why it was designed this way.

Refactoring becomes risky because the impact of changes is difficult to predict.

- Reduced morale
Engineers join teams to build things.

When the codebase feels like a maze, motivation declines.

Talent departs when the joy of building yields to the chore of deciphering.

- Lost opportunities
Overengineered systems resist change.

New ideas are avoided because they do not fit the existing abstraction.

The team spends more time reconciling mental models than shipping value.

Duplication is cheaper than the wrong abstraction

One of the most important lessons in software design is this:

Duplication is far cheaper than the wrong abstraction.

When you duplicate code, you pay a localized cost.

When you change one copy, you may need to change the other.

But the impact is limited.

When you create the wrong abstraction, you pay a systemic cost.

The abstraction couples multiple parts of the system.

Changing it requires understanding all consumers.

The cost of unwinding it can be geometric.

This does not mean duplication is always good.

It means that premature generalization is often more expensive than waiting until the pattern is clear.

A useful rule is the “rule of three”:

Implement the logic the first time.

Implement it the second time, even if it looks similar.
When you see it a third time, consider an abstraction.

This rule is not absolute, but it encourages evidence-based design.

You abstract when you have seen the pattern, not when you predict it.

When abstraction is appropriate

Abstraction is not the enemy.

Bad abstraction is.

Good abstraction is appropriate when:

The pattern has appeared multiple times.
The variation is real, not speculative.
The abstraction clarifies intent.
The boundary is meaningful.
The cost of change is reduced.
The team can understand and maintain it.
For example, a payment gateway abstraction is useful when:
You have multiple payment providers.
The business may change providers.
The core logic should not depend on a specific provider.
Testing is easier with a fake implementation.
A repository abstraction is useful when:
The data access strategy may change.
The domain logic should not depend on a specific database.
Testing is easier with an in-memory implementation.

But if you have one payment provider and no plan to change, a direct implementation may be simpler.

If you have one database and no need for multiple implementations, a direct repository may be clearer.

The goal is not to avoid abstraction.

The goal is to avoid abstraction that does not yet earn its place.

The YAGNI principle

YAGNI stands for “You Aren’t Going to Need It.”

The principle says:

Do not implement functionality until it is necessary.

This does not mean you should ignore the future.

It means you should not implement speculative features or abstractions based on assumptions.

There is no reason to make code more complicated just so that down the road you may be able to make it more flexible.

YAGNI complements other principles such as:

DRY (Don’t Repeat Yourself).
KISS (Keep It Simple, Stupid).
SOLID.
Separation of concerns.

The balance is important.

DRY encourages removing duplication.

YAGNI encourages waiting until the duplication is real.

Together, they suggest:

Do not repeat yourself unnecessarily, but do not abstract prematurely.

WET before DRY
Another useful perspective is “WET before DRY.”

WET stands for “Write Everything Twice.”

The idea is that duplicating code once or twice is not costly.

It allows you to understand the pattern before abstracting it.

Starting with DRY from the beginning increases the chances of bad generalizations.

When you attempt to DRY up the code too early, you may:

Optimize prematurely.

Bundle operations with different contexts.

Create abstractions that do not fit the problem.

An alternative is to see WET and DRY as complementary.

Start with a basic design.

When you find duplicated code two or three times, consider an abstraction.

After working on the problem for some time, reflect on how to abstract based on the challenges you faced.

Practical guidelines for avoiding over-abstraction

1. Wait for evidence
Do not abstract based on predictions.

Wait until you have seen the pattern multiple times.

Ask:

Has this variation appeared in production?

Is this a real requirement or a hypothetical scenario?

Will this abstraction simplify the next feature?

2. Favor explicit code
Explicit code is easier to understand than clever abstractions.

If a function has three clear steps, write them explicitly.

If a workflow has four distinct operations, name them clearly.

Do not hide simple logic behind layers of indirection.

3. Keep abstractions close to the domain
Abstractions should reflect the business domain, not technical convenience.

Use names like Order, Payment, and Invoice instead of Entity, Resource, and Model.

Use verbs like chargePayment and createOrder instead of executeAction and processResource.

4. Limit configuration
Avoid configuration objects that hold everything.

Split configuration by concern:

Database configuration.
Feature flags.
External API keys.
Tenant settings.

This makes the configuration easier to understand and evolve.

5. Reduce indirection
Ask whether each layer adds value.

If a layer only delegates to another layer without adding behaviour, consider removing it.

Deep call chains increase cognitive load without improving design.

6. Test the abstraction
Before adopting an abstraction, ask:

Can a new developer understand it in ten minutes?
Does it make the next feature easier to implement?
Does it reduce the number of concepts a developer must hold in their head?
Does it make testing easier or harder?

If the answer is no, the abstraction may not be worth the cost.

7. Prefer composition over inheritance
Inheritance can create deep hierarchies that are difficult to understand.

Composition allows you to assemble behaviour from smaller components.

For example:

This is often clearer than a deep inheritance tree.

8. Document the intent
If an abstraction is necessary, document its intent.

Explain:

Why the abstraction exists.
What problem it solves.
What scenarios it supports.
What scenarios it does not support.

This helps future developers understand the design decisions.

A practical example: notification service
Consider a notification system.

Overengineered design

The abstraction tries to support every possible scenario.

The configuration object holds settings for multiple concerns.

The method contains many conditional branches.

Adding a new channel requires modifying the central method and understanding all existing logic.

Simpler design

Each channel is a separate implementation.

The service delegates to the appropriate channel.

Adding a new channel requires creating a new implementation, not modifying existing logic.

The design is simpler, clearer, and easier to extend.

When to refactor

Refactoring is appropriate when:

The pattern has appeared multiple times.
The duplication is causing maintenance problems.
The abstraction will clarify intent.
The team can understand and maintain it.
The cost of change is reduced.
Refactoring is premature when:
The pattern has appeared once.
The variation is speculative.
The abstraction adds indirection without clarity.
The team cannot explain the design in simple terms.
The cost of change increases. The goal is not to avoid refactoring.

The goal is to refactor based on evidence, not prediction.

The balance: Goldilocks abstraction

Abstraction should be “just right.”

Not too little, not too much.

A codebase with too little abstraction can be repetitive and difficult to maintain.

A codebase with too much abstraction can be difficult to understand and evolve.

The sweet spot is when:

The code reflects the domain.
The abstractions are meaningful.
The call chains are shallow.
The intent is clear.
The team can onboard quickly.
Change is easier, not harder.
This balance is not static.
It evolves as the system grows and the team learns.

The important skill is recognizing when an abstraction has crossed the line from helpful to harmful.

Final thoughts

Abstraction is a tool, not a goal.

Good abstraction reduces complexity.

Bad abstraction creates it.

The real cost of overengineering is not measured in lines of code.

It is measured in:

Slower development.
More bugs.
Higher maintenance cost.
Reduced morale.
Lost opportunities.

Duplication is often cheaper than the wrong abstraction.

Waiting for evidence is often wiser than predicting the future.

Explicit code is often clearer than clever design.

The next time you create an abstraction, ask:

Does this simplify the next feature?
Can a new developer understand this in ten minutes?
Is this pattern real or speculative?
Does this reduce or increase the cognitive load?

Because good software is not software with the most abstractions.

It is software that can be understood, changed, and extended without unnecessary friction.

And sometimes, the best design is the one that resists the urge to generalize before it is ready.

Dependency Injection Explained: Why Your Classes Shouldn't Know How Everything Is Built

Nsikan Patrick Adaowo — Sun, 30 Aug 2026 12:31:31 +0000

Your codebase may not be failing because it lacks features. It may be failing because everything knows too much about everything else.

Most backend developers learn dependency injection through a framework.

In NestJS, you add decorators. In Spring, you annotate classes. In Angular, you declare providers. The framework then constructs your objects and passes their dependencies.

Everything works fine.

But many developers stop at the mechanics.

They learn how to use dependency injection, but not why it matters.

They learn the syntax, but not the design principle.

They learn the pattern, but not the problem it solves.

The result is code that uses dependency injection but still feels tightly coupled, difficult to test, and fragile when requirements change.

This article explains what dependency injection really is, why your classes should not know how their dependencies are built, and how to use it in a way that improves maintainability, testability, and flexibility.

The problem: classes that build their own world

Consider this service:

This code may work.

But it has a hidden problem.

The OrderService knows:

Which database library to use.
Which payment provider to call.
Which email client to instantiate.
How to construct each dependency.

This creates tight coupling.

If you want to:

Replace Paystack with Flutterwave.
Switch from Prisma to TypeORM.
Use a different email provider.
Test the service without calling real APIs.
Use a different configuration in staging versus production.

you must modify the service itself.
The class is responsible not only for its business logic, but also for constructing its entire world.
This is the opposite of what dependency injection tries to achieve.

What dependency injection actually is

Dependency injection is a design pattern where a class receives its dependencies from the outside instead of creating them internally.
Instead of:

You write:

The dependency is provided by an external assembler, such as:

A framework container.
A factory function.
A manual composition root.
A dependency injection library.

The class no longer decides how its dependencies are built.
It only declares what it needs.

Inversion of Control: the bigger idea

Dependency injection is a specific way to implement a broader principle called Inversion of Control.
In traditional code, a high-level component directly creates or locates its low-level dependencies.
For example:

The ReportGenerator controls how the database is obtained.
Under Inversion of Control, this responsibility is inverted.
An external mechanism provides the dependency:

Now the framework or container controls object creation and dependency resolution.
The high-level component declares what it needs but does not control how it is constructed.
This inversion of control leads to looser coupling and greater flexibility.

Constructor injection: the most common form

The most widely used form of dependency injection is constructor injection.
Dependencies are passed through the constructor:

This approach has several advantages:

The object is fully initialized when created.
Dependencies are clearly visible in the constructor signature.
Fields can be immutable.
It fails fast if a dependency is missing.

A class that requires certain dependencies should not be constructible without them.
Constructor injection enforces this requirement.

Setter and interface injection

Other forms of dependency injection exist, though they are less common in modern backend code.

Setter injection

Dependencies are provided through setter methods after construction:

This can be useful when dependencies are optional or change over time, but it also allows objects to exist in a partially initialized state.

Interface injection

A class implements an interface that defines how dependencies are injected.
This is less common in TypeScript and JavaScript ecosystems.
For most backend applications, constructor injection is the simplest and most reliable approach.

A practical NestJS example

NestJS provides a built-in dependency injection container.
A service can declare its dependencies in the constructor:
NestJS resolves the dependencies when the service is instantiated.
The service does not need to know:

Whether OrderRepository uses Prisma, TypeORM, or a raw SQL client.
Whether PaymentGateway is implemented with Paystack, Stripe, or a mock.
How NotificationService sends messages.

It only knows the capabilities it requires.
This separation makes the service easier to test and easier to evolve.

Why dependency injection matters

1. Reduced coupling
When a class constructs its own dependencies, it is tightly coupled to those implementations.
Dependency injection separates the use of a dependency from its construction.
The class depends on an abstraction or interface, not on a specific concrete class.
This makes it easier to switch implementations without modifying the consumer.
For example, you can replace a payment gateway implementation without changing the order service.
2. Improved testability
Testing becomes easier when dependencies can be replaced with fakes or mocks.
Consider this test:

The test can verify:

The correct amount is charged.
The order is created with the right data.
The notification is sent.
Error handling behaves correctly.

No real database, payment provider, or email server is required.
This makes tests faster, more reliable, and easier to run in isolation.
3. Easier configuration management
Different environments often require different configurations.
For example:

Development may use local services.
Staging may use test providers.
Production may use real providers.

With dependency injection, you can compose different implementations for different environments without changing the core business logic.
4. Clearer responsibilities
When a class receives its dependencies, its constructor signature communicates what it needs.
This makes the code easier to understand.
A developer can look at the constructor and immediately see the external capabilities the class depends on.
This is more explicit than hidden instantiations scattered throughout methods.
5. Better separation of concerns
Dependency injection helps separate:

Business logic.
Infrastructure details.
Object construction.
Configuration.

The business logic focuses on what needs to happen.
The infrastructure layer focuses on how to interact with external systems.
The composition root or container focuses on how to assemble everything.
This separation makes the system easier to reason about and easier to change.

Dependency injection versus service locator

A service locator is another pattern for obtaining dependencies.
Instead of injecting dependencies, a class asks a central registry for them:

This may look convenient, but it has important drawbacks:
Dependencies are hidden.

The class can request anything from the locator.
It is harder to see what a class truly needs.
Tests must configure the global locator.
It can encourage tight coupling to the locator itself.

Dependency injection makes dependencies explicit and visible in the constructor.
This clarity is one of its main advantages.

Common mistakes with dependency injection

Injecting concrete implementations everywhere

Dependency injection is most powerful when classes depend on abstractions.
If every service depends directly on concrete classes, you still have tight coupling, even if the container constructs them.
For example:

This is better than creating new PrismaClient() inside the service, but the service is still coupled to Prisma.
A repository abstraction can help:

Now the service depends on a capability, not a specific library.

Overusing dependency injection

Not every function needs to be a class with injected dependencies.
Simple utilities, pure functions, and small helpers may not benefit from dependency injection.
For example:

This function has no external dependencies.
Wrapping it in a class and injecting it through a container adds unnecessary complexity.
Use dependency injection where it solves a real problem: managing dependencies, improving testability, and reducing coupling.

Creating too many tiny services

Dependency injection can encourage splitting behavior into many small services.
This can be useful, but it can also create fragmentation.
If understanding one workflow requires jumping through twenty classes, the design may be over-engineered.
The goal is not maximum fragmentation.
The goal is clear responsibilities and manageable boundaries.

Ignoring the composition root

In a NestJS application, the framework handles much of the composition.
But in plain TypeScript or other environments, you need a place where the application is assembled.
This is often called the composition root.

It is where you:

Create concrete implementations.
Configure providers.
Wire dependencies together.
Start the application.

Keeping this logic centralized makes the system easier to understand and easier to configure for different environments.

Dependency injection and interfaces

Dependency injection works especially well with interfaces or abstract classes.
An interface defines a contract:

Multiple implementations can satisfy the contract:

The business logic depends on the interface:

This makes it easy to:

Switch providers.
Test with a fake implementation.
Introduce a new provider without modifying the checkout logic.

The class does not know how the payment is implemented.
It only knows what it can ask the payment gateway to do.

Dependency injection in a multi-tenant SaaS

In a multi-tenant SaaS platform, different tenants may require different configurations.
For example:

Different payment providers.
Different email providers.
Different storage backends.
Different feature flags.

Dependency injection can help you compose tenant-specific implementations.
A tenant context can determine which implementation to use:

The rest of the application depends on PaymentGateway, not on the specific provider.
This keeps tenant-specific logic contained and makes the core application more stable.

Dependency injection and testing strategies

Dependency injection enables several testing strategies.

Unit testing with fakes

You can provide simple in-memory or hardcoded implementations:

The service can be tested without a real database.

Unit testing with mocks

Mocking libraries can create objects that record how they were called:

This verifies that the service interacts correctly with its dependencies.
Integration testing with real dependencies
For integration tests, you can use real or containerized dependencies:

A test database.
A test message broker.
A test email service or stub.

Dependency injection makes it easier to swap between test and production configurations.

Dependency injection and clean architecture

Clean architecture and hexagonal architecture emphasize separating:

Domain logic.
Application logic.
Infrastructure.
Interfaces.

Dependency injection supports this separation by allowing inner layers to depend on abstractions while outer layers provide concrete implementations.
For example:

The application layer does not import infrastructure details.
It only defines the capabilities it needs.
This makes the system easier to evolve and easier to test.

When dependency injection may be overkill

Dependency injection is not required for every piece of code.
It is most valuable when:

A class has external dependencies.
You need to test the class in isolation.
Implementations may change.
Configuration differs between environments.
You want to reduce coupling.

It may be unnecessary when:

The code is a simple script.
The function has no external dependencies.
The behaviour is trivial and stable.
The overhead outweighs the benefit.

Use dependency injection intentionally, not as a default ritual.

A simple mental model

You can think of dependency injection as answering three questions:
What does this class need?
Declared in the constructor.
Who provides it?
The container, factory, or composition root.
How is it built?
The concrete implementation, configuration, or environment.
The class only answers the first question.
The other questions are handled externally.
This separation is what makes the code more flexible and easier to test.

Final thoughts

Dependency injection is not only a framework feature.
It is a design choice about who controls object creation and how dependencies are managed.
When your classes know how to build everything they need, they become tightly coupled to those implementations.
When your classes declare what they need and receive it from the outside, they become easier to test, easier to configure, and easier to change.
This does not mean every function must be a class with injected dependencies.
It means that when a component has external dependencies, those dependencies should be explicit, replaceable, and managed outside the component.
Because good software is not only about making each class work.
It is about designing a system where change does not require rewriting everything that depends on it.
And dependency injection is one of the most practical tools for achieving that.

What Actually Happens When 10,000 Users Hit Your "Buy Now" Button at The Same Time

Nsikan Patrick Adaowo — Mon, 03 Aug 2026 18:25:56 +0000

Every e-commerce team dreams of massive traffic spikes—until those spikes actually happen.

Imagine this: You’ve spent weeks (maybe months) building your e-commerce backend. Your API endpoints are clean, your database schema is normalized, and your authentication flow is solid. You test it with 10 users. It works. You test with 100. It still works.

Then Black Friday hits. Or your product goes viral on TikTok. Or a celebrity tweet about your app. Suddenly, it’s no longer just one request (or even a hundred)—it’s 10,000, all landing on the same endpoint within the same second, all fighting over the same rows in your database.

Your server slows to a crawl. Some users get errors. Others get charged twice. A lucky few get their orders, but the rest get nothing.

This is the exact moment most engineers discover that “it works on my machine” and “it works under concurrency” are two completely different claims.

What Went Wrong?

This isn’t just a “traffic spike” problem. It’s a concurrency, architecture, and systems design problem. If you’re building scalable backends—especially in Node.js, NestJS, or any modern stack—you need to understand exactly what happens under the hood when thousands of requests hit your API simultaneously.

The Mental Model: One Server, Thousands of Requests

Let’s start with a simple question: Does your server create 10,000 copies of itself when 10,000 users hit it at once?

No. It doesn’t.

What actually happens is far more interesting—and more fragile.

Your server has limited resources: CPU cores, memory, network bandwidth, and database connections. When a flood of requests arrives, your server doesn’t magically scale up. Instead, it tries to juggle those requests using the tools and patterns you’ve (hopefully) built into your architecture.

In Node.js, for example, there’s only one main JavaScript thread—but that doesn’t mean it handles requests one at a time. It handles them concurrently, not in parallel.

Concurrency vs. Parallelism: The Core Distinction

This is where most developers get tripped up.

- Concurrency means multiple requests are in progress at the same time but not necessarily executing at the same time.

- Parallelism means multiple requests are actually executing at the same time, on different CPU cores or threads.

A common misconception about Node.js is that because it is single-threaded, high traffic will cause requests to pile up like cars stuck at a single toll booth.

In reality, Node.js is single-threaded but highly concurrent. It uses an event loop to delegate I/O-bound tasks (like database queries, file reads, or external API calls) to the OS or thread pool, then moves on to the next request without waiting.

So, when 10,000 users hit your “Buy Now” endpoint:

Each request enters the event loop.
If the request involves a database query, Node.js offloads that work and immediately starts handling the next request.
When the database responds, Node.js picks up where it left off and sends the response.

This is why Node.js can handle thousands of concurrent connections—even on a single thread.

But here’s the catch: if your code blocks the event loop, everything grinds to a halt.

Where Things Actually Break: The Bottlenecks

Under heavy load, your API doesn’t just fail for no reason—it fails because of bottlenecks. Here are the most common ones:

- Blocking the Event Loop - If your code does something CPU-heavy in JavaScript—like encrypting passwords synchronously, parsing huge JSON payloads, or running complex calculations—it blocks the event loop. While that one request is hogging the thread, all other requests wait. This is why you should never use fs.readFileSync or heavy crypto in production code.

- Database Connection Pool Exhaustion – Your database doesn’t have infinite connections. Most connection pools are configured to handle 10–100 concurrent connections. If 10,000 requests each try to open a new connection, your pool gets exhausted. Requests start queuing—or worse, failing with “too many connections” errors.

- Unindexed or Slow Queries – A single slow query can block hundreds of requests waiting on the same table. Under load, this becomes a cascade failure: one slow query → connection pool fills up → new requests timeout → users see errors.

- External API Calls Without Timeouts – If your “Buy Now” endpoint calls a payment gateway, inventory service, or shipping API—and those calls don’t have timeouts—your server can get stuck waiting for responses that never come. Multiply that by 10,000 requests, and you’ve got a server meltdown.

- Memory Pressure and Garbage Collection – Under heavy load, your server allocates more memory. If you’re not careful, you can trigger frequent garbage collection pauses, which block the event loop and spike latency.

The Hidden Threat: Race Conditions

One of the most dangerous—and subtle—problems that emerges under high concurrency is the race condition. This occurs when two or more requests try to modify the same data simultaneously, and the final result depends on the unpredictable order in which the operations complete.

Consider this classic e-commerce example:

Without proper safeguards, two users can both be told an item is in stock, both complete checkout, and both be charged—even though only one unit was available. This is a race condition in its purest form, and it’s exactly why you need the strategies we’ll cover next.

So, What Actually Happens When 10,000 Users Click “Buy Now”?

Let’s walk through the sequence step by step.

Step 1: Requests Hit the Load Balancer Your traffic doesn’t hit a single server—it hits a load balancer (like AWS ALB, NGINX, or Cloudflare). The load balancer distributes requests across multiple backend instances. If you don’t have a load balancer, all 10,000 requests hit one server. That server will likely crash.

Step 2: Each Request Enters the Event Loop On each backend instance (say, a Node.js server), requests enter the event loop. If your code is non-blocking, the server can handle thousands of concurrent requests per instance.

Step 3: Database Queries Are Executed Each request tries to:

Check inventory
Reserve the item
Process payment
Create an order record

If your database isn’t optimized (no indexes, no connection pooling, no read replicas), this is where things slow down—and where race conditions can wreak havoc.

Step 4: Responses Are Sent Responses don’t go out in the order the requests arrived. They go out as soon as each request completes. Some users get their order confirmation in 200ms. Others wait 10 seconds. A few get timeouts.

How to Design for 10,000 Concurrent Users

You don’t need to over-engineer for day one—but you do need to design for scale. Here’s how:

1. Use Connection Pooling

Configure your database client (like pg for PostgreSQL or mysql2 for MySQL) to use a connection pool. This reuses connections instead of creating new ones for every request.

2. Database-Level Locking

The most direct fix lives at the database layer, using row-level locks. A SELECT ... FOR UPDATE statement tells the database: “Lock this specific row until my transaction finishes—nobody else can read or write it until I’m done.”

Any other transaction trying to touch row 42 simply blocks until this one commits or rolls back. This guarantees correctness, but it introduces lock contention—under extreme concurrency, requests start queuing up waiting for locks, and latency climbs. For a single hyper-popular SKU, this can become a serious bottleneck even though the rest of your database is sitting idle.

An alternative is optimistic locking, which skips the lock entirely and instead checks a version number at write time:

3. Decoupling with Queues

Locking solves correctness at the cost of making requests wait synchronously. A more scalable pattern is to decouple the write from the request entirely using a message queue (Kafka, RabbitMQ, AWS SQS, Google Pub/Sub).

Instead of your API handler directly touching the database:

The incoming request is validated and dropped onto a queue as a message: { userId, productId, requestId }.

The API immediately responds with something like 202 Accepted — processing.

A pool of background workers consumes messages off the queue one at a time (or a few at a time) at a rate the database can actually sustain.

Each worker executes the actual stock-check-and-deduct logic inside a transaction.

The result (success/failure) gets pushed to the client via websocket, polling, or a notification.

This converts a spike of 10,000 simultaneous writes into a controlled, sequential stream that the database can process without falling over. The tradeoff is eventual consistency—there’s a small delay between “I clicked buy” and “the system confirms it,” which needs to be communicated clearly in the UI (Spinners) so it doesn’t feel broken.

But here’s the reality check: Would you really place all 10,000 requests into Kafka? Not necessarily. Because if you only have 100 units in stock, 99% of those requests are doomed to fail from the start. Dropping them into a queue only wastes worker capacity, memory, and network bandwidth.

That’s why large-scale flash-sale systems move inventory protection closer to the edge. They preload inventory into a fast in-memory store (like Redis) and use it as a first gate. If Redis says stock = 0, the request is rejected immediately with a polite "Out of Stock" message, never even touching the queue or the primary database. The queue becomes a pathway only for requests that actually have a fighting chance, keeping your workers lean and your database unscathed.
Add a Caching Layer

4. Add a Caching Layer

For read-heavy traffic—like thousands of users just checking if a product is in stock before deciding to buy—a cache (Redis, Memcached, or a CDN edge cache) intercepts most of that traffic before it ever reaches the database. Re-running the same read query 10,000 times a second against your primary database is pure waste.

In high-concurrency “Buy Now” scenarios, Redis can go further and act as the first gate. Many flash-sale systems preload the available inventory into Redis at the start of the sale. When a request arrives, the first thing the API does is try an atomic decrement:

DECR product:42:stock

If the value was still positive, the request is allowed to proceed (and later confirmed in the database). If Redis returns a value less than zero, the request is rejected immediately with an “Out of Stock” response. It never reaches Kafka, never reaches the database, and never wastes a connection. This is extremely fast and protects the rest of your system.

But… What if Redis crashes after decrementing the stock?

This is why Redis should never be your source of truth. It’s a traffic-shaping layer - an early filter that keeps the stampede from overwhelming the slower, more authoritative systems behind it, not the final authority. The database remains the single source of truth for inventory. If Redis goes down mid-sale, you lose your fast gate, but your database can still fall back on its own row-level locks and atomic updates to guarantee correctness.

However, The classic hard problem remains: cache invalidation. A stale cache can tell users an item is available when it just sold out. That’s why the Redis inventory numbers are usually treated as a temporary, short-lived view that is reconciled with the database on a short interval or after every successful write.

5. Use Atomic Operations Instead of Read-Then-Write

A lot of race conditions disappear entirely if you avoid the "read, then write" pattern altogether and push the arithmetic into the database itself:

This single statement is atomic. The database guarantees that the check and the decrement happen together. Suppose the last item has stock = 1 and two requests arrive at almost the same instant:

Request A’s UPDATE succeeds. Stock becomes 0.
Request B’s UPDATE finds stock > 0 is now false, so zero rows are updated. The request is rejected.

No overselling. Only one transaction can successfully claim the final unit.
That’s the pure inventory decrement.

But here’s where it gets messy. What if you decrement the stock successfully, but the payment gateway times out? Or the user's credit card declines? Or they close their browser mid-checkout?

Imagine this: Stock is 1. User A reserves it. Your atomic UPDATE sets stock to 0. Then the payment fails. Now the product is completely unavailable—even though nobody actually bought it. You've just locked away your last item for a failed transaction. That's a terrible customer experience.

Large e-commerce platforms solve this by separating reservation from purchase. Instead of permanently deducting stock at the start of checkout, inventory first moves into a temporary, time-bound reserved state. The stock stays reserved while the user completes payment, but it's not permanently gone yet.

Only after a successful payment confirmation does the reservation convert into a permanent sale. If the payment fails, or if the user abandons the cart and walks away, the reservation simply expires—say, after 5-10 minutes—and the inventory is atomically released back into the available pool for the next customer.

This two-phase approach adds a bit of complexity (you now need a background job to sweep expired reservations), but it prevents the heartbreaking scenario where a legitimate buyer is told "out of stock" because someone else's credit card just bounced. It turns your atomic operation from a blunt instrument into a surgical tool—and your users will notice the difference.

6. Idempotency Keys

Under load, clients retry. Networks flake, timeouts happen, users double-click. Without protection, this creates duplicate side effects—double charges, double stock deductions.

The standard fix is an idempotency key: a unique identifier generated client-side (often a UUID) and attached to the request. The server stores which idempotency keys it has already processed and, on seeing a repeat, returns the cached original response instead of re-executing the logic:

Stripe/Paystack’s API is the canonical real-world example of this pattern done well—it’s specifically designed so that retried payment requests never double-charge a customer, as long as the same idempotency key is reused.

7. Rate Limiting and Backpressure

Not every request deserves to reach your database at full speed. Rate limiting—using algorithms like token bucket or sliding window—caps how many requests per second a given user, IP, or API key can send, rejecting or delaying the rest with a 429 Too Many Requests response.

This isn’t just about abuse prevention—it’s about protecting your own infrastructure. Related to this is backpressure: a signal that flows backward through a system telling upstream components “slow down, I can’t keep up,” so instead of a slow database causing your API servers to pile up thousands of stalled connections and crash, the system degrades gracefully by shedding or delaying excess load.

No Single Solution Solves the Entire Problem

No single technique here solves the whole problem. Locking without queuing creates painful contention. Queuing without idempotency creates duplicate charges. Caching without invalidation lies to users. And none of this work if you haven’t addressed the underlying race conditions that concurrency exposes.

It’s the combination—each one solving a different failure mode—that lets a system survive a genuine 10,000-request stampede without corrupting data or falling over.

Conclusion: Why This Matters for You

As a backend developer, your job isn’t just to write code that works. It’s to write code that works under pressure.

When you understand what happens when 10,000 users hit your API, you stop thinking in terms of “my code” and start thinking in terms of systems. You ask:

What happens if this endpoint gets 100x more traffic?

Where are the bottlenecks?

How do I fail gracefully?

What metrics should I monitor?

This mindset shift is what makes you valuable in remote job markets, freelance gigs, and high-growth startups.

From Spaghetti to Structure: The Architecture Patterns Every Software Developer Should Know

Nsikan Patrick Adaowo — Mon, 27 Jul 2026 16:31:00 +0000

Ever inherited a codebase where changing one thing breaks five others?

That’s rarely a coding problem. It’s an architecture one.

When you first join a software team, code organization feels simple. You put database queries in one folder, business logic in another, and UI routes at the top. It feels clean and logical.

Then the product hits real-world scale.

Deadlines tighten. Business models pivot based on user behaviour. Features get tacked on hastily over frantic weekends. What started as an elegant codebase slowly evolves into a tangled, unpredictable web.
Adding a simple feature to your checkout flow unexpectedly breaks an analytics pipeline three modules away. You realize you haven’t built a resilient application—you’ve built a house of cards.

Most developers assume the fix is writing more utilities or refactoring syntax. But syntax doesn’t solve structural decay; architecture does.

Software architecture patterns aren’t academic exercises or trivia for senior engineering interviews. They are time-tested blueprints designed to manage complexity, preserve developer velocity, and protect systems from falling apart when requirements change.

Here’s what every developer should understand:

The Real Cost of Spaghetti

Spaghetti architecture doesn’t just make the code ugly. It makes the business slower. Features take longer. Bugs become more expensive. Good engineers start avoiding certain parts of the codebase. New hires take months instead of weeks to become productive. And eventually, someone suggests a full rewrite — which is usually just a more expensive way of making the same mistakes again.

Most of this pain comes from missing or poorly enforced boundaries. When the UI can talk directly to the database, when domain logic lives inside controllers, when services depend on concrete implementations instead of abstractions, the system becomes a ball of mud. Change anything and the mud shifts.

Architecture patterns are essentially agreements about where those boundaries should live and what is allowed to cross them.

Here is a definitive guide to the 10 core architectural patterns, broken down by how they actually function in production:

1. Layered (N-Tier) Architecture

The Standard Horizontal Separation

Layered architecture is the default structure of almost every traditional backend framework. It divides an application horizontally into stacked tiers—typically Presentation, Business Logic, and Data Access—where each layer only talks to the one directly below it.

- How it works in practice:
A user hits an endpoint, the Controller parses the request, hands it off to the Service layer to execute business rules, and the Service calls the Repository to write to the database.

- The Reality Check:
While easy to learn, as your app grows, adding a single feature (like a user preference toggle) requires touching every single layer. Over time, layers become “pass-through tax boundaries” where code just forwards data downward without adding value.

2. Hexagonal Architecture (Ports & Adapters)

Isolating Core Business Logic from External Tech

Hexagonal Architecture (also known as ports and adapters) flips the traditional hierarchy inside out. Instead of placing the database at the bottom, it places your core domain logic at the exact center. The core defines abstract Ports (interfaces for what it needs—like PaymentGateway or UserRepository), and external technologies implement those ports using Adapters.

- How it works in practice:
Your core ordering logic doesn’t care if payments go through Paystack or Stripe, or if data lands in PostgreSQL or MongoDB. It only talks to its internal Port contracts. In other words, your application should not depend on external things. External things should depend on your application.

- The Reality Check:
You can test your entire business logic in milliseconds without spinning up a database or mocking complex HTTP calls. The trade-off is writing extra interface boilerplate up front.

3. Onion Architecture

Concentric Rings of Dependency Control

Coined by Jeffrey Palermo, Onion Architecture builds on the same principle as Hexagonal, visualization-wise using concentric circles. Domain Entities sit at the very core, surrounded by Domain Services, then Application Services, with Infrastructure and UI residing on the outermost ring.

How it works in practice: The strict rule of Onion Architecture is that dependencies only point inward. Outer rings depend on inner rings, but inner rings never know anything about outer rings.

- The Reality Check:
It keeps your core domain pristine and framework-agnostic. However, engineers used to quick-and-dirty scripting might find navigating multiple concentric abstraction layers over-engineered for simple CRUD applications.

4. Clean Architecture

Uncle Bob’s Unified Structural Blueprint

Popularized by Robert C. Martin (”Uncle Bob”), Clean Architecture synthesizes Hexagonal and Onion principles into a single, standardized framework. It categorizes code into Entities (enterprise business rules), Use Cases (application business rules), Interface Adapters, and Frameworks/Drivers. The Dependency Rule is the key: source code dependencies can only point inward. Nothing in an inner circle can know about something in an outer circle.

- How it works in practice: Use Cases orchestrate the flow of data to and from Entities. Frameworks (like Next.js, NestJS, or Express) live in the outermost layer as disposable details.

- The Reality Check: It provides absolute clarity on where code belongs. The downside? It can lead to an explosion of files and mappings between DTOs (Data Transfer Objects) and Domain Entities for basic operations. Not every CRUD app needs full Clean Architecture ceremony. The value shows up when the business rules are complex and long-lived. If your domain logic is simple, a lighter approach often wins. The principle, however — protect the business rules from frameworks and delivery mechanisms — remains solid.

5. Vertical Slice Architecture

Feature-First Autonomy Over Layered Overhead

Instead of slicing the app horizontally by technical concern (Controllers, Services, Repositories), Vertical Slice Architecture cuts vertically by business feature or use case (e.g., CreateOrder, CancelSubscription).

- How it works in practice: Every feature slice is completely self-contained. It owns its endpoint, request handling, business logic, and database access.

- The Reality Check: It drastically reduces side-effect risks—modifying CreateOrder can never accidentally break CancelSubscription because they share no execution paths. It is arguably the most effective pattern for shipping products fast without technical debt.

6. Event-Driven Architecture (EDA)

Asynchronous Communication via Reactive Events

In an Event-Driven system, services don’t make direct, blocking calls to each other. Instead, when a state change occurs, a service emits an Event to a central broker (like Kafka or EventBridge). Other independent services subscribe to those events and react accordingly.

- How it works in practice: When a user checks out, the Order Service emits OrderPlaced. The Inventory Service listens and reserves stock; the Notification Service listens and emails a receipt; the Analytics Service logs the event.

- The Reality Check: It decouples services almost entirely, allowing systems to handle massive asynchronous traffic spikes. The catch? Debugging distributed event chains and handling eventual consistency can be difficult without robust observability. But for many domains, the flexibility is worth the effort.

7. CQRS (Command Query Responsibility Segregation)

Splitting Write Operations from Read Pipelines

CQRS fundamentally splits an application’s data operations into two distinct pathways: Commands (writes that alter state) and Queries (reads that fetch data).

- How it works in practice: The write side focuses heavily on business rules and transactional integrity (using a normalized database). The read side bypasses complex business logic entirely, reading pre-aggregated views from a fast search index or cache.

- The Reality Check: It solves extreme performance bottlenecks when read traffic dwarfs write traffic (e.g., social media feeds, e-commerce catalogs). However, running two database models introduces temporary data lag (eventual consistency).

8. Service-Oriented Architecture (SOA)

Enterprise-Wide Shared Business Capabilities

Predating modern microservices, SOA is an architectural style where an enterprise splits its core systems into distinct, reusable services that communicate over a centralized communication bus—historically an Enterprise Service Bus (ESB).

- How it works in practice: A centralized ESB handles message transformation, routing, and protocol conversion between large, enterprise-level services (like Billing, ERP, and CRM).

- The Reality Check: SOA allowed massive enterprises to integrate disparate legacy systems. However, the central ESB often turned into a heavy, monolithic bottleneck managed by a single team.

9. Microservices Architecture

Independently Deployable, Fine-Grained Services

Microservices take the core idea of service decomposition and decentralize it completely. The application is built as a suite of small, autonomous services, each owning its own business domain, repository, and deployment pipeline.

- How it works in practice: Instead of sharing a monolithic database, the User Service, Payment Service, and Catalog Service each run their own isolated databases and communicate over lightweight protocols (gRPC or REST).

- The Reality Check: Microservices enable large organizations to scale engineering teams independently. But for small teams, they trade simple code problems for complex distributed network, deployment, and tracing problems.

- The promise is attractive: independent deploy-ability, technology freedom, team autonomy, better scaling. But you trade a simple deployment problem for a distributed systems problem. Network latency, partial failures, eventual consistency, distributed transactions, observability, and operational complexity all showing up at the same time.

10. Serverless Architecture

Function-as-a-Service & Managed Infrastructure

Serverless shifts the entire burden of server management, scaling, and provisioning to cloud providers. You write stateless granular functions (like AWS Lambda) that execute purely in response to triggers or HTTP requests.

- How it works in practice: When an API route is called, the cloud provider spins up a lightweight execution environment, runs your function, returns the response, and immediately destroys or freezes the container.

- The Reality Check: You pay strictly for execution time down to the millisecond, and elasticity is virtually infinite out of the box. The main trade-offs are potential cold-start latencies and vendor lock-in.

So, What Actually Matters in Practice

- Boundaries beat cleverness: Clear ownership and limited knowledge between parts of the system matter more than any specific pattern name.

- Start simple, evolve deliberately: A modular monolith with good internal boundaries is often the best place to begin. Extract services or introduce events when the pain of not doing so becomes clear.

- Patterns are tools, not identities:
Saying “we do Clean Architecture” or “we are event-driven” is less useful than understanding the problems each pattern solves and the costs it introduces.

- Consistency of approach matters more than perfection: A codebase that applies one set of principles reasonably well is usually healthier than one that mixes five different architectural styles without clear rules.

- Architecture is a team sport: The best patterns fail if the team doesn’t understand or respect the boundaries. Documentation, code reviews, and shared language matter.

The Product Engineering Mindset: Architectural Balance

It’s easy to get seduced by the distributed power of CQRS, Event-Driven processing, and Serverless. But every architectural pattern introduces trade-offs:

- Eventual Consistency: Reads may lag behind writes by a few milliseconds.

- Operational Overhead: Managing message brokers, dead-letter queues, and schema migrations requires real infrastructure discipline.

A true product engineer doesn’t apply CQRS and Event-Driven systems everywhere. They isolate them to the specific 10% of their application that faces intense write contention or heavy async processing, while keeping the rest of the application simple.

Scale where it counts, simplify where you can, and keep the user experience at the center of every architectural choice; because architecture isn’t about finding the “best” pattern; it’s about choosing the right set of trade-offs for your current scale.

Your Code is a Reflection of Your Standards

Nsikan Patrick Adaowo — Mon, 20 Jul 2026 22:27:34 +0000

For a long time, I believed becoming a better developer was simply a matter of writing more code.
The formula seemed straightforward and mechanical: Learn a language. Build a project. Complete a course. Move on to the next framework. Repeat.

For a while, that high-velocity approach worked surprisingly well. Every new feature taught me something. Every bug forced me to dive into documentation files. Every tutorial introduced another technology that felt exciting.

But as I began transitioning deeper into product engineering, I noticed a strange paradox.
Although I was learning new tools constantly, I wasn't becoming dramatically better at solving real-world problems. I could spin up an application. I could create an API. I could design a relational database. Yet, whenever I looked at systems designed by experienced product engineers, their work felt fundamentally different.
Not because it was more complex. Actually, it was usually much simpler.

Their architecture was easier to reason about. Their projects had strategic restraint. Their decisions seemed completely intentional. Somehow, they weren't just writing software; they were designing an asset.

For months, I assumed this clarity came from sheer years on the job. Eventually, I realized something else was happening. The senior engineers I admired didn't just look at documentation or scroll through technical blog posts. They read books that forced them to think deeply about system dynamics and human context.

Right now, I am reading Clean Code by Robert C. Martin. It is a text many took for granted during the "vibe coding" boom, but in 2026, its principles have become an aggressive competitive advantage.

Before picking up this book, my primary goal as a developer was shortsighted: Make the program work.

If the application produced the correct output and the UI looked clean, I considered the task complete. I was focused on the "surface."
Clean Code forces you to look at the "subsurface."

Software rarely lives for a week or a month. In a startup environment, a product survives, evolves, and shifts over years. This means the code you ship today will be read, modified, and debugged far more often than it is written. Uncle Bob reminds us of a truth that every product engineer must internalize: Programming isn’t just communication with a compiler; it’s communication with people.

One specific concept that shifted my mindset was the philosophy behind naming. On the surface, variable naming sounds trivial. The computer doesn’t care if a variable is named t or total. They produce identical machine code.
But a product engineer doesn't build for the machine; they build for the team and the user. One variable forces future developers to guess; the other tells a story.

When you have to touch a codebase six months later to pivot a feature based on customer feedback, clear naming is the difference between an elegant iteration and a broken system.

Clean Code challenged my habits. Functions that stretched over hundreds of lines suddenly looked like architectural debt. Comments became a symptom of poor expression rather than a sign of good documentation. Complex conditional logic became something to simplify, not tolerate.

As a product engineer, I’m glued already. This book has permanently changed how I review my own work. I no longer just ask, "Does this run?" I now ask, "Will another developer understand the intent behind this system without needing a meeting?"

The tools and frameworks change every two months, but the fundamentals of building a sustainable system remain permanent. Clean Code isn't teaching you a tool; it’s training your judgment.