Lesson 14 · Senior v2 architecture

Boundary leaks and architecture smells

How to review a v2 module critically: which smells are cosmetic, which smells change the dependency story, and why that distinction matters.

Your win: distinguish a real architecture leak from a merely ugly module, and explain why the dependency direction is the thing worth protecting most.

In plain English Plain English: an architecture smell matters most when it changes who depends on whom.

The problem: not every messy module is equally dangerous

Some modules are inconsistent but still survivable. Others look organized on the surface while quietly breaking the one rule the architecture was supposed to protect. Senior review means telling those apart instead of calling everything “technical debt” in one tone of voice.

The review rule The first question is not “is this pretty?” It is “did the dependency arrow stay pointed inward?”

The flagship smell in this repo

conversationmgmt is the best teaching case because the issue is concrete: the core imports infrastructure and constructs postgres repos inside the core service layer. That is not a naming problem. It changes the architecture contract.

Anchor — what to compare it against Compare conversationmgmt's leak to spike's controller-side wiring and eureka's gserver-side wiring. That contrast is what turns the smell into a lesson instead of a slogan.
Common mistake Calling a module “hexagonal” because it has folders named `core`, `port`, and `infrastructure`, without checking whether the core is still importing the concrete side.
Read this next

The repo-v2 map + the conventions docs

The strongest source for this lesson is the repo's own verified map and convention files, because the smell is local and specific.

→ Repo v2 map
→ .claude/rules/eureka-v2-conventions.md

Check yourself (from memory)

Q1. The most important architecture smell is one that…

The dependency story is the real load-bearing thing.
What is the first question in a senior architecture review of a v2 module?
recall, then click to reveal
Did the dependency arrow stay pointed inward, or did the core start depending on concrete infrastructure?
Want me to turn the conversationmgmt leak into a mini architecture-review exercise? Ask me.

Sources. Repo map; conventions docs.