We ship lots of code that “works,” yet every release feels like walking on eggshells. Open your repo: the top folder screams Rails or Spring/Hibernate, not Claims, Billing, or Inventory. Tests boot web servers, controllers know too much, and a minor library upgrade ripples through half the system. This is the real problem: we’ve let delivery details (web, DB, framework) dominate the design. The result is accidental complexity, slow feedback, and growing maintenance spend disguised as “business as usual.”
Here’s the lesson from Screaming Architecture from Uncle Bob: architecture must scream the use cases of the business, not the framework. Treat frameworks as replaceable tools, not organizing principles. The web is a delivery mechanism, not your architecture. Keep the core model and use-case orchestration independent of the UI, DB, and messaging so you can test them without a browser, a servlet container, or a database. When the heart of the system is just plain code coordinated by use-case objects, change becomes cheap: you can refactor behaviors, switch frameworks, or add a new interface (CLI, API, batch) without surgery on the domain.
Action time: what a Staff Engineer does to turn this into an operating reality. Start by renaming top-level packages to business capabilities (Orders, Payments, Catalog), not technical layers. Model use cases explicitly (interactors/services) that depend only on the domain. Wrap the edges with Hexagonal (Ports & Adapters): inbound ports for commands/queries; outbound ports for persistence, messaging, and external services. Establish the rule “no framework imports in core”; all frameworks live behind adapters. Add an anti-corruption layer when speaking to legacy systems. Enforce boundaries with architecture tests (ArchUnit/Deptrac), a no-framework-in-core CI gate, and contract tests that validate adapters without touching the core. Provide a paved road (templates and starter modules), so teams don’t reinvent the wheel. Use ADRs to record why a framework is chosen and how it’s isolated. Run “screaming reviews” each sprint: does the structure still tell a newcomer what business we’re in?
Strategic impact: your codebase reads like the company’s language; onboarding accelerates because intent is obvious; test cycles shrink because core logic runs in-memory; and technology choices become reversible decisions, not one-way doors. Maintenance costs decline as coupling to delivery details shrinks, while throughput rises because features change in the domain, not in glue code. Tomorrow morning, pick one painful use case, extract its interactor, add a database port, and make the tests green without a server. Let your architecture finally scream what you actually sell.