Your Nouns Are Not Your Architecture

A common way to design an application is to begin with its nouns:

User
Product
Order
Payment

Then each noun receives the standard architectural starter pack:

UserController
UserService
UserRepository

The controller receives users, the service services them, and the repository stores them somewhere responsible.

This is noun-oriented architecture: treating every important thing in the domain as if it were automatically a useful software boundary.

It works for simple CRUD systems. Unfortunately, most applications eventually do something.

The noun becomes a drawer

Consider a typical UserService:

register()
findByEmail()
resetPassword()
changeAddress()
disableAccount()
mergeAccounts()
assignRole()
calculateDiscount()

These operations all involve a user.

That is approximately where their similarity ends.

They have different rules, dependencies, side effects, security concerns, owners, and reasons to change. They live together because User was the nearest available noun when the folders were created.

As more behaviour accumulates, UserService becomes the official location for anything vaguely user-shaped.

Other components depend on it. It gradually depends on authentication, email, permissions, billing, auditing, and several services added during incidents nobody wishes to revisit.

The noun becomes both a dependency of everything and a consumer of everything.

The folder remains impressively tidy.

Name the capability, not the material

A better starting question is not:

What things exist in this system?

It is:

What must this system be capable of doing?

That leads to components such as:

UserRegistrar
PasswordResetter
AccountMerger
OrderPlacer
PaymentRefunder
SubscriptionCanceller

These are agentive names. They name the component responsible for performing a capability.

Compare:

UserService

with:

PasswordResetter

UserService tells us which noun is nearby.

PasswordResetter tells us what the component is for.

That difference produces better architectural questions:

• What rules does the PasswordResetter enforce?
• What information does it need?
• What effects does it produce?
• Which dependencies are legitimate?
• What does it own?
• Could it be replaced independently?

The distinction between noun-oriented architecture and capability-oriented architecture is one I use in this article. I am not aware of either term being established terminology, but they provide a useful way to describe the difference.

There is no required folder structure, framework, or certification. It is mostly the refusal to treat nouns as boundaries without evidence.

Capabilities can be composed

Large capabilities are often compositions of smaller capabilities.

An OrderPlacer may coordinate:

CartValidator
PriceCalculator
InventoryReserver
PaymentCollector
ShipmentCreator
ConfirmationSender

Each component owns a distinct responsibility. The OrderPlacer owns the sequence and decisions connecting them.

Likewise, a UserResolver might coordinate:

ExternalIdentityFinder
EmailUserFinder
UserCreator
IdentityOwnershipMigrator

The resolver checks an external identity, falls back to email, creates a user when necessary, and repairs ownership when identities have changed.

The composition is itself a capability.

This is different from putting the whole process inside:

UserService.findOrCreate()

where four responsibilities share one method because they appeared in the same ticket.

Explicit composition makes each capability nameable, testable, replaceable, and reusable. It also makes orchestration visible instead of hiding it halfway through a general-purpose service.

This does not mean mechanically creating one class for every verb.

Several operations may belong together when they share rules, ownership, dependencies, and reasons to change. The goal is deliberate cohesion, not an infestation of -er suffixes.

Capabilities do not need a full stack

This is the most common mistake when moving away from noun-oriented code.

The original structure looks like this:

OrderController
    ↓
OrderService
    ↓
OrderRepository

Someone then introduces capabilities:

OrderCancellationController
    ↓
OrderCanceller
    ↓
OrderCancellationRepository

Nothing meaningful has changed.

The same three-storey building has received a more specific sign.

A capability should occupy only the layers it actually needs.

A straightforward database read may live entirely in a repository:

OrderFinder

A business operation may live in an application component and use an existing persistence adapter:

OrderCanceller
    ↓
Orders

An HTTP-specific concern may remain entirely in a controller:

PaginationParser

There is no architectural prize for passing through three classes.

Controllers still handle HTTP. Repositories still adapt persistence. These are useful technical roles at the edges of the system.

They are not capabilities, and they do not describe what the application exists to do.

At the edges, name the mechanism.

At the core, name the actor responsible for the decision, operation, policy, or effect.

Agentive names should remain honest

Agentive naming is useful only when the name describes a real responsibility.

Good names include:

OrderPlacer
RefundIssuer
CartValidator
PriceCalculator
InventoryReserver

Less useful names include:

OrderManager
UserProcessor
PaymentHandler
AccountHelper

Those are technically agentive, but semantically unemployed.

A good name should allow someone to predict why the component exists and what probably does not belong inside it.

RefundIssuer should issue refunds.

It should not also produce invoices, calculate loyalty points, synchronize customer profiles, and retrieve every payment ever made merely because refunds involve payments.

Otherwise it is just PaymentService wearing a narrower hat.

Extractability exposes false boundaries

A useful test is whether a capability could be understood, tested, replaced, or moved without dragging half the application behind it.

It does not need to become a microservice. Extraction is only a diagnostic.

Suppose SubscriptionCanceller requires:

UserService
PaymentService
PlanService
NotificationService

and unrestricted access to their tables.

That component may have an excellent name, but it is not an isolated capability. Its apparent boundary disappears as soon as we inspect its dependencies.

A healthier version might depend on narrower collaborators:

SubscriptionCanceller
├── ActiveSubscriptionFinder
├── CancellationPolicy
├── RecurringPaymentStopper
└── CancellationNotifier

Those dependencies describe what cancellation actually requires.

The component can now be understood without importing the entire conceptual contents of users, payments, plans, and notifications.

That is extractability: not necessarily moving the code, but being able to see where it ends.

Nouns still matter

This is not an argument against entities, models, aggregates, or nouns.

Software contains things. Those things need names.

The mistake is assuming that because User, Order, or Payment is important, every behaviour involving it belongs inside one architectural box.

Nouns describe the material the system works with.

Capabilities describe the work.

Agentive names give that work an owner.

Architecture begins when we stop confusing the three.