Patterns, processes, and principles for designing and evolving server-side architecture—whether you're building new systems, modernizing legacy, or fixing a distributed monolith.

Core topics: Domain-driven design • Contract-first APIs • Event-driven architecture • Data ownership • Observability • Team organization

Technology-agnostic guidance based on real-world experience. Not a silver bullet—use what fits your context and adapt the rest. About this playbook →

🌱 Building a greenfield service
Start with Vision → Principles section → Target architecture.
Then baseline with the Maturity model.

🔧 Modernizing one slice of a monolith
Start with Domain ownership → Data ownership → Target architecture.
If you have 4+ teams, read Prerequisites first. Baseline with the Maturity model.

🚨 Fixing a distributed monolith
Start with Team Topologies → Prerequisites → Domain ownership.
Then use the Maturity model to identify the highest-leverage fixes.

• 01-strategy/ vision, prerequisites, team topologies, maturity model
• 02-principles/ domain ownership, data ownership, contract-first guidance
• 03-reference-architecture/ target architecture, patterns, guardrails, anti-patterns
• 04-07/ process, templates, checklists, examples (in progress)

Full structure: STRUCTURE →

• Small teams (1–2 teams): default to a modular monolith and apply the same principles (boundaries, contracts, ownership, observability).
  Details: see Vision.
• Growing teams (3–5 teams): consider services when you need independent deployment and domain boundaries are clear.
• Medium/large orgs (6+ teams): start with Prerequisites to avoid distributed monoliths.

If you’re rolling this out across teams: How to use this in an organization →

Improvements welcome via pull requests. Use ADRs for significant changes.

MIT License