liveBook · Manning

What you will learn in Grokking Software Architecture

A friendly guide for programmers and other curious people

by Matt Erman · Manning Early Access Program (MEAP)

Chapter by chapter

Chapter 1: The Architect's Compass: It's All About Tradeoffs

This chapter introduction previews the architecture concepts, decision-making process, and case study covered later.

1.2 Welcome to the Real World · 1.3 What is Software Architecture? · 1.4 Becoming a "Clarity Engineer" · 1.5 The Architectural Thinking Process: From an Idea to a Blueprint · 1.5.1 The Scenario: · 1.5.2 Step 1: The Spark (The "What") · 1.5.3 Step 2: The Inquiry (The "Why") · 1.5.4 Step 3: The Sketch (The "How") · 1.5.5 Step 4: The Options (The "Tradeoff") · 1.5.6 Step 5: The Decision (The "Receipt") · 1.6 The Scope of This Book and The Skills You'll Build · 1.6.1 What You'll Learn · 1.6.2 The Hands-On Journey · 1.6.3 A Language-Agnostic Approach · 1.6.4 What You Need to Know (and Have) · 1.6.5 The Architect's Compass · 1.7 The Dork Side: Friendster and the Billion-Dollar Tradeoff · 1.7.1 The Seduction of Perfection · 1.7.2 The Agony of the Spinning Wheel · 1.7.3 The Aftermath and the Lesson · 1.8.1 Make a Mini-Defensible Decision (Time: 10 minutes) · 1.9 Checklist · 1.10 Recap

What you learn in chapter 1 →

Chapter 2: The Architect's Toolkit: A Guide to Defensible Decisions

The chapter introduction previews the decision-making tools and concepts covered in Chapter 2.

2.2 The Myth of the “Perfect” Architecture · 2.3 The Architect’s Role: Explainer, Scribe, Boundary Keeper, and Scout · 2.4 The “-ilities”: Your Vocabulary of Quality · 2.4.1 Exercise: How to Use Them in the Real World · 2.4.2 Maintainability in Action: From Mess to Clarity · 2.4.3 Testability in Action: Breaking Dependencies · 2.4.4 Performance in Action: From Slow to Fast with Caching · 2.5 Constraints: The Box You Have to Think Inside · 2.5.1 Constraints in Action: "Good Enough for Now" · 2.6 Case Study: How Constraints Forced the Hydra's Defeat · 2.6.1 Risk: The Security Emergency · 2.6.2 Technology: The End of the Road · 2.6.3 Time: The Agony of Slow Changes · 2.6.4 People: The Divided Team · 2.6.5 Money: The High Cost of Ownership · 2.7 Architecture Decision Records (ADR) · 2.7.1 A Real-World Example · 2.7.2 The Lifecycle: From Document to Code · 2.8 The Tradeoff Triangle · 2.8.1 The Weighted Decision Model · 2.9 The Dork Side: CAP Theorem - A Story of Impossible Choices · 2.9.1 Why you, a junior dev, care about this academic-sounding theorem · 2.10 Your “In Action” Mission: · 2.11 Checklist: · 2.12 Recap

What you learn in chapter 2 →

Chapter 3: The Principles of Sound Structure: From Code That Works to Code That Lasts

This chapter introduction previews the structural principles, code smells, refactoring example, and case studies covered later.

3.2 Separation of Concerns · 3.3 Cohesion and Coupling · 3.3.1 Exercise: The "Simple Conversation" Test for Coupling · 3.4 SOLID Principles · 3.4.1 S – Single Responsibility Principle (SRP) · 3.4.2 O - Open/Closed Principle (OCP) · 3.4.3 L – Liskov Substitution Principle (LSP) · 3.4.4 I – Interface Segregation Principle (ISP) · 3.4.5 D – Dependency Inversion Principle (DIP) · 3.4.6 Real-World Design Questions to Ask · 3.5 In Action: “Before vs. After” SRP Refactor · 3.5.1 The "Before" Code (The Monolithic Method) · 3.5.2 The 5-Step Architectural Thinking Process in Action · 3.5.3 The "After" Code (Separated Concerns) · 3.5.4 The Payoff (The Defensible Decision) · 3.6 Case Study: Taming the 35-Headed Hydra · 3.6.1 The Scorecard Nightmare · 3.6.2 The Clarity Engineer's Diagnosis: The High Cost of Duplication · 3.7 Zooming Out: The Fractal Nature of Good Architecture · 3.8 The Dork Side: The First "Virtual Reality" - The Real Story Behind OOP · 3.9 Your “In-Action” Mission: Perform a Structural Audit · 3.10 Checklist · 3.11 Recap

