Update architect for flow pattern

Author: stefaniuk

patterns/architect-for-flow.md

@@ -3,63 +3,178 @@
 - [Architect for flow](#architect-for-flow)
   - [Context](#context)
   - [The pattern](#the-pattern)
+  - [The mindset](#the-mindset)
+  - [Core concepts and how they fit together](#core-concepts-and-how-they-fit-together)
+    - [Independent value streams (Lean Thinking)](#independent-value-streams-lean-thinking)
+    - [Stream-aligned teams (Team Topologies)](#stream-aligned-teams-team-topologies)
+    - [Services, products, and ownership](#services-products-and-ownership)
+    - [Bounded contexts and domain alignment](#bounded-contexts-and-domain-alignment)
+    - [Fast flow through small batches](#fast-flow-through-small-batches)
+  - [Co-creation, codesign, and coevolution](#co-creation-codesign-and-coevolution)
   - [Benefits](#benefits)
-  - [Caveats](#caveats)
-  - [Details](#details)
+  - [Practical guidance](#practical-guidance)
   - [Examples](#examples)
 
 ## Context
 
-- These notes are part of a broader set of [principles](../principles.md)
-- This pattern is closely related to the [deliver little and often](little-and-often.md) pattern
-- See also: [structured code](../practices/structured-code.md)
+- This pattern is part of a broader set of [engineering principles](../principles.md).
+- It strongly complements the [deliver little and often](./little-and-often.md) pattern.
+- It aligns with modern thinking on architecture modernisation, [evolutionary design / domain-driven design (DDD)](https://martinfowler.com/tags/evolutionary%20design.html), [Team Topologies](https://teamtopologies.com/key-concepts), and [Better Value Sooner Safer Happier (BVSSH)](https://www.soonersaferhappier.com/post/what-is-bvssh).
+- It should be read alongside [structured code](../practices/structured-code.md).
+
+At its core, _architecting for flow_ is about designing systems and teams so that valuable change can move quickly, safely, and sustainably from idea to production.
 
 ## The pattern
 
-Technical design choices should primarily optimise for rapid, reliable delivery and operations.
+Design architecture to enable fast, safe flow of change across independent value streams.
 
-One key consideration is how best to break the system down into independent services/components.
+Architecting for flow means intentionally shaping systems around:
 
-## Benefits
+- Independent value streams
+- Stream-aligned teams
+- Clear bounded contexts
+- Loosely coupled services and products
+
+The primary goal is not technology elegance, reuse, or theoretical purity. The goal is fast flow, which is the ability for teams to deliver small, incremental changes frequently, with confidence.
+
+This requires aligning business domains, team ownership, services/products, and architecture boundaries so that:
+
+- teams can work independently
+- changes are small and low-risk
+- coordination and hand-offs are minimised
+- learning happens early and often
+
+## The mindset
+
+Modern architecture recognises that software systems do not exist in isolation. Their behaviour, quality, speed of change, and reliability are shaped just as much by people, team structures, incentives, and ways of working as by code, infrastructure, or technologies.
+
+Poorly shaped architectures create:
+
+- Change coupling across teams
+- Slow delivery and high coordination costs
+- Fragile systems and risky releases
+- Unhappy, frustrated engineers and users
+
+Well-shaped architectures enable:
+
+- Independent delivery
+- Faster learning
+- Better quality
+- Safer change
+- Happier teams and users
+
+Architecting for flow is therefore a business optimisation strategy, not just an engineering one.
+
+## Core concepts and how they fit together
+
+### Independent value streams (Lean Thinking)
+
+An **independent value stream** is the fundamental building block. Each value stream:
+
+- Is aligned to a business subdomain
+- Is owned by a single stream-aligned team
+- Delivers business outcomes, not just features
+- Can be developed and deployed independently
+
+Architecture should make independence real, not just aspirational.
+
+### Stream-aligned teams (Team Topologies)
+
+Each independent value stream is owned by a **stream-aligned team**. That team:
+
+- Owns the product or service end-to-end
+- Makes day-to-day product and technical decisions
+- Builds, deploys, operates, and improves what they own
+- Optimises for outcomes and flow, not hand-offs
+
+Architecture should reduce the need for teams to coordinate in order to deliver change.
 
-In high level terms, systems which are designed to maximise rapid, reliable delivery and operations:
+### Services, products, and ownership
 
-- Are cost efficient: teams don't waste their time fighting the tools or working with difficult architectures
-- Improve business agility: these systems allow teams to respond more quickly to changes
-- Improve reliability: these systems are easier to understand, which leads to fewer failures and shorter recovery times
-- Improve team happiness: engineers are happy when the tools they work with let them get on with what they do best
+Architecting for flow means aligning:
 
-In many cases, building a system as a set of independently running services/components has benefits:
+- Products and services
+- Codebases and repositories
+- Runtime boundaries
+- Team ownership
 
-- Multiple components enable parallel development work by multiple teams
-- Teams can work at their own cadence
-- Changes with each component are easier to reason about and test
-- The best tools can be chosen for each job, rather than being hampered by a common set of technologies which need to be adequate for all parts of the system but may only suit some parts of the system well
-- Concerns such as scaling, resilience, etc, can be tailored on a per-component basis — for example avoiding the waste generated by scaling a monolith for the benefit of scaling one small aspect of the system
-- It is possible to isolate the impact of catastrophic failure of any individual component
-- Self-contained components with clear boundaries of responsibility reduce hand-offs between teams
-- Components with clear boundaries of responsibility are more easily replaced
-- Components with clear boundaries of responsibility more likely to be reusable — note: this does not promote building "generic" components — rather, components that have a clear scope
+A common smell is when:
+
+- Multiple teams must change their services together
+- Features require cross-team coordination by default
+- Teams share databases or internal implementation details
+
+Instead:
+
+- Each service or product should map clearly to a value stream
+- Ownership boundaries should be obvious
+- Dependencies should be explicit and intentional
+
+### Bounded contexts and domain alignment
+
+Clean **bounded contexts** are essential to flow. Key principles:
+
+- Split systems vertically by domain, not horizontally by technical layers
+- Avoid shared databases across bounded contexts
+- Encapsulate data, logic, and behaviour within each context
+- Accept duplication where it reduces coupling and coordination
+
+Bounded contexts reduce change coupling, allowing teams to move independently. Collaborative techniques such as [EventStorming](https://www.eventstorming.com/) are strongly encouraged to identify meaningful domain boundaries.
+
+### Fast flow through small batches
+
+Flow improves when teams:
+
+- Deliver small slices of value
+- Deploy frequently
+- Learn quickly from real usage
+- Reduce the blast radius of change
+
+Architecture should actively support:
+
+- Independent deployments
+- Progressive delivery
+- Feature toggling
+- Observability and fast feedback
+
+Large, coordinated releases are a sign that flow is being constrained by architecture.
+
+## Co-creation, codesign, and coevolution
+
+Architecting for flow is not a one-off design activity. It requires a **co-creation approach**, where:
+
+- Engineers, product managers, domain experts, and users collaborate
+- Architecture evolves incrementally
+- Decisions are revisited as learning increases
+
+Architecture should be **codesigned and coevolved** with the system:
+
+- Changes are made in small, safe steps
+- Learning feeds back into design
+- Teams continuously improve both the product and the architecture
+
+This is a deliberate move away from big up-front designs.
+
+## Benefits
 
-## Caveats
+Systems architected for flow tend to deliver strong outcomes. However
 
-- This pattern must not compromise quality: automation (including of quality control) is essential for safe implementation of this pattern
-- Architectures with multiple moving parts are more complicated. While splitting a system into multiple components is often a good idea, "too many" components can cause more harm than good. There is usually a sweet spot for how many components to break a system down into — and for small or simple systems a monolith might be better. In distributed systems:
-  - There are more failure modes to test, since calls which go over the network can fail in more ways than simple method invocations
-  - Versioning becomes a more complicated concern, and additional effort is required to ensure component APIs are compatible as each changes independently
-  - Clean domain boundaries are essential for safe implementation of this pattern
-  - Comprehensive monitoring and alerting is essential for safe implementation of this pattern
-- Components should be built because working in that way gives benefits, not purely because the components might be reused later: if they are later reused, that's even better
+- Flow must not compromise quality, strong automation is essential (testing, security, deployment)
+- More components ≠ better as over-fragmentation increases cognitive load and operational cost, small or simple systems may benefit from a well-structured modular monolith
+- Distributed systems introduce complexity, network failures has to be factored in, versioning challenges become a norm, observability becomes mandatory
+- Reuse is not the primary goal, build components for clear ownership and flow, reuse is a secondary benefit, not a justification
 
-## Details
+There is usually a sweet spot between monoliths and over-distributed systems.
 
-- Split services vertically via [bounded contexts](https://martinfowler.com/bliki/BoundedContext.html) rather than horizontally via technology layers: for example, do not implement dedicated processes to update databases or configuration
-- For components to be genuinely independent they need to only interact via their public APIs (e.g. not via a shared database)
-- Components should handle the entirety of their bounded context, for example persistence, logic and presentation (though obviously not all components will involve all of these layers)
-- This pattern applies to existing services as well as greenfield development projects — please see Martin Fowler's [StranglerFigApplication blog](https://martinfowler.com/bliki/StranglerFigApplication.html)
+## Practical guidance
 
-TO DO: reference to the NHS UI toolkit (for presentation fragments)
+- Split systems by bounded context, not by technical layers
+- Avoid shared databases between components
+- Ensure components interact only via public APIs (external to the internal service API)
+- Design services so a single team can change and deploy them independently
+- Align repositories, pipelines, and runtime ownership with team boundaries
+- Apply this pattern to existing systems as well as greenfield work, techniques like the [Strangler Fig](https://martinfowler.com/bliki/StranglerFigApplication.html) pattern can help evolve legacy systems safely
 
 ## Examples
 
-TO DO
+We have examples of live systems where this pattern has been applied in practice and continues to evolve. If you would like to explore concrete examples, including what worked well, what was learned, and where trade-offs were made, please get in touch. These systems can be discussed collaboratively and used as shared learning opportunities to help teams apply the pattern effectively in their own contexts.