Team Topologies: Stream-Aligned, Platform, and Enabling Teams for Engineering Organizations

How you structure your engineering teams determines what software you can build. This is Conway's Law: "Organizations which design systems are constrained to produce designs which are copies of the communication structures of those organizations."

Team Topologies (the book by Matthew Skelton and Manuel Pais) gives a vocabulary and framework for designing engineering organizations to produce the architectures you want — and to keep cognitive load manageable as teams scale.

---

The Four Team Types

The ratio to aim for: Most engineers (70–80%) on stream-aligned teams, supported by a smaller platform team (15–20%), with enabling teams used temporarily.

---

Stream-Aligned Teams

Stream-aligned teams are the primary building block. Each owns a slice of the product and can independently deploy value to customers:

Characteristics:

• Small: 5–9 people (Dunbar's number for effective teams)
• Full-stack: includes product, design, engineering (no separate design team throwing specs over the wall)
• Persistent: not project-based; the team exists as long as the product area does
• Autonomous: can deploy independently without asking another team
• Owns the full lifecycle: build, run, support

What breaks stream-alignment:

• High coordination dependencies (can't ship without 3 other teams)
• Shared codebase with no ownership boundaries
• Separate QA team that must test every release
• DBA team that must approve every database change

Example team charter:

Payments Team — Charter

Mission: Enable customers to pay for Viprasol services reliably and efficiently.

Owns:

• Checkout flow (frontend + backend)
• Payment processing (Stripe integration)
• Invoice generation and delivery
• Revenue recognition reporting

Does NOT own:

• Subscription pricing (→ Growth team)
• Customer support for payment disputes (→ Support tooling team)
• Fraud detection (→ Complicated-subsystem team)

Dependencies we accept:

• Auth tokens from the Platform team's auth service
• Email delivery from the Platform team's notifications service

Our deployment pipeline: Fully self-service via GitHub Actions On-call: Payments team owns their own on-call rotation SLOs: 99.95% checkout success rate; < 3s p99 checkout completion

---

## Platform Teams

A platform team exists to reduce the cognitive load on stream-aligned teams. They don't build features — they build the internal products that make features easier to build.

**"Good platform" test:** A stream-aligned team can use the platform's capabilities without asking the platform team for help. Self-service documentation, clear contracts, opinionated defaults.

**Platform team products (examples):**

| Platform Product | What It Provides to Stream-Aligned Teams |
|---|---|
| CI/CD pipeline template | Pre-configured GitHub Actions workflow: test, build, deploy |
| Observability stack | Pre-configured Datadog dashboards, alert templates, log formats |
| Secrets management | Self-service access to secrets via Vault or AWS Secrets Manager |
| Auth service | JWT issuance and validation; teams consume, don't implement |
| Database provisioning | Self-service PostgreSQL provisioning with sensible defaults |
| Feature flags | LaunchDarkly or in-house system; teams add flags without platform help |

**Platform team failure modes:**
- **Ticket-based access model**: Teams must submit requests to the platform team. This creates a bottleneck that defeats the purpose.
- **Over-engineered infrastructure**: Platform team builds Kubernetes clusters when most teams need simple ECS Fargate.
- **Ignored user research**: Platform team builds what they think teams need, not what teams actually struggle with.

**Platform team health metric**: Time for a new engineer to go from nothing to a service deployed in production. If it takes > 1 day, the platform has gaps.

---

Interaction Modes

Teams don't just "work together" — the mode of interaction matters:

Collaboration → X-as-a-Service transition:

Most platform services start as collaboration (teams work together to figure out the right interface), then transition to X-as-a-Service (teams consume self-service, minimal communication):

## Example: Internal Auth Service Evolution

Phase 1 (Collaboration — weeks 1–6):
  - Platform team embeds with 2 stream-aligned teams
  - Jointly design the JWT format, token exchange endpoint, SDK
  - Platform team writes the service; stream-aligned teams give feedback
  
Phase 2 (X-as-a-Service — ongoing):
  - Documentation: "How to add auth to your service" (30-minute guide)
  - SDK: @company/auth — npm install, configure once, works
  - Support: GitHub Discussions; platform team responds within 1 day
  - Stream-aligned teams use auth without talking to platform team

---

Cognitive Load

Cognitive load is the core concept in Team Topologies. Teams have limited cognitive capacity — the more they need to understand and maintain, the less effective they are.

Three types of cognitive load:

Signs of too much cognitive load:

• Team owns too many services to understand all of them well
• On-call pages for things team doesn't understand
• PR review takes days because no one has context
• New engineers take 3+ months to be productive

Team size + cognitive load limit:

## Cognitive Load Assessment — Payments Team

Services owned: 3 (checkout-api, billing-worker, invoice-service)
External dependencies: 2 (auth, notifications)
Languages: TypeScript (all)
Frameworks: Fastify, BullMQ, Stripe SDK
Databases: PostgreSQL, Redis

Assessment: MANAGEABLE
- 3 services is near the upper limit for a 6-person team
- All TypeScript reduces switching cost
- External dependencies well-documented (X-as-a-Service)

DO NOT ADD to this team's scope:
- Payment dispute handling
- Subscription plan management
- Fraud detection
(Each would require new domain knowledge that pushes cognitive load past limit)

---

Conway's Law in Practice

If your architecture has tight coupling between services, look at your org chart — you probably have tight coupling between teams (shared goals, dependencies, joint deployments).

To fix the architecture, first fix the team structure:

Current state (problem):
Team A owns frontend + half of API
Team B owns other half of API + database
Result: Every feature requires A and B to coordinate; architecture couples API halves

Desired state:
Team A owns user-facing product (frontend + API + DB read models)
Team B owns data processing and storage (API + DB writes)
Result: Teams can deploy independently; architecture boundary matches team boundary

This is the "inverse Conway maneuver" — deliberately designing team boundaries to produce the architecture you want.

---

When to Apply Team Topologies

Team Topologies becomes relevant at 15–25+ engineers. Before that:

• You probably have one stream-aligned team (everyone)
• "Platform" is one engineer maintaining CI/CD and infra
• Formal interaction modes are overhead

When to formalize:

• Teams are slowing each other down due to dependencies
• New engineers take too long to be productive (cognitive load symptom)
• One team's deployment breaks another team's service
• "We need a meeting to figure out who owns this" is a recurring problem

---

Working With Viprasol

We advise engineering leaders on team structure and organization design — applying Team Topologies to real orgs, defining team charters and ownership boundaries, designing platform capabilities, and conducting cognitive load assessments.

→ Talk to our team about engineering organization design.

---

See Also

• Platform Engineering — building the platform team's products
• Startup CTO — team structure from the CTO perspective
• Engineering Handbook — codifying team norms
• Microservices Architecture — architecture that reflects team boundaries
• Web Development Services — engineering advisory