What you learn in chapter 3 →

Chapter 4: Thinking in Layers: Separating the 'How' from the 'Why' at Scale

This chapter introduction previews the topics to be covered: architectural layers, downward dependencies, cross-cutting concerns, anti-patterns, and diagrams.

4.2 Layered Architecture · 4.2.1 Command Flow vs. Data Flow · 4.2.2 Classic Layered Architecture · 4.2.3 The Evolution of Layers · 4.2.4 Challenging the Layers: Newer Patterns · 4.3 Downward Dependency · 4.3.1 Why Is It So Important? · 4.3.2 The Danger Zone: Violating the Rule · 4.4 Physically Structuring Layers · 4.4.1 Approach 1: Folders (common in Python/JavaScript) · 4.4.2 Approach 2: Separate Projects (Common in Java/C#) · 4.4.3 Fitness Functions: A Different Kind of Test · 4.5 Cross-Cutting Concerns · 4.5.1 The Problem: Tangling and Scattering · 4.5.2 The Solution: Invert the Dependency! · 4.5.3 The Payoff: Why This Matters Architecturally · 4.6 The Four-Layer Diagram · 4.6.1 Reading the Blueprint · 4.7 Anti-Patterns: When Layers Go Wrong · 4.7.1 Anti-Pattern 1: The Fat Controller (or Bloated Service) · 4.7.2 Anti-Pattern 2: The Anemic Domain Model · 4.7.3 “After”: The Defensible Decision (Rich Domain, Thin Controller) · 4.7.4 The Architect’s Mandate: Decide and Enforce · 4.8 The Dork Side: The 7-Layer Sandwich That Runs the Internet · 4.8.1 The Problem: The Digital Tower of Babel · 4.8.2 The Solution: "Grandma's Letter" (The OSI Model) · 4.8.3 The "Aha!" Moment · 4.9 Your “In Action” Mission: Sketching Layers · 4.9.1 Your Mission: Sketch a Blog · 4.9.2 Instructions · 4.9.3 Extra Credit! · 4.9.4 A Model Sketch (For Comparison) · 4.10 Checklist · 4.11 Recap

What you learn in chapter 4 →

Chapter 5: Hexagonal Architecture: Protecting the Core: The Power of Ports and Adapters

This chapter introduction previews decoupling business logic from external systems and the vocabulary, diagram, code, and origins of hexagonal architecture.

5.2 Decoupling the Core: Breaking Free from "Database Gravity" · 5.2.1 The “Database First” Trap · 5.2.2 The Clarity Engineer's Shift in Focus: Inside vs. Outside · 5.2.3 Analogy: The "Clean Room" Lab · 5.3 Inside, Ports, and Adapters · 5.3.1 1. The Inside (The Core) · 5.3.2 2. The Ports (The Interfaces) · 5.3.3 3. The Adapters (The Translators) · 5.3.4 Analogy: The Universal Serial Bus (USB) · 5.3.5 A More Fun Analogy: The Castle and The Drawbridge · 5.4 Diagram: The Map of the Hexagon · 5.4.1 Reading the Map · 5.5 Code Snippet: The "Universal Power Outlet" · 5.5.1 The “Before” Code: The Infrastructure Anchor · 5.5.2 The Hexagonal Solution: One Core, Many Plugs · 5.5.3 Making the Hexagon Visible: The Project Structure · 5.5.4 The Strategic Payoff: The "Click" of the Plug · 5.6 The Dork Side: Cockburn's Hexagons and the Shape of Logic · 5.6.1 The Origin Story: Alistair and the Weather App · 5.6.2 The Geometry of "Enough Room" · 5.7 The Rescue Mission: Can I Migrate a Legacy App to Hexagonal? · 5.7.1 How to execute the "Strangler" Refactor: · 5.8 The Cost of Decoupling: Why You Might Not Want (or Need!) Hexagonal Architecture · 5.8.1 The Complexity Tax (Overhead) · 5.8.2 The "Indirection" Frustration · 5.8.3 Mapping Fatigue · 5.8.4 The Architect's Decision Matrix · 5.9 Your "In Action" Mission: Refactoring to Hexagonal · 5.9.1 1. The Hunt: Dig Up Your Own Skeleton · 5.9.2 2. The Sketch: 5 Minutes on Paper · 5.9.3 3. The Refactor: Steal This Example · 5.10 Checklist · 5.11 Recap

What you learn in chapter 5 →

Chapter 6: Reliable API Design: Public Contracts and Synchronous Communication

This chapter introduction previews API contracts, REST and GraphQL, AI-facing APIs, REST’s origins, and versioned endpoints.

6.2 The Client-Server Model · 6.2.1 The Cost of Crossing the Line · 6.2.2 The Separation of Duties · 6.2.3 The Anatomy of the Conversation (Request/Response) · 6.2.4 The "Clarity" Tradeoff: Thick vs. Thin Clients · 6.2.5 Why We Split Them (Scale and Specialization) · 6.3 API as a Public Contract · 6.3.1 The "Restaurant Menu" Analogy · 6.3.2 The Clauses of the Contract · 6.3.3 The "Breaking Change" Nightmare · 6.3.4 Hyrum's Law: The Hidden Contract · 6.3.5 The Escape Hatch: Versioning · 6.4 REST or GraphQL · 6.4.1 REST: The Vending Machine · 6.4.2 GraphQL: The Personal Shopper · 6.4.3 Making The Defensible Decision · 6.5 Designing for the New User: The AI Agent · 6.5.1 The "Dumb Genius" Paradox · 6.5.2 Naming IS Prompt Engineering · 6.5.3 The Modern Architect's AI Rule · 6.6 Diagram: Client-Server · 6.7 Code Snippet: API Endpoint · 6.7.1 Why This Matters · 6.8 The Hidden Costs of Abstraction · 6.8.1 The Hidden Performance Trap: The N + 1 Problem · 6.8.2 The Hidden Governance Trap: API Sprawl · 6.8.3 The Hidden Knowledge Trap: Debugging Hell · 6.8.4 The Hidden Availability Trap: Chained Dependencies · 6.9 The Dork Side: The “Accidental Genius” Of REST · 6.9.1 Dungeons and Dragons Trivia Time · 6.9.2 Why "State Transfer"? · 6.9.3 The "Lost Ark" of REST: HATEOAS · 6.9.4 Leveling Up: The Richardson Maturity Model · 6.9.5 The Historical Takeaway · 6.10 "In-Action": Defining an API Contract · 6.10.1 The "Function" Mindset (The Anti-Pattern) · 6.10.2 Exercise: The Contract Challenge · 6.11 Checklist · 6.12 Recap

What you learn in chapter 6 →

Chapter 7: Event-Driven Architecture (EDA): Temporal Decoupling and Asynchronous Communication

This chapter introduction previews topics in event-driven architecture without explaining them.

7.1.1 The Clarity Engineer's Fix · 7.2 Core Components & Publish-Subscribe · 7.2.1 The Players · 7.2.2 Command vs. Event (The Vocabulary) · 7.2.3 The Publish-Subscribe Pattern (Pub/Sub) · 7.3 Eventual Consistency (The Art of Being Late) · 7.3.1 The Lie We Tell Ourselves · 7.3.2 The "Coffee Shop" Analogy · 7.3.3 The "Panic Gap" (Read-Your-Writes) · 7.3.4 Connecting the Dots: The CAP Theorem Returns · 7.3.5 CAP Theorem Revisited: Why “Pick 2 out of 3” is (Mostly) a Lie · 7.4 The Event Lifecycle · 7.4.1 The Distribution Patterns: Queue vs. Topic · 7.4.2 The Four Operational Realities of Event Streams · 7.4.3 The Four Stages of Flow · 7.4.4 The Safety Valve: Dead Letter Queues (DLQ) · 7.4.5 The Hidden Trap: The Fan-Out Storm · 7.5 Code Snippet: Event Definition (The POCO) · 7.5.1 The Golden Rules of Event Design · 7.5.2 The "VIP Badge": The Marker Interface · 7.5.3 The Breadcrumbs: Correlation ID · 7.5.4 The Architectural Footprint: Where does this code live? · 7.6 The Dork Side: “Houston, We Have a Stack Trace!”, the Real Life Story of Apollo 13 · 7.6.1 The Hidden Bug (Technical Debt) · 7.6.2 The Incident: "Main Bus B Undervolt" · 7.6.3 The Debugging: Sy Liebergot’s Correlation · 7.6.4 The "Hotfix": The Square Peg in a Round Hole · 7.6.5 The Legacy: Why We Log · 7.7 In-Action Mission: Triggering Real-Time AI Inference · 7.7.1 The Mission Brief · 7.7.2 Acceptance Criteria (The Rules) · 7.7.3 The Target Output · 7.8 Checklist · 7.9 Recap

What you learn in chapter 7 →

Chapter 8: The Database as an Architectural Pillar: Choosing Between Strict Order and Massive Scale

This chapter introduction previews SQL, NoSQL, vector databases, normalization tradeoffs, and SQL injection without explaining them.

8.2 SQL vs. NoSQL Data Models · 8.2.1 The Relational Model (SQL) · 8.2.2 The Document Model (NoSQL) · 8.2.3 The AI Revolution: Vector Databases · 8.2.4 The Code Reality: SQL vs. NoSQL vs. Vector · 8.2.5 The Final Verdict: The Feud is Largely Over · 8.2.6 Choosing Your Pillar · 8.2.7 The Polyglot Tax: Complexity and Operational Overhead · 8.3 The Abstraction Layer: ORMs and Query Builders · 8.3.1 Declarative Querying (The Universal Standard) · 8.3.2 The Dark Side: The "Leaky Abstraction" · 8.4 Normalization vs. Denormalization · 8.4.1 Normalization (The "One Truth") · 8.4.2 Denormalization (The "Speed Demon") · 8.5 The Performance Reality Check: Indexing & Types · 8.5.1 Indexing: The "Phone Book" Analogy · 8.5.2 Data Types Matter (The "String" Trap) · 8.6 Real World Case Study: The "Hydra" Revisited · 8.6.1 The "Hydra" Architecture (The Trap) · 8.6.2 The Fix · 8.7 The Dork Side: The Story of “Little Bobby Tables” · 8.7.1 The Vulnerability · 8.7.2 The Fix · 8.7.3 Additional Database Security Tips · 8.8 Your “In-Action” Mission: The "Refactor or Die" Decision · 8.8.1 The Intel · 8.8.2 The Objective · 8.8.3 Your Mission · 8.9 Checklist · 8.10 Recap

What you learn in chapter 8 →

Chapter 9: Architecting for the Cloud: Trading Pets for Cattle and Concrete for Code

This chapter introduction previews cloud architecture topics, including disposable servers, compute tradeoffs, Infrastructure as Code, and automated services.

9.1.1 The Cloud is Not Magic: The Multi-Tenant Reality · 9.1.2 The Architectural Mindset Change · 9.1.3 But Wait… Isn’t This Infrastructure, Not Architecture? · 9.1.4 OK, So How Do I Actually Start? · 9.2 The Cloud-Ready Diagnostic · 9.3 Pets vs. Cattle · 9.3.1 The Problem with Pets · 9.3.2 The "Cattle" Revolution · 9.3.3 The Architectural Rule: Stateless Design · 9.4 The Compute Spectrum: Control vs. Convenience · 9.4.1 1. The "Do It Yourself" Model: Virtual Machines (IaaS) · 9.4.2 2. The Sweet Spot: Containers (CaaS) · 9.4.3 3. The "Just Run My Code" Model: Platform as a Service (PaaS) · 9.4.4 4. The Ultimate Abstraction: Serverless (Faas) · 9.4.5 5. The New Frontier: AI as a Service (AIaaS) · 9.4.6 How the Architect Chooses · 9.5 Spotlight: Serverless In-Action · 9.5.1 Event-Driven by Default · 9.5.2 How Serverless Changes Your Code (The Rules of the Road): · 9.5.3 The Serverless Sweet Spots: A Deeper Look · 9.5.4 Serverless and the "-ilities" · 9.5.5 The Next Challenge: Escaping the Dashboard · 9.6 Infrastructure as Code (IaC): Defeating the "ClickOps" Anti-Pattern · 9.6.1 The "Snowflake" Server and “The Curse of ClickOps” · 9.6.2 The Solution: Infrastructure as Code (IaC) · 9.6.3 The Superpowers of IaC · 9.7 Infrastructure as Code in Practice: The Declarative Blueprint · 9.7.1 The Architect's Infrastructure Review · 9.7.2 The Digital Memory Bank: The State File · 9.7.3 The Danger: The Single Point of Failure · 9.8 The Immutable Infrastructure Mindset · 9.8.1 The Developer's Parallel: Variables vs. Constants · 9.8.2 Never Patch a Live Server · 9.8.3 Why Architects Demand Immutability · 9.9 The Dork Side: "Friends Don't Let Friends Type in Production" (The AWS S3 Outage) · 9.10 Your "In Action" Mission: Scaffolding a Service · 9.11 Checklist · 9.12 Recap

What you learn in chapter 9 →

Chapter 10: Architecting for Resilience and Scale: Preparing for the Worst, Scaling for the Best

This chapter introduction previews resilience, scaling, and the risks of assuming systems will always work as expected.

10.2 Designing for Failure & Resilience Patterns · 10.2.1 Timeouts (The Escape Hatch) · 10.2.2 Retries (The Second Chance) · 10.2.3 Fallbacks (The Plan B) · 10.3 The Circuit Breaker Pattern: Preventing the Fire · 10.3.1 State 1: CLOSED (Everything is Fine) · 10.3.2 State 2: OPEN (The Breaker is Tripped) · 10.3.3 State 3: HALF-OPEN (The Test Ping) · 10.4 Putting It Into Practice: The Resilience Decorator · 10.4.1 Why the Fragile Way Fails in Production · 10.4.2 Why The Resilient Way Keeps Production Safe · 10.5 Scalability · 10.5.1 The Cost of the Dream: Scale is a Business Decision · 10.5.2 Scaling Up (Vertical Scaling) · 10.5.3 Scaling Out (Horizontal Scaling) · 10.5.4 Resilience at the Data Layer (Replication & Fault Tolerance) · 10.6 Basic Performance Tuning: Don't Compute What You Can Remember · 10.7 The Dork Side: The $370 Million Overflow · 10.7.1 The Bug · 10.7.2 The Real Architectural Failure · 10.7.3 The Architect's Warning: The Convenience Trap · 10.8 Your "In Action" Mission: Protecting Shop-Zilla · 10.9 Checklist · 10.10 Recap

What you learn in chapter 10 →

Chapter 11: Foundational Security Architecture: Building the Fortress, Not Just the Fence

This chapter introduction previews the security concepts, architectural boundaries, credential protection, and attack analysis covered later in the chapter.

11.2 The Security Mindset: Least Privilege and Defense in Depth · 11.2.1 The Principle of Least Privilege (PoLP) · 11.2.2 Defense in Depth (The Castle Approach) · 11.3 Architectural Security: API Gateways, Identity Providers, and Zero Trust · 11.3.1 The API Gateway: The Single Chokepoint · 11.3.2 Identity Providers (OAuth and OIDC): The Royal Seal · 11.3.3 Zero Trust Architecture: The Internal Guards · 11.4 Diagram: The Modern Security Architecture · 11.5 Code Snippet: Secrets Management · 11.5.1 Why is This a Disaster? · 11.5.2 What makes this "Secure"? · 11.5.3 The Art of Secret Rotation · 11.6 Threat Modeling: Thinking Like an Attacker · 11.7 The Dork Side: Target's HVAC Hack (2013) · 11.7.1 The Architectural Lesson · 11.8 Your "In Action" Mission: Applying Security · 11.9 Checklist · 11.10 Recap

What you learn in chapter 11 →

Chapter 12: The Great Debate: Monoliths vs. Microservices— Navigating the Distributed Divide

This chapter introduction previews the comparison of monoliths and microservices, legacy-system evolution, and the costs and failure risks of distributed architectures.

12.2 The Architecture Spectrum: Monoliths, Modular Monoliths, and Microservices · 12.2.1 The Monolith: The Single Deployable Unit · 12.2.2 The Microservice Architecture: Independently Deployable · 12.2.3 The Secret Catalyst: Conway's Law · 12.2.4 The Trap: The Distributed Monolith · 12.2.5 The Modular Monolith: The Golden Middle Ground · 12.2.6 Architecture Quick Reference Guide · 12.3 Why "Monolith" is Not a Dirty Word · 12.3.1 The Majestic Monolith · 12.3.2 The Premium on Developer Velocity · 12.3.3 The "Microservice Premium" · 12.4 When Microservices Actually Win · 12.4.1 1. The Human Scaling Problem (Conway's Law at Scale) · 12.4.2 2. Extreme, Asymmetrical Scaling · 12.4.3 3. Polyglot Environments (The Right Tool for the Job) · 12.4.4 4. Regulatory and Security Blast Radii · 12.5 The Strangler Fig Pattern: Safely Evolving a Legacy System · 12.5.1 The Botanical Inspiration · 12.5.2 The Strangler Fig in Action: Extracting "Billing" · 12.6 The Network Tax: The Hidden Costs of Distributed Architectures · 12.6.1 The Fallacies of Distributed Computing · 12.6.2 The Network Tax Summary (The 8 Fallacies) · 12.7 Code Snippet: The Network Tax in Action (The Blog Endpoint) · 12.7.1 The Monolith Approach: Simple and Fast · 12.7.2 The Microservice Approach: The Distributed Aggregator · 12.8 The Dork Side: MIT's Beer Game (The Bullwhip Effect) · 12.8.1 The Setup · 12.8.2 The Chaos · 12.8.3 The Architectural Lesson: Retry Storms · 12.9 Your "In Action" Mission: Choosing an Approach · 12.9.1 The Scenario · 12.9.2 Your Mission · 12.10 Checklist · 12.11 Recap

