What is the 'Highlighted Core' technique for distilling a domain model, and what problem does it solve when a team can't yet afford to physically restructure the codebase?

## What the technique produces The **Highlighted Core** is the lightest-weight of the core-domain distillation techniques. Instead of touching any source code, a team produces a supplementary artifact: - **most often, a diagram** of the existing domain model with the classes, aggregates, or concepts that constitute the core domain visually marked (bold outlines, a distinct color, an asterisk), accompanied by a short written explanation of why each marked element belongs to the core and how it relates to the surrounding, unmarked generic or supporting parts of the model; - **a short 'distillation document'**, which some teams instead maintain: a page that lists, in prose, which modules or classes carry the core domain logic and which are considered supporting scaffolding. Either way, the defining property is that the technique produces **knowledge, not structural change** — the code's package layout, class boundaries, and module dependencies are completely untouched. ## Why it exists This technique exists because the two heavier distillation techniques both require real refactoring effort and carry real risk: - **segregated core**, which physically separates core code from the rest; - **abstract core**, which extracts a small abstract layer. Moving code across module boundaries can break tests, ripple through consumers, and requires enough confidence in what actually is core to justify the churn. Early on, or in a codebase under active feature pressure, a team frequently knows roughly where the core value lives but doesn't yet have the shared, precise, validated understanding needed to safely reorganize the code around that boundary — and even if they did, they may not have the calendar space to do it safely right now. The Highlighted Core lets the team capture and communicate that emerging understanding immediately, cheaply, and reversibly, so that new team members, code reviewers, and planning discussions can orient around 'here's what's core' well before any refactor happens — or even in cases where no refactor is ever planned. ## The trade-off: durability versus cost The central trade-off is **durability versus cost**. | | Cost to produce | Enforcement | |---|---|---| | **Highlighted Core** | lives outside the code — in a wiki page, a diagram tool, a README section — so it costs almost nothing to produce and update compared to a code refactor | carries zero structural enforcement, for exactly that reason | | **Segregated Core** | by contrast, expensive to build | self-enforcing in a much stronger sense: putting core code in its own module or package with an explicit boundary makes accidental entanglement visible immediately, because it requires new imports or changes the dependency graph | Nothing stops a developer from adding a new class to the 'core' area of the model without updating the diagram, or from making the core noticeably more entangled with generic infrastructure over successive changes, because the highlighting exists only in a document that most day-to-day commits never touch. The Highlighted Core deliberately trades that enforcement away for speed and low risk. ## Failure modes 1. The dominant failure mode in production is exactly this **drift**: teams draw the highlighted-core diagram once, during a workshop or a big-picture design review, then never touch it again as the code evolves underneath it. Months later the diagram still shows the original core aggregates, but some of them have since absorbed generic cross-cutting concerns — audit logging, notification triggers, permission checks — that make them behave like ordinary application glue rather than a focused, high-value model. Anyone who trusts the stale diagram over the actual code makes bad prioritization and staffing calls. 2. A second failure mode is **drawing the highlighting too coarsely** — marking entire packages or modules as 'core' without saying which specific classes or responsibilities inside them are the actual differentiator — which gives reviewers no more guidance than the unmarked model did, defeating the point of the exercise. 3. A third is using it as a **permanent substitute for a segregated core** when the core domain has clearly outgrown that arrangement: if the core is large, actively growing, and repeatedly getting entangled with generic subdomains despite the highlighting, that's a signal the team needs to invest in the heavier, code-level separation rather than keep re-drawing the same diagram. ## A concrete scenario A concrete scenario: a small SaaS team building an expense-approval product has, over a year, accreted a single 'expenses' module containing both the actual **approval-routing rule engine** — who must approve what, under which delegation-of-authority policy, the genuine differentiator — and a mass of generic CRUD for expense line items, receipt uploads, and currency conversion. Rather than immediately splitting the module, risky mid-quarter with a release imminent, the tech lead produces a one-page diagram highlighting the rule-engine classes and annotating why they matter, and shares it with the team. New hires now know within their first week which handful of classes deserve careful review and which are safe to touch casually, without a single line of code having moved.