/*@jsxRuntime automatic @jsxImportSource react*/ const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0]; const {useMDXComponents: _provideComponents} = arguments[0]; function _createMdxContent(props) { const _components = Object.assign({ p: "p", em: "em", hr: "hr", h2: "h2", a: "a", span: "span", pre: "pre", code: "code", strong: "strong", ul: "ul", li: "li", table: "table", thead: "thead", tr: "tr", th: "th", tbody: "tbody", td: "td", ol: "ol", h3: "h3", h4: "h4" }, _provideComponents(), props.components); return _jsxs(_Fragment, { children: [_jsxs(_components.p, { children: ["I've been writing code with hygiene and type safety in mind for a while now (or at least trying to). Every function gets explicit return types (even in languages where it's not required), objects get validated, repository methods get tested. But I've noticed I'm not quite strict enough about the ", _jsx(_components.em, { children: "other" }), " boundaries."] }), "\n", _jsxs(_components.p, { children: ["Principles of ", _jsx(_components.em, { children: "modularity" }), " (e.g., in the 'lego blocks' or 'IKEA furniture' sense) and ", _jsx(_components.em, { children: "abstraction" }), " always came more naturally to me, but for whatever reason the principles of clean ", _jsx(_components.em, { children: "encapsulation" }), " and ", _jsx(_components.em, { children: "inheritance" }), " (other pillars of Object-Oriented Programming) and their boundaries were less intuitive to me, so I find I have to pause and reflect a bit more about them to ensure they are well defined and enforced."] }), "\n", _jsx(_components.hr, {}), "\n", _jsxs(_components.h2, { id: "scope-creep", children: [_jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#scope-creep", children: _jsx(_components.span, { className: "icon icon-link" }) }), "Scope creep"] }), "\n", _jsxs(_components.p, { children: ["Recently, after a flurry of new code/features being pushed, I did my customary practice of reflecting on what went well and what could be improved. So I decided to revisit the ", _jsx(_components.a, { href: "https://amzn.to/3LryYC9", children: "book Clean Architecture" }), " for a fresh look/reflection... and ", _jsx(_components.em, { children: "oh my god I just realized that the author, Robert Martin, is \"Uncle Bob\"!" }), " (the humorous Twitter sensation I've been watching for years, but never put two-and-two together). He has a ", _jsx(_components.a, { href: "https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html", children: "great blog" }), ", too."] }), "\n", _jsx(_components.p, { children: "Mostly I knew where the trouble spots were even before I revisited Clean Architecture. I was growing rather concerned with the growth of the controllers, repositories, services, and router files, and knew their boundaries weren't clean/clear enough." }), "\n", _jsx(_components.p, { children: "Note: I'll show some examples below from my own Java + Spring Boot repo... but most of the ideas I've written here, Java examples aside, are agnostic and repo/framework/language-independent." }), "\n", _jsx(_components.pre, { className: "language-java", children: _jsxs(_components.code, { className: "language-java", children: [_jsx(_components.span, { className: "token comment", children: "// In PeopleV1Controller - boundary violation example" }), "\n", _jsx(_components.span, { className: "token annotation punctuation", children: "@PutMapping" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token string", children: "\"/detail\"" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), "\n", _jsx(_components.span, { className: "token keyword", children: "public" }), " ", _jsx(_components.span, { className: "token class-name", children: "ResponseEntity" }), _jsxs(_components.span, { className: "token generics", children: [_jsx(_components.span, { className: "token punctuation", children: "<" }), _jsx(_components.span, { className: "token class-name", children: "Map" }), _jsx(_components.span, { className: "token punctuation", children: "<" }), _jsx(_components.span, { className: "token class-name", children: "String" }), _jsx(_components.span, { className: "token punctuation", children: "," }), " ", _jsx(_components.span, { className: "token class-name", children: "Object" }), _jsx(_components.span, { className: "token punctuation", children: ">" }), _jsx(_components.span, { className: "token punctuation", children: ">" })] }), " ", _jsx(_components.span, { className: "token function", children: "updatePersonDetail" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "\n ", _jsx(_components.span, { className: "token annotation punctuation", children: "@RequestParam" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "required ", _jsx(_components.span, { className: "token operator", children: "=" }), " ", _jsx(_components.span, { className: "token boolean", children: "false" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), " ", _jsx(_components.span, { className: "token class-name", children: "String" }), " id", _jsx(_components.span, { className: "token punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "token annotation punctuation", children: "@RequestParam" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "required ", _jsx(_components.span, { className: "token operator", children: "=" }), " ", _jsx(_components.span, { className: "token boolean", children: "false" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), " ", _jsx(_components.span, { className: "token class-name", children: "String" }), " slug", _jsx(_components.span, { className: "token punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "token annotation punctuation", children: "@RequestBody" }), " ", _jsx(_components.span, { className: "token class-name", children: "Map" }), _jsxs(_components.span, { className: "token generics", children: [_jsx(_components.span, { className: "token punctuation", children: "<" }), _jsx(_components.span, { className: "token class-name", children: "String" }), _jsx(_components.span, { className: "token punctuation", children: "," }), " ", _jsx(_components.span, { className: "token class-name", children: "Object" }), _jsx(_components.span, { className: "token punctuation", children: ">" })] }), " body", _jsx(_components.span, { className: "token punctuation", children: ")" }), " ", _jsx(_components.span, { className: "token punctuation", children: "{" }), "\n\n ", _jsx(_components.span, { className: "token class-name", children: "String" }), " personId ", _jsx(_components.span, { className: "token operator", children: "=" }), " ", _jsx(_components.span, { className: "token function", children: "resolveIdOrThrow" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "id", _jsx(_components.span, { className: "token punctuation", children: "," }), " slug", _jsx(_components.span, { className: "token punctuation", children: "," }), " s ", _jsx(_components.span, { className: "token operator", children: "->" }), " personService", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "resolveIdBySlug" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "s", _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n ", _jsx(_components.span, { className: "token class-name", children: "String" }), " normalizedSlug ", _jsx(_components.span, { className: "token operator", children: "=" }), " ", _jsx(_components.span, { className: "token class-name", children: "RequestValidation" }), _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "normalizeOptionalSlug" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "body", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "get" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token string", children: "\"slug\"" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: "," }), " ", _jsx(_components.span, { className: "token string", children: "\"slug\"" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n ", _jsx(_components.span, { className: "token keyword", children: "if" }), " ", _jsx(_components.span, { className: "token punctuation", children: "(" }), "normalizedSlug ", _jsx(_components.span, { className: "token operator", children: "!=" }), " ", _jsx(_components.span, { className: "token keyword", children: "null" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), " ", _jsx(_components.span, { className: "token punctuation", children: "{" }), "\n body", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "put" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token string", children: "\"slug\"" }), _jsx(_components.span, { className: "token punctuation", children: "," }), " normalizedSlug", _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n ", _jsx(_components.span, { className: "token punctuation", children: "}" }), "\n ", _jsx(_components.span, { className: "token keyword", children: "var" }), " updated ", _jsx(_components.span, { className: "token operator", children: "=" }), " personService", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "update" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "personId", _jsx(_components.span, { className: "token punctuation", children: "," }), " body", _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n ", _jsx(_components.span, { className: "token keyword", children: "return" }), " ", _jsx(_components.span, { className: "token class-name", children: "ResponseEntity" }), _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "ok" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "updated", _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n", _jsx(_components.span, { className: "token punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.p, { children: "I think it would have been better to have put the identifier resolution and slug normalization in a use-case layer, not in the HTTP adapter." }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Potential improvements" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "resolveIdOrThrow()" }), " → belongs in a ", _jsx(_components.code, { children: "PersonIdentifierResolver" }), " use-case service"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "normalizeOptionalSlug()" }), " → belongs in a ", _jsx(_components.code, { children: "SlugNormalizationService" }), " domain service"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "body.put(\"slug\", ...)" }), " → should happen in the use-case layer, not the controller"] }), "\n", _jsx(_components.li, { children: "The controller should just be translating HTTP → command and return the response" }), "\n"] }), "\n", _jsx(_components.p, { children: "Another one:" }), "\n", _jsx(_components.pre, { className: "language-java", children: _jsxs(_components.code, { className: "language-java", children: [_jsx(_components.span, { className: "token comment", children: "// In PersonRepository - web concerns in a data layer" }), "\n", _jsx(_components.span, { className: "token keyword", children: "public" }), " ", _jsx(_components.span, { className: "token class-name", children: "String" }), " ", _jsx(_components.span, { className: "token function", children: "create" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token class-name", children: "Map" }), _jsxs(_components.span, { className: "token generics", children: [_jsx(_components.span, { className: "token punctuation", children: "<" }), _jsx(_components.span, { className: "token class-name", children: "String" }), _jsx(_components.span, { className: "token punctuation", children: "," }), " ", _jsx(_components.span, { className: "token class-name", children: "Object" }), _jsx(_components.span, { className: "token punctuation", children: ">" })] }), " request", _jsx(_components.span, { className: "token punctuation", children: ")" }), " ", _jsx(_components.span, { className: "token punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "token class-name", children: "String" }), " slug ", _jsx(_components.span, { className: "token operator", children: "=" }), " ", _jsx(_components.span, { className: "token class-name", children: "ControllerParameterUtils" }), _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "normalizeSlugStrict" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token function", children: "toStr" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "request", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "get" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token string", children: "\"slug\"" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n ", _jsx(_components.span, { className: "token keyword", children: "if" }), " ", _jsx(_components.span, { className: "token punctuation", children: "(" }), "slug ", _jsx(_components.span, { className: "token operator", children: "==" }), " ", _jsx(_components.span, { className: "token keyword", children: "null" }), " ", _jsx(_components.span, { className: "token operator", children: "||" }), " slug", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "isBlank" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), " ", _jsx(_components.span, { className: "token punctuation", children: "{" }), "\n slug ", _jsx(_components.span, { className: "token operator", children: "=" }), " ", _jsx(_components.span, { className: "token class-name", children: "SlugUtils" }), _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "slugify" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "first", _jsx(_components.span, { className: "token punctuation", children: "," }), " last", _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n ", _jsx(_components.span, { className: "token punctuation", children: "}" }), "\n ", _jsx(_components.span, { className: "token keyword", children: "if" }), " ", _jsx(_components.span, { className: "token punctuation", children: "(" }), "slug ", _jsx(_components.span, { className: "token operator", children: "==" }), " ", _jsx(_components.span, { className: "token keyword", children: "null" }), " ", _jsx(_components.span, { className: "token operator", children: "||" }), " slug", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "isBlank" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), " ", _jsx(_components.span, { className: "token punctuation", children: "{" }), "\n slug ", _jsx(_components.span, { className: "token operator", children: "=" }), " ", _jsx(_components.span, { className: "token class-name", children: "IdGenerator" }), _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "generate" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token number", children: "8" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "toLowerCase" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token class-name", children: "Locale" }), _jsx(_components.span, { className: "token punctuation", children: "." }), "ROOT", _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n ", _jsx(_components.span, { className: "token punctuation", children: "}" }), "\n slug ", _jsx(_components.span, { className: "token operator", children: "=" }), " ", _jsx(_components.span, { className: "token class-name", children: "SlugUtils" }), _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "ensureUniqueSlug" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "slug", _jsx(_components.span, { className: "token punctuation", children: "," }), " ", _jsx(_components.span, { className: "token keyword", children: "null" }), _jsx(_components.span, { className: "token punctuation", children: "," }), " ", _jsx(_components.span, { className: "token punctuation", children: "(" }), "candidate", _jsx(_components.span, { className: "token punctuation", children: "," }), " ignored", _jsx(_components.span, { className: "token punctuation", children: ")" }), " ", _jsx(_components.span, { className: "token operator", children: "->" }), " ", _jsx(_components.span, { className: "token function", children: "existsBySlug" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "candidate", _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n request", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "put" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token string", children: "\"slug\"" }), _jsx(_components.span, { className: "token punctuation", children: "," }), " slug", _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n ", _jsx(_components.span, { className: "token comment", children: "// ... JDBC insert follows" }), "\n", _jsx(_components.span, { className: "token punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Potential improvements" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "ControllerParameterUtils.normalizeSlugStrict()" }), " → should use a domain ", _jsx(_components.code, { children: "SlugNormalizer" }), " instead"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "SlugUtils.slugify()" }), " → belongs in a ", _jsx(_components.code, { children: "PersonNameSlugGenerator" }), " domain service"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "ensureUniqueSlug()" }), " → belongs in a ", _jsx(_components.code, { children: "UniqueSlugValidator" }), " use-case service"] }), "\n", _jsx(_components.li, { children: "The repository should only persist validated entities, not generate business rules" }), "\n"] }), "\n", _jsx(_components.p, { children: "Each shortcut created a new dependency direction. But, say, changing the email validation rules requires touching both the controller and the repository, plus every test that had come to depend on this specific behavior." }), "\n", _jsx(_components.p, { children: _jsx(_components.em, { children: "As mentioned, the 'elephant in the room' of a lot of these examples is that the controller, repository, and service layers are all doing too much. They should be focused on their primary responsibilities: things like translating HTTP requests to commands and returning responses, persisting data, and executing business logic." }) }), "\n", _jsx(_components.p, { children: "A model for cleaner boundaries in the highest risk areas I found having their definitions conflated:" }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Layer" }), _jsx(_components.th, { children: "Knows About" }), _jsx(_components.th, { children: "Doesn't Know About" }), _jsx(_components.th, { children: "Key Question" }), _jsx(_components.th, { children: "Example from aVenture.vc" })] }) }), _jsxs(_components.tbody, { children: [_jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.strong, { children: "Controller" }) }), _jsx(_components.td, { children: "HTTP, JSON, request/response" }), _jsx(_components.td, { children: "Business rules, database" }), _jsx(_components.td, { children: "\"What did the user request?\"" }), _jsxs(_components.td, { children: [_jsx(_components.code, { children: "PeopleV1Controller" }), " maps ", _jsx(_components.code, { children: "POST /api/people" }), " to ", _jsx(_components.code, { children: "CreatePersonCommand" })] })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.strong, { children: "Use Case" }) }), _jsx(_components.td, { children: "Business flow, transaction boundaries" }), _jsx(_components.td, { children: "HTTP, SQL specifics" }), _jsx(_components.td, { children: "\"What does this operation do?\"" }), _jsxs(_components.td, { children: [_jsx(_components.code, { children: "CreatePersonUseCase" }), " coordinates duplicate check, domain creation, persistence"] })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.strong, { children: "Domain Service" }) }), _jsx(_components.td, { children: "Business rules, domain logic" }), _jsx(_components.td, { children: "HTTP, persistence" }), _jsx(_components.td, { children: "\"Is this valid by business rules?\"" }), _jsxs(_components.td, { children: [_jsx(_components.code, { children: "DuplicateEmailChecker" }), " validates email uniqueness against business rules"] })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.strong, { children: "Repository" }) }), _jsx(_components.td, { children: "Persistence, queries" }), _jsx(_components.td, { children: "Business logic, HTTP" }), _jsx(_components.td, { children: "\"How do I store/retrieve this?\"" }), _jsxs(_components.td, { children: [_jsx(_components.code, { children: "PersonRepository" }), " saves/retrieves ", _jsx(_components.code, { children: "Person" }), " entities using JDBC/JPA"] })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.strong, { children: "Domain Entity" }) }), _jsx(_components.td, { children: "Its own invariants" }), _jsx(_components.td, { children: "Everything else" }), _jsx(_components.td, { children: "\"Am I in a valid state?\"" }), _jsxs(_components.td, { children: [_jsx(_components.code, { children: "Person" }), " enforces required name/email and valid email format"] })] })] })] }), "\n", _jsx(_components.p, { children: "Here are a few more examples of boundary violations I found:" }), "\n", _jsx(_components.pre, { className: "language-java", children: _jsxs(_components.code, { className: "language-java", children: [_jsx(_components.span, { className: "token comment", children: "// BaseDomainService.java - 200+ lines of abstractions" }), "\n", _jsx(_components.span, { className: "token keyword", children: "public" }), " ", _jsx(_components.span, { className: "token keyword", children: "abstract" }), " ", _jsx(_components.span, { className: "token keyword", children: "class" }), " ", _jsx(_components.span, { className: "token class-name", children: "BaseDomainService" }), _jsxs(_components.span, { className: "token generics", children: [_jsx(_components.span, { className: "token punctuation", children: "<" }), _jsx(_components.span, { className: "token class-name", children: "T" }), _jsx(_components.span, { className: "token punctuation", children: "," }), " ID", _jsx(_components.span, { className: "token punctuation", children: ">" })] }), " ", _jsx(_components.span, { className: "token keyword", children: "extends" }), " ", _jsx(_components.span, { className: "token class-name", children: "BaseListService" }), " ", _jsx(_components.span, { className: "token punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "token keyword", children: "protected" }), " ", _jsx(_components.span, { className: "token keyword", children: "final" }), " ", _jsx(_components.span, { className: "token class-name", children: "String" }), " domainName", _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n ", _jsx(_components.span, { className: "token keyword", children: "protected" }), " ", _jsx(_components.span, { className: "token keyword", children: "final" }), " ", _jsx(_components.span, { className: "token class-name", children: "BaseDomainRepository" }), _jsxs(_components.span, { className: "token generics", children: [_jsx(_components.span, { className: "token punctuation", children: "<" }), _jsx(_components.span, { className: "token class-name", children: "T" }), _jsx(_components.span, { className: "token punctuation", children: "," }), " ID", _jsx(_components.span, { className: "token punctuation", children: ">" })] }), " baseRepository", _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n\n ", _jsx(_components.span, { className: "token comment", children: "// Now includes: caching, circuit breakers, generic CRUD," }), "\n ", _jsx(_components.span, { className: "token comment", children: "// domain column mappings, string column handling, etc." }), "\n ", _jsx(_components.span, { className: "token annotation punctuation", children: "@Cacheable" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token string", children: "\"domain:list\"" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), "\n ", _jsx(_components.span, { className: "token annotation punctuation", children: "@CircuitBreaker" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "name ", _jsx(_components.span, { className: "token operator", children: "=" }), " ", _jsx(_components.span, { className: "token string", children: "\"domain-operations\"" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), "\n ", _jsx(_components.span, { className: "token keyword", children: "public" }), " ", _jsx(_components.span, { className: "token class-name", children: "List" }), _jsxs(_components.span, { className: "token generics", children: [_jsx(_components.span, { className: "token punctuation", children: "<" }), _jsx(_components.span, { className: "token class-name", children: "T" }), _jsx(_components.span, { className: "token punctuation", children: ">" })] }), " ", _jsx(_components.span, { className: "token function", children: "findPage" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsxs(_components.span, { className: "token class-name", children: ["FilterParams", _jsx(_components.span, { className: "token punctuation", children: "." }), "Where"] }), " where", _jsx(_components.span, { className: "token punctuation", children: "," }), " ", _jsx(_components.span, { className: "token class-name", children: "String" }), " order", _jsx(_components.span, { className: "token punctuation", children: "," }), " ", _jsx(_components.span, { className: "token class-name", children: "String" }), " direction", _jsx(_components.span, { className: "token punctuation", children: "," }), " ", _jsx(_components.span, { className: "token keyword", children: "int" }), " limit", _jsx(_components.span, { className: "token punctuation", children: "," }), " ", _jsx(_components.span, { className: "token keyword", children: "int" }), " offset", _jsx(_components.span, { className: "token punctuation", children: ")" }), " ", _jsx(_components.span, { className: "token punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "token keyword", children: "return" }), " baseRepository", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "findPage" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "where", _jsx(_components.span, { className: "token punctuation", children: "," }), " order", _jsx(_components.span, { className: "token punctuation", children: "," }), " direction", _jsx(_components.span, { className: "token punctuation", children: "," }), " limit", _jsx(_components.span, { className: "token punctuation", children: "," }), " offset", _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n ", _jsx(_components.span, { className: "token punctuation", children: "}" }), "\n\n ", _jsx(_components.span, { className: "token comment", children: "// Plus more \"convenience\" methods..." }), "\n", _jsx(_components.span, { className: "token punctuation", children: "}" }), "\n"] }) }), "\n", _jsxs(_components.p, { children: ["The problem shows up when I need to create a ", _jsx(_components.code, { children: "PersonService" }), " that doesn't need caching but does need custom validation. I end up with:"] }), "\n", _jsx(_components.pre, { className: "language-java", children: _jsxs(_components.code, { className: "language-java", children: [_jsx(_components.span, { className: "token annotation punctuation", children: "@Service" }), "\n", _jsx(_components.span, { className: "token keyword", children: "public" }), " ", _jsx(_components.span, { className: "token keyword", children: "class" }), " ", _jsx(_components.span, { className: "token class-name", children: "PersonService" }), " ", _jsx(_components.span, { className: "token keyword", children: "extends" }), " ", _jsx(_components.span, { className: "token class-name", children: "BaseDomainService" }), _jsxs(_components.span, { className: "token generics", children: [_jsx(_components.span, { className: "token punctuation", children: "<" }), _jsx(_components.span, { className: "token class-name", children: "PersonDTO" }), _jsx(_components.span, { className: "token punctuation", children: "," }), " ", _jsx(_components.span, { className: "token class-name", children: "String" }), _jsx(_components.span, { className: "token punctuation", children: ">" })] }), " ", _jsx(_components.span, { className: "token punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "token comment", children: "// Inherits 200+ lines I don't need" }), "\n ", _jsx(_components.span, { className: "token comment", children: "// But still need to override half the methods" }), "\n ", _jsx(_components.span, { className: "token comment", children: "// And now debugging requires understanding the entire hierarchy" }), "\n", _jsx(_components.span, { className: "token punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.p, { children: "Or here:" }), "\n", _jsx(_components.pre, { className: "language-java", children: _jsxs(_components.code, { className: "language-java", children: [_jsx(_components.span, { className: "token comment", children: "// Controller layer" }), "\n", _jsx(_components.span, { className: "token annotation punctuation", children: "@PutMapping" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token string", children: "\"/detail\"" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), "\n", _jsx(_components.span, { className: "token keyword", children: "public" }), " ", _jsx(_components.span, { className: "token class-name", children: "ResponseEntity" }), _jsxs(_components.span, { className: "token generics", children: [_jsx(_components.span, { className: "token punctuation", children: "<" }), _jsx(_components.span, { className: "token class-name", children: "Map" }), _jsx(_components.span, { className: "token punctuation", children: "<" }), _jsx(_components.span, { className: "token class-name", children: "String" }), _jsx(_components.span, { className: "token punctuation", children: "," }), " ", _jsx(_components.span, { className: "token class-name", children: "Object" }), _jsx(_components.span, { className: "token punctuation", children: ">" }), _jsx(_components.span, { className: "token punctuation", children: ">" })] }), " ", _jsx(_components.span, { className: "token function", children: "updatePersonDetail" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "\n ", _jsx(_components.span, { className: "token annotation punctuation", children: "@RequestBody" }), " ", _jsx(_components.span, { className: "token class-name", children: "Map" }), _jsxs(_components.span, { className: "token generics", children: [_jsx(_components.span, { className: "token punctuation", children: "<" }), _jsx(_components.span, { className: "token class-name", children: "String" }), _jsx(_components.span, { className: "token punctuation", children: "," }), " ", _jsx(_components.span, { className: "token class-name", children: "Object" }), _jsx(_components.span, { className: "token punctuation", children: ">" })] }), " body", _jsx(_components.span, { className: "token punctuation", children: ")" }), " ", _jsx(_components.span, { className: "token comment", children: "// Untyped Map" }), "\n\n", _jsx(_components.span, { className: "token comment", children: "// Service layer - accepts Map" }), "\n", _jsx(_components.span, { className: "token keyword", children: "public" }), " ", _jsx(_components.span, { className: "token class-name", children: "PersonDTO" }), " ", _jsx(_components.span, { className: "token function", children: "update" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token class-name", children: "String" }), " id", _jsx(_components.span, { className: "token punctuation", children: "," }), " ", _jsx(_components.span, { className: "token class-name", children: "Map" }), _jsxs(_components.span, { className: "token generics", children: [_jsx(_components.span, { className: "token punctuation", children: "<" }), _jsx(_components.span, { className: "token class-name", children: "String" }), _jsx(_components.span, { className: "token punctuation", children: "," }), " ", _jsx(_components.span, { className: "token class-name", children: "Object" }), _jsx(_components.span, { className: "token punctuation", children: ">" })] }), " request", _jsx(_components.span, { className: "token punctuation", children: ")" }), " ", _jsx(_components.span, { className: "token punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "token keyword", children: "int" }), " rows ", _jsx(_components.span, { className: "token operator", children: "=" }), " personRepository", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "update" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "id", _jsx(_components.span, { className: "token punctuation", children: "," }), " request", _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n\n", _jsx(_components.span, { className: "token comment", children: "// Repository layer - still Map-based" }), "\n", _jsx(_components.span, { className: "token keyword", children: "public" }), " ", _jsx(_components.span, { className: "token keyword", children: "int" }), " ", _jsx(_components.span, { className: "token function", children: "update" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token class-name", children: "String" }), " id", _jsx(_components.span, { className: "token punctuation", children: "," }), " ", _jsx(_components.span, { className: "token class-name", children: "Map" }), _jsxs(_components.span, { className: "token generics", children: [_jsx(_components.span, { className: "token punctuation", children: "<" }), _jsx(_components.span, { className: "token class-name", children: "String" }), _jsx(_components.span, { className: "token punctuation", children: "," }), " ", _jsx(_components.span, { className: "token class-name", children: "Object" }), _jsx(_components.span, { className: "token punctuation", children: ">" })] }), " request", _jsx(_components.span, { className: "token punctuation", children: ")" }), " ", _jsx(_components.span, { className: "token punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "token keyword", children: "if" }), " ", _jsx(_components.span, { className: "token punctuation", children: "(" }), "request", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "containsKey" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token string", children: "\"nameFirst\"" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), " ", _jsx(_components.span, { className: "token punctuation", children: "{" }), "\n updates", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "add" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token string", children: "\"name_first = ?\"" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n args", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "add" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token function", children: "toStr" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "request", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "get" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token string", children: "\"nameFirst\"" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n ", _jsx(_components.span, { className: "token punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Potential improvements" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: ["Controller should accept a typed ", _jsx(_components.code, { children: "UpdatePersonRequest" }), " DTO"] }), "\n", _jsxs(_components.li, { children: ["Service should accept a ", _jsx(_components.code, { children: "UpdatePersonCommand" }), " use-case object"] }), "\n", _jsxs(_components.li, { children: ["Repository should accept a ", _jsx(_components.code, { children: "Person" }), " domain entity"] }), "\n", _jsx(_components.li, { children: "All three should share a single validation schema, not three separate Map key interpretations" }), "\n"] }), "\n", _jsxs(_components.p, { children: ["When I add a new field like ", _jsx(_components.code, { children: "linkedinUrl" }), ", I currently have to update:"] }), "\n", _jsxs(_components.ol, { children: ["\n", _jsx(_components.li, { children: "OpenAPI annotations in the controller" }), "\n", _jsx(_components.li, { children: "Map key handling in the service" }), "\n", _jsx(_components.li, { children: "Column mapping in the repository" }), "\n", _jsx(_components.li, { children: "Frontend expecting specific JSON structure" }), "\n"] }), "\n", _jsx(_components.hr, {}), "\n", _jsxs(_components.h2, { id: "so-what-went-wrong-exactly", children: [_jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#so-what-went-wrong-exactly", children: _jsx(_components.span, { className: "icon icon-link" }) }), "So what went wrong, exactly?"] }), "\n", _jsxs(_components.p, { children: ["The issue truly was remembering the strict boundaries for each layer (knowing exactly where one ends and one should begin). You can't see it from this blog post, but there ", _jsx(_components.em, { children: "were/are" }), " a lot of clean boundaries in the codebase already, but the examples given were some of the worst 'all-in-one' files that I should have put strict boundaries on right out of the gate to prevent them from this level of scope creep."] }), "\n", _jsx(_components.p, { children: "This leads to a particular kind of technical debt that’s hard to spot early or measure objectively. It’s also the dominant style of code I've often seen online and from AI/LLMs. The code runs. Tests pass. The API responds. But the code is messy, hard to understand, and difficult to maintain." }), "\n", _jsxs(_components.h2, { id: "sidebar-to-my-past-profession", children: [_jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#sidebar-to-my-past-profession", children: _jsx(_components.span, { className: "icon icon-link" }) }), "Sidebar to my past profession"] }), "\n", _jsx(_components.p, { children: "In finance, I became allergic to the phrase “best practices.” In reality it usually meant “common practices” at best, and “things people confidently repeat without understanding” at worst. Software engineering has a similar problem." }), "\n", _jsxs(_components.p, { children: ["So you have to be unusually discerning about which “best practices” you accept. So this is salient to me now as I write this reflection, as I am trying to identify what constitutes 'objectively' ", _jsx(_components.em, { children: "clean architecture" }), " and what is just being pedantic about subjective coding practices."] }), "\n", _jsxs(_components.h2, { id: "rethinking-the-approach", children: [_jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#rethinking-the-approach", children: _jsx(_components.span, { className: "icon icon-link" }) }), "Rethinking the approach"] }), "\n", _jsx(_components.p, { children: "Ultimately, the way I 'move the needle' for myself (and when collaborating on repos with others) is to (discuss and) set agreed upon boundaries on the repo, and then set some guardrails, often a coarse linting barrier. The goal isn’t perfect layers. The goal is to make it easier to respect boundaries than to violate them." }), "\n", _jsx(_components.hr, {}), "\n", _jsxs(_components.h3, { id: "adding-architectural-guardrails-pragmatically", children: [_jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#adding-architectural-guardrails-pragmatically", children: _jsx(_components.span, { className: "icon icon-link" }) }), "Adding architectural guardrails (pragmatically)"] }), "\n", _jsxs(_components.p, { children: ["I wanted to add ", _jsx(_components.a, { href: "https://www.archunit.org/userguide/", children: "ArchUnit tests" }), " to prevent future violations, but existing code would fail immediately. The solution: use ", _jsx(_components.code, { children: "FreezingArchRule" }), " to baseline current violations while preventing new ones:"] }), "\n", _jsx(_components.pre, { className: "language-java", children: _jsxs(_components.code, { className: "language-java", children: [_jsx(_components.span, { className: "token keyword", children: "import" }), " ", _jsxs(_components.span, { className: "token namespace", children: ["com", _jsx(_components.span, { className: "token punctuation", children: "." }), "tngtech", _jsx(_components.span, { className: "token punctuation", children: "." }), "archunit", _jsx(_components.span, { className: "token punctuation", children: "." }), "junit", _jsx(_components.span, { className: "token punctuation", children: "." })] }), _jsx(_components.span, { className: "token class-name", children: "FreezingArchRule" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n", _jsx(_components.span, { className: "token keyword", children: "import" }), " ", _jsx(_components.span, { className: "token keyword", children: "static" }), " ", _jsxs(_components.span, { className: "token namespace", children: ["com", _jsx(_components.span, { className: "token punctuation", children: "." }), "tngtech", _jsx(_components.span, { className: "token punctuation", children: "." }), "archunit", _jsx(_components.span, { className: "token punctuation", children: "." }), "lang", _jsx(_components.span, { className: "token punctuation", children: "." }), "syntax", _jsx(_components.span, { className: "token punctuation", children: "." })] }), _jsx(_components.span, { className: "token class-name", children: "ArchRuleDefinition" }), _jsx(_components.span, { className: "token punctuation", children: "." }), "*", _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n\n", _jsx(_components.span, { className: "token annotation punctuation", children: "@ArchTest" }), "\n", _jsx(_components.span, { className: "token keyword", children: "private" }), " ", _jsx(_components.span, { className: "token keyword", children: "final" }), " ", _jsx(_components.span, { className: "token class-name", children: "ArchRule" }), " controllers_should_not_depend_on_repositories ", _jsx(_components.span, { className: "token operator", children: "=" }), "\n ", _jsx(_components.span, { className: "token class-name", children: "FreezingArchRule" }), _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "freeze" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "\n ", _jsx(_components.span, { className: "token function", children: "noClasses" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), "\n ", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "that" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "resideInAnyPackage" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token string", children: "\"..controller..\"" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), "\n ", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "should" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "dependOnClassesThat" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), "\n ", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "resideInAnyPackage" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token string", children: "\"..repository..\"" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), "\n ", _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n\n", _jsx(_components.span, { className: "token annotation punctuation", children: "@ArchTest" }), "\n", _jsx(_components.span, { className: "token keyword", children: "private" }), " ", _jsx(_components.span, { className: "token keyword", children: "final" }), " ", _jsx(_components.span, { className: "token class-name", children: "ArchRule" }), " new_use_cases_follow_clean_architecture ", _jsx(_components.span, { className: "token operator", children: "=" }), "\n ", _jsx(_components.span, { className: "token function", children: "classes" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), "\n ", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "that" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "resideInAnyPackage" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token string", children: "\"..application.usecase..\"" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), "\n ", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "should" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "onlyDependOnClassesThat" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), "\n ", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "resideInAnyPackage" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "\n ", _jsx(_components.span, { className: "token string", children: "\"..domain..\"" }), _jsx(_components.span, { className: "token punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "token string", children: "\"java..\"" }), _jsx(_components.span, { className: "token punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "token string", children: "\"org.slf4j..\"" }), "\n ", _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n"] }) }), "\n", _jsxs(_components.p, { children: ["This required adding ", _jsx(_components.code, { children: "archunit.properties" }), ":"] }), "\n", _jsx(_components.pre, { className: "language-properties", children: _jsxs(_components.code, { className: "language-properties", children: [_jsx(_components.span, { className: "token attr-name", children: "freeze.store.default.path" }), _jsx(_components.span, { className: "token punctuation", children: "=" }), _jsx(_components.span, { className: "token attr-value", children: "archunit_store" }), "\n", _jsx(_components.span, { className: "token attr-name", children: "freeze.allow.store.creation" }), _jsx(_components.span, { className: "token punctuation", children: "=" }), _jsx(_components.span, { className: "token attr-value", children: "true" }), "\n"] }) }), "\n", _jsxs(_components.p, { children: ["Now the build tracks violations in ", _jsx(_components.code, { children: "archunit_store/" }), " files (gitignored). New violations fail, existing ones are tolerated until refactored."] }), "\n", _jsxs(_components.h3, { id: "introducing-a-use-case-layer", children: [_jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#introducing-a-use-case-layer", children: _jsx(_components.span, { className: "icon icon-link" }) }), "Introducing a use-case layer"] }), "\n", _jsx(_components.p, { children: "With guardrails in place, I'm refactoring the most problematic areas by introducing a use-case layer. This addresses the core issue: business logic scattered across controllers, services, and repositories. Each use case is one class with one clear responsibility." }), "\n", _jsxs(_components.h4, { id: "before-service-layer-doing-everything", children: [_jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#before-service-layer-doing-everything", children: _jsx(_components.span, { className: "icon icon-link" }) }), "Before: Service layer doing everything"] }), "\n", _jsx(_components.p, { children: "The service layer demonstrates all the problems in one place. Here's a typical create method with mixed concerns:" }), "\n", _jsx(_components.pre, { className: "language-java", children: _jsxs(_components.code, { className: "language-java", children: [_jsx(_components.span, { className: "token comment", children: "// PersonService.createPerson() - Mixed concerns everywhere" }), "\n", _jsx(_components.span, { className: "token keyword", children: "public" }), " ", _jsx(_components.span, { className: "token class-name", children: "Map" }), _jsxs(_components.span, { className: "token generics", children: [_jsx(_components.span, { className: "token punctuation", children: "<" }), _jsx(_components.span, { className: "token class-name", children: "String" }), _jsx(_components.span, { className: "token punctuation", children: "," }), " ", _jsx(_components.span, { className: "token class-name", children: "Object" }), _jsx(_components.span, { className: "token punctuation", children: ">" })] }), " ", _jsx(_components.span, { className: "token function", children: "createPerson" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token class-name", children: "Map" }), _jsxs(_components.span, { className: "token generics", children: [_jsx(_components.span, { className: "token punctuation", children: "<" }), _jsx(_components.span, { className: "token class-name", children: "String" }), _jsx(_components.span, { className: "token punctuation", children: "," }), " ", _jsx(_components.span, { className: "token class-name", children: "Object" }), _jsx(_components.span, { className: "token punctuation", children: ">" })] }), " request", _jsx(_components.span, { className: "token punctuation", children: ")" }), " ", _jsx(_components.span, { className: "token punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "token comment", children: "// Validation mixed with normalization" }), "\n ", _jsx(_components.span, { className: "token class-name", children: "String" }), " email ", _jsx(_components.span, { className: "token operator", children: "=" }), " ", _jsx(_components.span, { className: "token function", children: "toStr" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "request", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "get" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token string", children: "\"email\"" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n ", _jsx(_components.span, { className: "token keyword", children: "if" }), " ", _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token operator", children: "!" }), _jsx(_components.span, { className: "token class-name", children: "EmailValidator" }), _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "isValid" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "email", _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), " ", _jsx(_components.span, { className: "token punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "token keyword", children: "throw" }), " ", _jsx(_components.span, { className: "token keyword", children: "new" }), " ", _jsx(_components.span, { className: "token class-name", children: "BadRequestException" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token string", children: "\"Invalid email\"" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n ", _jsx(_components.span, { className: "token punctuation", children: "}" }), "\n\n ", _jsx(_components.span, { className: "token comment", children: "// Business rule enforcement scattered" }), "\n ", _jsx(_components.span, { className: "token keyword", children: "if" }), " ", _jsx(_components.span, { className: "token punctuation", children: "(" }), "personRepository", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "existsByEmail" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "email", _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), " ", _jsx(_components.span, { className: "token punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "token keyword", children: "throw" }), " ", _jsx(_components.span, { className: "token keyword", children: "new" }), " ", _jsx(_components.span, { className: "token class-name", children: "ConflictException" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token string", children: "\"Email already exists\"" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n ", _jsx(_components.span, { className: "token punctuation", children: "}" }), "\n\n ", _jsx(_components.span, { className: "token comment", children: "// Slug generation (domain logic) in service layer" }), "\n ", _jsx(_components.span, { className: "token class-name", children: "String" }), " slug ", _jsx(_components.span, { className: "token operator", children: "=" }), " ", _jsx(_components.span, { className: "token class-name", children: "SlugUtils" }), _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "slugify" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "\n ", _jsx(_components.span, { className: "token function", children: "toStr" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "request", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "get" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token string", children: "\"nameFirst\"" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "token function", children: "toStr" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "request", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "get" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token string", children: "\"nameLast\"" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), "\n ", _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n request", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "put" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token string", children: "\"slug\"" }), _jsx(_components.span, { className: "token punctuation", children: "," }), " slug", _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n\n ", _jsx(_components.span, { className: "token comment", children: "// Direct repository call with untyped Map" }), "\n ", _jsx(_components.span, { className: "token class-name", children: "String" }), " id ", _jsx(_components.span, { className: "token operator", children: "=" }), " personRepository", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "create" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "request", _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n\n ", _jsx(_components.span, { className: "token comment", children: "// Event publishing mixed with business logic" }), "\n eventPublisher", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "publishEvent" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token keyword", children: "new" }), " ", _jsx(_components.span, { className: "token class-name", children: "GenericEvent" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token string", children: "\"person.created\"" }), _jsx(_components.span, { className: "token punctuation", children: "," }), " id", _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n\n ", _jsx(_components.span, { className: "token comment", children: "// Manual response mapping" }), "\n ", _jsx(_components.span, { className: "token keyword", children: "return" }), " ", _jsx(_components.span, { className: "token class-name", children: "Map" }), _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "of" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token string", children: "\"id\"" }), _jsx(_components.span, { className: "token punctuation", children: "," }), " id", _jsx(_components.span, { className: "token punctuation", children: "," }), " ", _jsx(_components.span, { className: "token string", children: "\"email\"" }), _jsx(_components.span, { className: "token punctuation", children: "," }), " email", _jsx(_components.span, { className: "token punctuation", children: "," }), " ", _jsx(_components.span, { className: "token string", children: "\"slug\"" }), _jsx(_components.span, { className: "token punctuation", children: "," }), " slug", _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n", _jsx(_components.span, { className: "token punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "The core problems:" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "Business rules scattered across layers" }), "\n", _jsx(_components.li, { children: "No clear transaction boundaries" }), "\n", _jsx(_components.li, { children: "Hard to test individual business operations in isolation" }), "\n", _jsx(_components.li, { children: "Mixed concerns make changes risky" }), "\n"] }), "\n", _jsxs(_components.h4, { id: "after-clean-use-case-with-single-responsibility", children: [_jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#after-clean-use-case-with-single-responsibility", children: _jsx(_components.span, { className: "icon icon-link" }) }), "After: Clean use-case with single responsibility"] }), "\n", _jsx(_components.pre, { className: "language-java", children: _jsxs(_components.code, { className: "language-java", children: [_jsx(_components.span, { className: "token comment", children: "// CreatePersonUseCase.java - One class, one business action" }), "\n", _jsx(_components.span, { className: "token annotation punctuation", children: "@Component" }), "\n", _jsx(_components.span, { className: "token keyword", children: "public" }), " ", _jsx(_components.span, { className: "token keyword", children: "class" }), " ", _jsx(_components.span, { className: "token class-name", children: "CreatePersonUseCase" }), " ", _jsx(_components.span, { className: "token keyword", children: "implements" }), " ", _jsx(_components.span, { className: "token class-name", children: "CreatePerson" }), " ", _jsx(_components.span, { className: "token punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "token keyword", children: "private" }), " ", _jsx(_components.span, { className: "token keyword", children: "final" }), " ", _jsx(_components.span, { className: "token class-name", children: "DuplicateEmailChecker" }), " duplicateCheck", _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n ", _jsx(_components.span, { className: "token keyword", children: "private" }), " ", _jsx(_components.span, { className: "token keyword", children: "final" }), " ", _jsx(_components.span, { className: "token class-name", children: "PersonRepository" }), " repository", _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n ", _jsx(_components.span, { className: "token keyword", children: "private" }), " ", _jsx(_components.span, { className: "token keyword", children: "final" }), " ", _jsx(_components.span, { className: "token class-name", children: "DomainEventPublisher" }), " events", _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n\n ", _jsx(_components.span, { className: "token annotation punctuation", children: "@Override" }), "\n ", _jsx(_components.span, { className: "token keyword", children: "public" }), " ", _jsx(_components.span, { className: "token class-name", children: "Person" }), " ", _jsx(_components.span, { className: "token function", children: "handle" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token class-name", children: "CreatePersonCommand" }), " command", _jsx(_components.span, { className: "token punctuation", children: ")" }), " ", _jsx(_components.span, { className: "token punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "token comment", children: "// Clear business rule enforcement" }), "\n ", _jsx(_components.span, { className: "token keyword", children: "if" }), " ", _jsx(_components.span, { className: "token punctuation", children: "(" }), "duplicateCheck", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "exists" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "command", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "email" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), " ", _jsx(_components.span, { className: "token punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "token keyword", children: "throw" }), " ", _jsx(_components.span, { className: "token keyword", children: "new" }), " ", _jsx(_components.span, { className: "token class-name", children: "DuplicatePersonException" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "command", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "email" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n ", _jsx(_components.span, { className: "token punctuation", children: "}" }), "\n\n ", _jsx(_components.span, { className: "token comment", children: "// Domain object creation with invariants" }), "\n ", _jsx(_components.span, { className: "token keyword", children: "var" }), " person ", _jsx(_components.span, { className: "token operator", children: "=" }), " ", _jsx(_components.span, { className: "token class-name", children: "Person" }), _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "create" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "command", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "name" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: "," }), " command", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "email" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n\n ", _jsx(_components.span, { className: "token comment", children: "// Simple persistence of valid entity" }), "\n repository", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "save" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "person", _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n\n ", _jsx(_components.span, { className: "token comment", children: "// Explicit event with strong typing" }), "\n events", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "publish" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token keyword", children: "new" }), " ", _jsx(_components.span, { className: "token class-name", children: "PersonCreatedEvent" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "person", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "id" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n\n ", _jsx(_components.span, { className: "token keyword", children: "return" }), " person", _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n ", _jsx(_components.span, { className: "token punctuation", children: "}" }), "\n", _jsx(_components.span, { className: "token punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.pre, { className: "language-java", children: _jsxs(_components.code, { className: "language-java", children: [_jsx(_components.span, { className: "token comment", children: "// Inbound Port - The contract this use case fulfills" }), "\n", _jsx(_components.span, { className: "token keyword", children: "public" }), " ", _jsx(_components.span, { className: "token keyword", children: "interface" }), " ", _jsx(_components.span, { className: "token class-name", children: "CreatePerson" }), " ", _jsx(_components.span, { className: "token punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "token class-name", children: "Person" }), " ", _jsx(_components.span, { className: "token function", children: "handle" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token class-name", children: "CreatePersonCommand" }), " command", _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n", _jsx(_components.span, { className: "token punctuation", children: "}" }), "\n\n", _jsx(_components.span, { className: "token comment", children: "// Strongly typed command object" }), "\n", _jsx(_components.span, { className: "token keyword", children: "public" }), " ", _jsx(_components.span, { className: "token keyword", children: "record" }), " ", _jsx(_components.span, { className: "token class-name", children: "CreatePersonCommand" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "\n ", _jsx(_components.span, { className: "token class-name", children: "String" }), " name", _jsx(_components.span, { className: "token punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "token class-name", children: "String" }), " email\n", _jsx(_components.span, { className: "token punctuation", children: ")" }), " ", _jsx(_components.span, { className: "token punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "token comment", children: "// Validation happens at construction time" }), "\n ", _jsx(_components.span, { className: "token keyword", children: "public" }), " ", _jsx(_components.span, { className: "token class-name", children: "CreatePersonCommand" }), " ", _jsx(_components.span, { className: "token punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "token class-name", children: "Objects" }), _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "requireNonNull" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "name", _jsx(_components.span, { className: "token punctuation", children: "," }), " ", _jsx(_components.span, { className: "token string", children: "\"Name is required\"" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n ", _jsx(_components.span, { className: "token class-name", children: "Objects" }), _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "requireNonNull" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "email", _jsx(_components.span, { className: "token punctuation", children: "," }), " ", _jsx(_components.span, { className: "token string", children: "\"Email is required\"" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n ", _jsx(_components.span, { className: "token keyword", children: "if" }), " ", _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token operator", children: "!" }), _jsx(_components.span, { className: "token class-name", children: "EmailValidator" }), _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "isValid" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "email", _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), " ", _jsx(_components.span, { className: "token punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "token keyword", children: "throw" }), " ", _jsx(_components.span, { className: "token keyword", children: "new" }), " ", _jsx(_components.span, { className: "token class-name", children: "InvalidCommandException" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token string", children: "\"Invalid email format\"" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n ", _jsx(_components.span, { className: "token punctuation", children: "}" }), "\n ", _jsx(_components.span, { className: "token punctuation", children: "}" }), "\n", _jsx(_components.span, { className: "token punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Benefits of this approach:" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "Each use case is 20-50 lines of focused logic" }), "\n", _jsx(_components.li, { children: "Business rules are explicit and testable" }), "\n", _jsx(_components.li, { children: "Strong typing catches errors at compile time" }), "\n", _jsx(_components.li, { children: "Easy to understand what each operation does" }), "\n", _jsx(_components.li, { children: "Dependencies are minimal and clear" }), "\n", _jsx(_components.li, { children: "Can compose use cases for complex workflows" }), "\n"] }), "\n", _jsxs(_components.h3, { id: "standardizing-the-error-contract", children: [_jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#standardizing-the-error-contract", children: _jsx(_components.span, { className: "icon icon-link" }) }), "Standardizing the error contract"] }), "\n", _jsxs(_components.p, { children: ["I'm also gradually replacing ad-hoc error responses with ", _jsx(_components.a, { href: "https://blog.frankel.ch/problem-details-http-apis/", children: "RFC 9457 Problem Details" }), ". The goal is making client integration more predictable and reducing the countless ", _jsx(_components.em, { children: "Sentry" }), " error regression alerts that turn out to be false alarms."] }), "\n", _jsxs(_components.p, { children: ["This includes things like mapping constraint violations from ", _jsx(_components.a, { href: "https://beanvalidation.org/", children: "Jakarta Bean Validation" }), ". In JavaScript, my favorite is ", _jsx(_components.a, { href: "https://zod.dev/", children: "Zod" }), " for validation and automatic type inference (TypeScript)."] }), "\n", _jsxs(_components.p, { children: ["In Spring, ", _jsx(_components.a, { href: "https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/http/ProblemDetail.html", children: "ProblemDetail" }), " provides a built-in structure for these responses:"] }), "\n", _jsx(_components.pre, { className: "language-java", children: _jsxs(_components.code, { className: "language-java", children: [_jsx(_components.span, { className: "token annotation punctuation", children: "@RestControllerAdvice" }), "\n", _jsx(_components.span, { className: "token keyword", children: "class" }), " ", _jsx(_components.span, { className: "token class-name", children: "ApiExceptionHandler" }), " ", _jsx(_components.span, { className: "token punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "token annotation punctuation", children: "@ExceptionHandler" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token class-name", children: "DupulicatePersonException" }), _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token keyword", children: "class" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), "\n ", _jsx(_components.span, { className: "token class-name", children: "ProblemDetail" }), " ", _jsx(_components.span, { className: "token function", children: "handleDuplicate" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token class-name", children: "DuplicatePersonException" }), " ex", _jsx(_components.span, { className: "token punctuation", children: ")" }), " ", _jsx(_components.span, { className: "token punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "token keyword", children: "return" }), " ", _jsx(_components.span, { className: "token class-name", children: "ProblemDetail" }), _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "forStatusAndDetail" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), "\n ", _jsx(_components.span, { className: "token class-name", children: "HttpStatus" }), _jsx(_components.span, { className: "token punctuation", children: "." }), "CONFLICT", _jsx(_components.span, { className: "token punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "token string", children: "\"Person with email \"" }), " ", _jsx(_components.span, { className: "token operator", children: "+" }), " ex", _jsx(_components.span, { className: "token punctuation", children: "." }), _jsx(_components.span, { className: "token function", children: "email" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token punctuation", children: ")" }), " ", _jsx(_components.span, { className: "token operator", children: "+" }), " ", _jsx(_components.span, { className: "token string", children: "\" already exists\"" }), "\n ", _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n ", _jsx(_components.span, { className: "token punctuation", children: "}" }), "\n\n", _jsx(_components.span, { className: "token punctuation", children: "}" }), "\n"] }) }), "\n", _jsxs(_components.h3, { id: "trying-compile-time-mapping-with-mapstruct", children: [_jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#trying-compile-time-mapping-with-mapstruct", children: _jsx(_components.span, { className: "icon icon-link" }) }), "Trying compile-time mapping with MapStruct"] }), "\n", _jsxs(_components.p, { children: ["Instead of hand-rolled mappers that seem to drift over time, I've also experimented with ", _jsx(_components.a, { href: "https://mapstruct.org/", children: "MapStruct" }), " to generate type-safe mappings between layers:"] }), "\n", _jsx(_components.pre, { className: "language-java", children: _jsxs(_components.code, { className: "language-java", children: [_jsx(_components.span, { className: "token keyword", children: "public" }), " ", _jsx(_components.span, { className: "token keyword", children: "interface" }), " ", _jsx(_components.span, { className: "token class-name", children: "PersonWebMapper" }), " ", _jsx(_components.span, { className: "token punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "token class-name", children: "CreatePersonCommand" }), " ", _jsx(_components.span, { className: "token function", children: "toCommand" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token class-name", children: "CreatePersonRequest" }), " request", _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n ", _jsx(_components.span, { className: "token class-name", children: "PersonResponse" }), " ", _jsx(_components.span, { className: "token function", children: "toResponse" }), _jsx(_components.span, { className: "token punctuation", children: "(" }), _jsx(_components.span, { className: "token class-name", children: "Person" }), " person", _jsx(_components.span, { className: "token punctuation", children: ")" }), _jsx(_components.span, { className: "token punctuation", children: ";" }), "\n", _jsx(_components.span, { className: "token punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.p, { children: "This seems to eliminate a category of bugs where DTOs and domain models get out of sync." }), "\n", _jsx(_components.hr, {}), "\n", _jsxs(_components.h2, { id: "a-cleaner-repo-file-tree-might-look-something-like-this", children: [_jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#a-cleaner-repo-file-tree-might-look-something-like-this", children: _jsx(_components.span, { className: "icon icon-link" }) }), "A cleaner repo file tree might look something like this"] }), "\n", _jsx(_components.pre, { className: "language-markdown", children: _jsx(_components.code, { className: "language-markdown", children: "src/ [...]\n├── boot/ # entry + typed config (in this example, for Spring Boot)\n├── domain/ # Business types (minimal framework deps)\n│ ├── model/ # Value objects and aggregates\n│ ├── service/ # Domain rules and calculations\n│ └── port/ # Repository interfaces\n├── application/ # Use cases (transactional boundaries)\n│ ├── usecase/ # One class per business action\n│ └── dto/ # Input/output records for use cases\n├── adapters/\n│ ├── in/web/ # HTTP layer (controllers, DTOs, mappers)\n│ └── out/persistence/ # Database layer (repositories, entities)\n└── shared/ # Cross-cutting utilities\n" }) }), "\n", _jsx(_components.hr, {}), "\n", _jsxs(_components.h3, { id: "having-clear-boundaries", children: [_jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#having-clear-boundaries", children: _jsx(_components.span, { className: "icon icon-link" }) }), "Having Clear Boundaries"] }), "\n", _jsx(_components.p, { children: "The right amount of friction appears to prevent the wrong shortcuts without noticeably slowing legitimate development." }), "\n", _jsx(_components.p, { children: "On a team, once boundaries are agreed upon and set, they're enforced by tests rather than convention, and then architecture debates happen a lot less often. The code either compiles and finishes the CI/CD pipeline or it doesn't. Discussions are shifting from \"where should this logic live?\" to \"what's the right business rule?\"" }), "\n", _jsx(_components.hr, {}), "\n", _jsxs(_components.h2, { id: "how-a-request-flows-through-clean-architecture", children: [_jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#how-a-request-flows-through-clean-architecture", children: _jsx(_components.span, { className: "icon icon-link" }) }), "How a Request Flows Through Clean Architecture"] }), "\n", _jsxs(_components.p, { children: ["Using the ", _jsx(_components.code, { children: "CreatePerson" }), " use case as an example, here's how data flows through the clean boundaries:"] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { children: "POST /api/people {\"name\": \"Alice\", \"email\": \"alice@example.com\"}\n ↓\nPeopleController (HTTP → Command)\n ↓\nCreatePersonUseCase.handle(CreatePersonCommand)\n ↓\nPerson.create() + DuplicateEmailChecker (Domain Logic)\n ↓\nPersonRepository.save(Person) (Outbound Port)\n ↓\nJpaPersonRepository (Adapter → SQL)\n ↓\nDatabase\n\nResult flows back the same path, with mappers at each boundary:\nDatabase Entity → Domain Person → PersonResponse → JSON\n" }) }), "\n", _jsxs(_components.p, { children: ["My mental model is roughly: Dependencies point inward. Controllers depend on use cases, use cases depend on domain, but the domain never knows about HTTP, databases, or frameworks. This is enforced through ports (interfaces) and adapters (implementations), which is a rough ", _jsx(_components.a, { href: "https://alistair.cockburn.us/hexagonal-architecture/", children: "Hexagonal Architecture" }), " approach/example."] })] }); } function MDXContent(props = {}) { const {wrapper: MDXLayout} = Object.assign({}, _provideComponents(), props.components); return MDXLayout ? _jsx(MDXLayout, Object.assign({}, props, { children: _jsx(_createMdxContent, props) })) : _createMdxContent(props); } return { default: MDXContent };