spb/ultra-sharp-agent-skills Public

1---2name: architecting-service-boundaries3description: Decides how to split (or not split) a backend into services — modular monolith by default, boundaries along business capabilities, data ownership per service, sagas over distributed transactions, strangler-pattern extraction. Use when the user asks whether to adopt microservices, how to split a monolith, where service boundaries belong, how services should share data, or how to handle transactions across services. Do not use for message-broker mechanics (handling-async-messaging) or REST endpoint design (designing-rest-apis).4---56<!--7Author: Simon-Pierre Boucher8Contact: contact@spboucher.ai9-->1011# Architecting Service Boundaries1213## When to use / when NOT to use14- **Use for:** monolith-vs-services decisions, drawing/reviewing service boundaries, cross-service data and transaction design, extraction plans.15- **Do NOT use for:** broker/queue mechanics (handling-async-messaging), endpoint design (designing-rest-apis), or infra scaling (scaling-backend-services).1617## Core rules18191. **Default to a modular monolith.** One deployable with enforced internal module boundaries. Split a module out only on a proven trigger: independent scaling need, independent deploy cadence, or team-ownership friction — never "because microservices."202. **Boundaries follow business capabilities, not technical layers.**21   - ✅ `billing`, `catalog`, `fulfillment`22   - ❌ `api-service`, `business-logic-service`, `database-service`233. **Each service owns its data.** No other service reads its tables; integration happens through its API or published events. A shared database is one service wearing several trench coats.244. **Keep synchronous call chains shallow — ~2 hops max.** Request → A → B is acceptable; A → B → C → D couples four uptimes and multiplies latency. Deeper flows go asynchronous via events.255. **Distributed transactions are sagas.** A sequence of local transactions with explicit compensating actions for each step. Never reach for two-phase commit; design the compensation before the happy path.266. **Contracts are versioned and backward compatible.** Additive changes only within a version; breaking changes get a new version with a deprecation window. A consumer must never be forced to deploy in lockstep with a provider.277. **Extract with the strangler pattern.** Route a slice of traffic through the new service while the monolith still serves the rest; retire monolith code only after parity is proven. Big-bang rewrites forfeit the rollback path.288. **Watch for the distributed monolith.** Services that must deploy together, share a schema, or break when one is down have all of the costs of microservices and none of the benefits — re-merge or re-draw the boundary.2930## Workflow31321. List business capabilities and the teams that own them; sketch candidate boundaries there.332. For each candidate split, name the concrete trigger from rule 1. No trigger → stays a module.343. For each boundary: define the owned data, the exposed contract, and the events published.354. Map every cross-boundary write flow as a saga with compensations (rule 5).365. Plan extraction via strangler routing with a rollback switch (rule 7).376. Validate the design: for each service, confirm it can deploy alone with every other service frozen, and survive (degraded, not down) any single dependency being offline. Any "no" is a rule-8 smell — redraw before building.3839## Edge cases & failure modes40- **Two services keep changing in the same PRs** → boundary is wrong; merge them or move the shared concept to one owner.41- **A service needs another's data constantly** → replicate via events into a local read model instead of chatty sync calls.42- **Reporting needs to join across services** → dedicated analytics store fed by events; never grant cross-service table access.43- **Saga compensation impossible** (e.g., email already sent) → make the step last, or design it to be semantically reversible ("correction" message).4445## References46Decision tables, saga and strangler sketches: see [references/patterns.md](references/patterns.md).47