chapter two

2 WriteFlow's wake-up call: When good architecture intentions aren't enough

 

This chapter covers

  • A case study of a migration from a layered monolith to hexagonal architecture
  • The stakeholder conversation: how to justify the switch to your team and management
  • A step-by-step migration map with the questions to ask and the traps to avoid
  • How reusable components emerge naturally from a clean hexagonal core
  • What can go wrong

Now that you understand what hexagonal architecture is and why it matters, here comes the harder question: what does it actually look like to switch a real system to it?

This chapter follows WriteFlow—a fictitious but realistic content-platform SaaS—through exactly that journey. You will see the moment the team realized their layered architecture had become a liability, the conversation they had with their stakeholders, the migration steps they took, and the mistakes they nearly made. Every pattern and concept touched on here gets built in full across chapters 3 through 6. This chapter's job is simpler: to give you a concrete map of where you are going before you start building.

2.1 Meet WriteFlow: The system we will migrate

2.2 How a request travels through the hexagon

2.3 Reusable components: What you get for free

2.3.1 How these components compare to what you already know

2.3.2 Choosing the right component for your use case

2.4 The WriteFlow migration: A step-by-step map

2.4.1 Phase 1: Extract the domain

2.4.2 Phase 2: Define the ports

2.4.3 Phase 3: Wrap existing code as facade adapters

2.4.4 Phase 4: Refactor into handlers

2.4.5 Phase 5: Replace and verify

2.4.6 Making the case: The stakeholder conversation

2.4.7 What the WriteFlow team got wrong

2.5 Summary