Thoughtful Class Placement, Tidier Architecture
The setup: a class that fits two homes
Some architecture decisions are tiny in code and large in consequence. This one was two lines long.
For context, imagine a layered application: around 300 modules spread over roughly five layers. Two of them matter here. Workspace lives in the lower Platform layer, which holds shared infrastructure and is allowed to use networking types directly. Workspace holds knowledge about the surrounding environment, including a class called Configuration, and already contains some networking types. App lives in the Application layer, above it, and wires the product together at startup.
While improving the architecture of the application, we came across a class, ConfigurationAwareProxy. It decides how outgoing web requests are proxied, based on the application’s configuration. It uses a few classes from Workspace (Configuration among them) and nothing from App. App creates one instance and registers it as the default proxy of the HTTP client: one line to instantiate it, one line to register it.
So where does the class belong, in Workspace or in App? Both options compile and both respect the layering rules, so this is not a question of what is allowed. It is a question of design quality. Here is how to work through the decision, in three easy steps :-)
Step 1: separate the facts from the habits
The first move is to write down what is actually true, before anyone argues for a placement.
-
ConfigurationAwareProxydepends only on Workspace classes. It has no dependency on App. - App is its only consumer today, with two lines of usage.
- App sits above Workspace, so the dependency direction is legal in either placement.
- Workspace already contains networking types and may use HTTP directly, so a proxy class would not introduce a new kind of dependency there.
- Setting the default proxy of the HTTP client is a process-wide side effect. It is wiring, not logic.
That last point already splits the problem in two. The class (how proxy behavior is derived from configuration) and the registration (installing it globally at startup) are different things with different natural homes. The registration clearly belongs in App, which is where the application is assembled. The open question is only about the class.
The tempting argument is “App uses it, so it goes in App.” We will see why that is the weakest argument on the table.
Option A: put it in Workspace
The case for Workspace is that the class belongs with everything it already talks to.
Pros
- Cohesion. The class changes for the same reasons as the Workspace classes it uses: how configuration is stored, how the environment is described. Things that change together should live together.
- No new cross-module edge. All its dependencies stay inside one module. In App, it would add a dependency from the class to Workspace for no reason except location.
- Reuse without the heavy dependency. Any other module above Workspace could use it without depending on App, a large, volatile, top-layer module. With around 300 modules, a second consumer is more likely than it looks today.
- A thinner App. App should mostly assemble things. Keeping real logic out of it limits its size and its churn.
- Easier tests. The class can be tested next to its collaborators, without bringing in App.
- Stable direction. Lower layers should be the more stable ones. Proxy resolution from configuration is slow-moving logic, which suits a lower layer.
Cons
- A bigger lower module. Everything added to a lower module widens its blast radius: more dependents to rebuild and retest when it changes.
- Speculative generality. If App stays the only consumer forever, the extra visibility and care buys nothing.
- A public commitment. Once it sits in a shared module, other teams may depend on its behavior, which makes later changes harder.
Option B: put it in App
The case for App is that the class sits next to its only caller and nowhere else is affected.
Pros
- Locality. The class and its single usage are in the same module. It is easy to find and easy to change.
- Minimal blast radius. Workspace does not grow, and none of its dependents are touched.
- Cheap to move later. If a second consumer appears, moving the class down one layer is a small refactoring. Waiting for evidence is a legitimate YAGNI argument.
- A fit for product-specific policy. If the proxy behavior encodes a product decision rather than a generic environment capability, App is where product decisions belong.
Cons
- Weak cohesion. The class would use nothing from App and many things from Workspace. A class whose collaborators are all elsewhere is a classic sign of misplacement.
- Reuse is blocked. Modules below App cannot depend upward on it, so a second consumer must either move the class later or copy it.
- App bloat. Infrastructure logic accumulates in the composition layer, which blurs its role.
- Mixed concerns. How the HTTP stack is configured (wiring) gets tangled with how proxy behavior is derived (logic).
Step 2: score both options against the principles
Most of the pros and cons above are instances of a handful of well-known design principles. Naming them turns a debate of opinions into an analysis.
| Principle | What it asks | Favors |
|---|---|---|
| Cohesion / Common Closure | Classes that change together live together | Workspace |
| Common Reuse | Don’t force consumers to depend on things they don’t need | Workspace |
| Stable Dependencies | Depend in the direction of stability; lower layers are more stable | Workspace |
| Single responsibility of the composition root | App assembles; it doesn’t implement | Workspace |
| Layering / dependency direction | Higher layers depend on lower ones, never the reverse | Neutral (both are legal) |
| Minimal blast radius / YAGNI | Don’t widen shared modules without evidence | App |
A useful rule of thumb comes out of this table: place a class in the lowest layer that can legally contain it, and where it changes, not where it is called from. Usage count is a fact about today’s callers. Placement is a decision about tomorrow’s changes.
The global side effect deserves its own mention. Registering the proxy as the HTTP client’s default is process-wide state, so it belongs in the composition root. That is App in both options. Moving the class does not move the wiring.
The decision: the class goes in Workspace, the wiring stays in App
ConfigurationAwareProxy belongs in Workspace. Four of the six principles point there, one is neutral, one favors App, and the only argument for App is that the class is called from there.
Concretely:
- Move
ConfigurationAwareProxyinto Workspace, next toConfigurationand the other classes it uses. - Leave the two lines in App: create the instance, then set it as the HTTP client’s default proxy.
- Keep the class’s public surface small. Expose what App needs and nothing more, so the “public commitment” risk stays low.
The argument that decides it is simple. Every collaborator of the class is already in Workspace and none is in App. If the class lived in App, the code would be telling the next reader that it is an App concern, when in fact it is a Workspace concern that App happens to trigger.
Step 3: check what could flip the decision
A good recommendation says what would change it. Three questions are worth answering before you commit:
- Is the behavior environment logic or product policy? If the class encodes a product decision, such as which setting overrides which for this application, it belongs in App. If it only translates configuration into proxy behavior, it belongs in Workspace.
- Is a second consumer plausible? Another host, a command-line tool, a background service or a test harness would each be a reason to go down a layer. A realistic second consumer settles the question for Workspace.
- Is there a better home than either? If a lower-layer module about networking or HTTP infrastructure already exists, the class may fit there even better than in Workspace. Workspace was only the better of the two options on the table.
If these answers point away from Workspace, App is a perfectly defensible pragmatic choice. In that case, record the reason and move the class down as soon as a second consumer shows up.
Habits to reuse
Placement decisions are cheap to make and expensive to live with, so they deserve a few minutes of structured thought. Three habits are worth keeping for the next decision.
- Look at the dependencies, not the call sites. The question “who uses it?” is weak. The question “what does it depend on, and what changes with it?” is strong.
- Split logic from wiring. The class and its registration are separate decisions. The composition root owns the wiring, and the rest lives where it is most cohesive.
- State what would change your mind. A decision with named conditions is easy to revisit. A decision made on habit is easy to defend and hard to fix.
Small decisions like this one, placing a class where it truly belongs, keep the architecture tidy by preventing needless connections between the system’s components.
Enjoy Reading This Article?
Here are some more articles you might like to read next: