Architecture and Team Topologies

Software architecture and team design are the same problem viewed from two sides. Team Topologies, by Matthew Skelton and Manuel Pais, gives architects a vocabulary for the human side: a small set of team types and interaction modes that make it easier to design systems that teams can actually own.

Cognitive load as a design constraint

A team can hold only so much in its head: the domain, the codebase, the tooling, the operational burden. When load exceeds capacity, quality falls and delivery slows. Architecture decisions directly affect load. A service that requires deep knowledge of three other services raises it; a clean API with good documentation lowers it.

Treat cognitive load as a first-class non-functional requirement. Ask: can one team of five to nine people understand, change, and operate this component?

The four team types

| Team type | Purpose | Architectural implication | |-----------|---------|---------------------------| | Stream-aligned | Deliver value along a business flow | Owns services for a domain end to end | | Platform | Provide self-service capabilities | Offers paved roads: CI, runtime, observability | | Enabling | Help other teams adopt new skills | Temporary coaching, not ownership | | Complicated subsystem | Own specialist components | Hides hard math or domain behind clean interfaces |

Most teams should be stream-aligned. Example: a payments company has stream-aligned teams for Onboarding, Transfers, and Cards; a platform team offering deployment and monitoring; a complicated-subsystem team for fraud scoring; and an enabling team that helps others adopt a new event framework before moving on.

The three interaction modes

• Collaboration: two teams work closely for a limited time to discover something new. High bandwidth, high cost.
• X-as-a-Service: one team consumes another's capability through a clear interface with minimal contact. Low cost at scale.
• Facilitating: one team helps another get better at something.

A common mistake is staying in collaboration mode forever. If Transfers and Fraud meet daily two years after launch, the boundary is wrong or the interface is unclear. Aim to move relationships toward X-as-a-Service, and treat prolonged collaboration as a signal to redraw the boundary.

Designing the architecture with the teams

1. Identify business streams and their change rates.
2. Draw bounded contexts from the domain, then map each to one team.
3. Decide which capabilities are common enough to become platform services.
4. Define each interface as a product: documented, versioned, supported.
5. Check load: does any team own more than it can reasonably handle?

Stream team: Transfers
  Owns: transfer-service, ledger-adapter
  Consumes as a service: identity (platform), fraud-score (subsystem)
  Interaction: X-as-a-Service with both
  Load check: 2 services, 1 datastore, on-call rota of 6

Common anti-patterns

• A platform team that mandates rather than serves, becoming a bottleneck. Measure it by adoption, not compliance.
• A shared "DevOps" team that everyone files tickets with.
• Enabling teams that quietly become permanent owners.
• Splitting teams by technology, which forces every feature to cross handoffs.

Evolve with the organization

Team topologies are not fixed. As a product matures, platform capabilities emerge from repeated stream-team work, and subsystems get extracted when complexity grows. Review the topology every six to twelve months: where are handoffs piling up, where are teams stretched, which interactions have outlived their purpose?

Key takeaways

• Treat team cognitive load as a design constraint.
• Use four team types: stream-aligned, platform, enabling, complicated subsystem.
• Prefer X-as-a-Service interactions; use collaboration only temporarily.
• Map bounded contexts to teams and treat interfaces as products.
• Revisit the topology regularly as the system and company change.