What you learn in chapter 12 →

Chapter 13: Architecting for the Delivery Lifecycle (CI/CD): Building Automated Gates for High-Velocity Software Delivery

This chapter introduction previews the delivery-lifecycle topics covered later in the chapter.

13.2 Designing for Deployability: Why Architecture Dictates Your Release Pipeline · 13.3 Deployment Strategies: Shifting Traffic Without Breaking Hearts · 13.3.1 Rolling Updates: The Assembly Line · 13.3.2 Blue-Green Deployment: The Parallel Worlds · 13.3.3 Canary Deployments: The Early Warning System · 13.3.4 Deployment vs. Release: The Feature Flag Distinction · 13.3.5 How Do I Decide Which Deployment Strategy is Best? · 13.4 Architecture Governance: Automated Guardrails · 13.4.1 Paying Off the Receipt: Architectural Fitness Functions · 13.4.2 Enforcing Boundaries in the Code · 13.4.3 The Database Evolution: The Expand/Contract Pattern · 13.4.4 Common Pitfalls When Setting Up Automated Guardrails · 13.5 Diagram: CI/CD Pipeline: The Conveyor Belt of Truth · 13.5.1 Walking Through the Automated Machinery · 13.5.2 Architectural Philosophy: Roll Forward vs. Rollback · 13.6 Code Snippet: GitHub Actions YAML · 13.7 Environment Promotion as Architectural Confidence · 13.7.1 The Defensive Toolkit: Navigating the Staging Conversation · 13.8 DORA Metrics: Your Architecture's Report Card · 13.9 The Dork Side: The $440M Deployment Error · 13.9.1 The Setup: Reviving a Dead Engine · 13.9.2 The Autopsy: 45 Minutes of Unchecked Fire · 13.9.3 The Architectural Retrospective: What Went Wrong and How to Prevent It · 13.9.4 Defending "-ilities" Against Short-Term Feature Pressure · 13.10 Your "In Action" Mission: Diagramming CI/CD · 13.10.1 The Scenario · 13.10.2 Your Objective · 13.10.3 The Shop-Zilla Blueprint Canvas Template · 13.11 Checklist · 13.12 Recap

What you learn in chapter 13 →

Concepts explained in this book

These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.