An ADR deciding where one service boundary goes, justified by a real seam, not the org chart.
What this is
Draw one line, and defend where you drew it.
Same ADR format, a structural decision: split this off into its own service, or keep it together. The justification has to be a real axis, a domain seam, a different scaling need, or a failure boundary.
💡 In plain English
Same kind of note as last time, but the decision is now "should these two things be one service or two?" The trap is splitting because it feels grown-up. The win is splitting only where it genuinely earns its keep.
Do this, in order
The steps.
1
Describe the slice of systemThe area you're deciding a boundary within. Keep it small and concrete.
2
Find the seamWhere does the language or the meaning of a word change? That's a bounded context (Session 8), and the natural place to cut.
3
Decide: split, or keep togetherCommit to one. "We will split X out" or "We will keep X and Y together."
4
Justify by a real axisDomain seam, different scaling need, different rate of change, or a hard failure boundary. Not "because different teams own them."
5
Run the distributed-monolith checkIf you split: do the two pieces have to deploy together? If yes, you didn't really split, you just added a network call.
The ADR format
A boundary, recorded.
Title
ADR-002 ·
Context
the slice · the bounded contexts you see · current pain
Decision
"We will [split out / keep together] ______."
Real axis
the seam / scaling / change-rate / failure boundary that justifies it
Distributed-monolith check
must the pieces deploy together? yes (bad) / no (good)
Consequences
cost accepted (network, consistency, or coupling) · revisit when: ___
How it's marked
What good looks like.
✓ Strong submission
The boundary sits on a domain seam, not a team or a database table.
You can name what now changes or scales independently.
The distributed-monolith check is answered honestly.
The cost of the choice (either way) is stated.
✕ Common mistakes
Splitting to match the org chart.
Services that must always deploy together (a distributed monolith).
No cost acknowledged for the split or the coupling.
A boundary drawn on a table, not on a behaviour.
Wrapping up
Hand in one boundary ADR.
Reuse the ADR format. Sessions 7 and 8 give you the styles and the domain seams. The distributed-monolith check is mandatory.
Logistics
One-page ADR · includes the deploy-together check · due Thu 3 July.
submit on Maven
Where's the seam?
Find one word that means two different things in your domain. Cut there.
see S8
For the instructorHow to teach thisclick to open ▾
The talk-track for introducing and explaining this project to students, beat by beat.
1
Connect to the last ADR: "Same one-page format you already know. The only new thing is what we're deciding, where a service boundary goes." That lowers the barrier.
2
State the why and the danger together: "Boundaries are expensive to move later, and splitting wrongly gives you all the cost of microservices and none of the benefit. This ADR makes you justify the cut."
3
Walk the steps; the make-or-break one is step 2, finding the seam. Reuse the "customer means three things" example from Session 8 so the abstract idea lands.
4
On the template, the new field is the distributed-monolith check, and it's the highest-signal line. Tell them to answer it honestly even if it embarrasses the decision.
5
Rubric: the recurring beginner mistake is splitting on the org chart. Say plainly: "If the only reason two things are separate services is that two teams own them, that's not an architecture reason."
6
Logistics, due July 3rd, and point anyone unsure of the seam back to the bounded-context idea in Session 8.