Software architecture · Level 2: Structure · Module 08 of 46

Finding the components

Components are the building blocks of an architecture: the named parts that hold the system's behaviour. Choosing them is one of the first and most consequential things an architect does, because every later decision (style, deployment, team ownership) is made in terms of components. The most common way to get them wrong is also the most natural: making one component per database table.

1. The idea

Organising a hospital. You could organise it by things: a department for beds, one for medicines, one for patient files. But no patient needs "beds"; they need emergency care, surgery, maternity. Each of those uses beds, medicines and files, and owns the process from arrival to discharge. Hospitals are organised by what they do for people, not by what they store. Good components are the same.

A component is a group of related code with a clear responsibility, usually a namespace or package (app.enrolment, app.catalogue). Its name says what it does. Together the components form the logical architecture (Module 01): the parts and how they relate, before any decision about how they're deployed.

Three ways to find them, and one trap

Approach	How it works	Good for
Workflow	Walk through the main business workflows step by step, and give each major step a component that owns it	Process-heavy systems: orders, claims, enrolment
Actor and action	List the actors (student, instructor, admin, the system itself) and every action each one takes; group related actions into components	Systems with several kinds of user
Event storming	A workshop: put every business event ("course published", "payment taken") on a wall in time order, then cluster them	Complex domains with many experts to involve
Entity trap (avoid)	One component per data entity: StudentManager, CourseManager, PaymentManager	Nothing: the components only wrap the database, and the real logic ends up scattered

Two structural rules help. First, components are leaf namespaces: app.enrolment.payment and app.enrolment.refunds are components, so app.enrolment itself should hold no code, only components (it names a subdomain). Code sitting directly in a parent namespace is a component nobody designed. Second, find components iteratively: identify a first set, assign the requirements to them, check each one's responsibilities and characteristics, then split or merge, and repeat.

Technical or domain partitioning

The top-level split of a codebase is itself an architecture decision. Technical partitioning splits by layer: presentation, business, persistence. Domain partitioning splits by business area: catalogue, enrolment, learning, each with its own layers inside. Domain partitioning keeps a business change inside one part and matches how teams and services are usually organised; technical partitioning keeps specialists together and suits small, simple systems.

2. How it works

The entity trap, and the workflow fix

An online course platform. Press Play to see where the rules for "enrol in a paid course" end up with entity components, and what happens when a second app needs the same workflow.

One change, two partitionings

Change request: "let students pay with gift cards at checkout". Watch who has to change.

3. Try it yourself

Actors and actions → components

Here are ten actions from the course platform. Assign each to the component you'd give it to, then check your design. The component cards below show what each one ends up responsible for.

4. Trade-offs

Coarse vs fine components

A few big components keep related code together but mix responsibilities; many small ones are focused but create lots of dependencies between them. Split a component when its parts change for different reasons or need different characteristics.

Domain vs technical partitioning

Domain partitioning keeps business changes local and maps cleanly onto teams and services. Technical partitioning makes cross-cutting technical changes (a new persistence framework) local, and suits small teams.

Workflow vs actor-action

Workflows find the process owners but can miss actions outside the main flows; actor-action is thorough but can produce a flat list without a clear owner of each process. Use one, then check with the other.

Getting it right vs getting started

The first set of components is always wrong somewhere. Treat it as a draft: assign requirements, see what doesn't fit, and refactor.

5. In real projects

The entity trap is everywhere because frameworks encourage it: generate a controller and a repository per table, and you have entity components before writing a line of business logic. The symptom is a "service" layer full of orchestration code that calls five managers, duplicated in every app that needs the workflow.

Conway's law says a system's structure ends up mirroring the communication structure of the organisation that builds it. If teams are organised by layer (a UI team, a backend team, a database team), every feature crosses three teams. Many organisations now organise teams around business domains first, so that the architecture they want is the one Conway's law produces.

Components come before services. Find the logical components first; whether they're deployed together or apart is a later decision (Level 3). Teams that skip this step and start with "the services" usually rediscover the entity trap at the network level: a Customer service, an Order service and a Product service with every workflow spread across all three.

Say it in the interview

Two-sentence answers

"How do you identify components?" I walk through the main workflows, or list actors and their actions, and group related behaviour into components that each own a process. Then I assign the requirements and refine iteratively.
"What's the entity trap?" Making one component per entity, like CustomerManager and OrderManager. They become thin wrappers over the database, and the real workflow logic scatters across their callers.
"Domain or technical partitioning?" Domain partitioning for most systems: a business change stays in one part and maps to one team. Technical partitioning for small, simple systems or when a team is organised by skill.

Red flags interviewers notice

Components named after tables: UserService, ProductService, OrderService, with no workflow owner.
Starting from "the microservices" before naming the components.
A "Manager" or "Helper" component that does a bit of everything.

6. Remember it

Memory hook: "Name components after verbs, not nouns"Enrolment, checkout, publishing: things the system does. Not Student, Course, Payment: things it stores.

How this hook works: what "verbs, not nouns" means

What the slogan means, phrase by phrase

"Verbs": A component owns a piece of behaviour or a process, so its name describes an activity.
"not nouns": A component named after an entity usually just stores it; the behaviour ends up somewhere else.

Why this picture fits: it's a quick test you can apply to any component list: if most names are nouns from the database schema, you're probably in the entity trap.

The story → the concept

The hospital	The software
Departments for beds, medicines, files	Entity components (the trap)
Emergency, surgery, maternity	Workflow components
Each department uses beds and files	Components use shared entities through clear interfaces

The trap it saves you from

A system where every workflow is reassembled, slightly differently, by every caller.

7. Common mistakes

The entity trapComponents that mirror the database. The business rules end up in controllers and apps, duplicated and drifting apart.

Code in parent namespacesClasses sitting in app.enrolment next to its sub-components are an undesigned component. Move them into a named leaf.

One giant "core" componentEverything important in one place: high cohesion in name only. Split it by workflow.

Freezing the first draftInitial components are guesses. Refine them as requirements are assigned and characteristics are analysed.

8. Design exercise (30 minutes)

Workflow pass (10 min). Pick a system you know. Write its three main workflows as steps, and name a component for each major step.
Actor pass (10 min). List every actor and their actions. Does every action land in one of your components? Which ones don't fit?
Trap check (10 min). Look at your system's real top-level namespaces. How many are nouns from the schema? Where does the logic for your main workflow actually live?

9. Self-check quiz

What is the entity trap?

The components hold no real behaviour, so workflow logic scatters across their callers.

How does the workflow approach find components?

Components own the steps of real processes.

With domain partitioning, how many parts change for "pay with gift cards at checkout"?

The change is about one business area, which owns its own layers.

Code sits directly in app.enrolment, next to app.enrolment.refunds. What's wrong?

Components are leaf namespaces; parents only group them.

What does Conway's law say?

Layer teams produce layered systems; domain teams produce domain parts.

10. Go deeper

Resource	Time	Why
Fundamentals of Software Architecture, 2nd edition (Richards and Ford)	book	Chapter 8 covers component identification, the entity trap and partitioning.
EventStorming (Alberto Brandolini)	browse	The workshop format for discovering events and components with domain experts.
Conway's Law (Martin Fowler)	10 min	Why architecture follows team structure, and the "inverse Conway manoeuvre".