Module 02 · The product and its people · 25 min · You are: Platform and product
Teams and how they work together
In this module
- You learn: The four team types and three interaction modes of Team Topologies, why a platform team exists to reduce the cognitive load of product teams, and why collaboration is planned to end.
- You do: Write the teams of the example company and four interactions between them: a time-boxed collaboration with team-checkout, X-as-a-Service with team-payments, facilitating from an enabling team. Then see what the check says when a collaboration has no end.
- You end with:
teams.yamlpasses the check, and the check now also confirms that the owner inplatform.yamlis a platform team. The platform team collaborates with checkout until a date, and then becomes X-as-a-Service.
A platform team that helps everyone with everything becomes the bottleneck it was meant to remove. Team Topologies gives the words to say what each team is for and how two teams should work together at a given time, so the platform team can be deliberate: close collaboration while a new capability is discovered, then a service other teams use without talking to the platform team at all. Its key concepts start from cognitive load: "overloaded teams make poor decisions and move slowly" (Team Topologies key concepts).
Open this module in the interactive course to track progress.
Concepts
- Stream-aligned team
- Aligned to a flow of work for a part of the business, such as checkout. Most teams in a company are this type, and the others exist to help them.
- Platform team
- Provides internal services that stream-aligned teams use to deliver with fewer things to know and fewer things to wait for.
- Enabling and complicated-subsystem teams
- An enabling team helps other teams learn something, then steps back. A complicated-subsystem team owns a part that needs specialist skills, such as ranking models.
- Interaction modes
- Collaboration (working closely together for a while), X-as-a-Service (using what the other team provides, with little contact) and facilitation (helping a team learn). Team Topologies' three modes (Team Topologies key concepts).
- Cognitive load
- How much a team has to know and keep in its head to do its work. The platform's job is to take load off product teams, not to add a new tool to learn.
When to use which interaction mode
| Mode | Use it when | Cost | In the example |
|---|---|---|---|
| Collaboration | Discovering something new together, such as the first golden path | High: both teams spend time; boundaries blur | platform with checkout, until a date |
| X-as-a-Service | The service is understood and stable enough to use without help | Low, if the service is good | platform for payments; search-ranking for checkout |
| Facilitating | A team needs to learn a skill it will keep | Medium, for a limited time | security-enablement with checkout |
Source for the types and modes: Team Topologies key concepts. The "until" and "then" fields are this course's way to write down that a collaboration is planned to end.
Files to know
Open them in your editor or on GitHub; the bullets say what to look at.
Steps
1. Write the teams
Five teams and four interactions. The first interaction is the one you build in this course: the platform team builds the first golden path together with team-checkout, its first user.
cd ~/platformengr/platform-design
Create teams.yaml
# The teams and how they work together, in Team Topologies terms.
# Owner: the platform team, agreed with every team listed. Read by the design check (rules T1 to T5).
teams:
- id: platform
type: platform
contact: "#platform-help"
mission: Self-service for delivery, runtime and agent access, so product teams do not wait for us.
- id: checkout
type: stream-aligned
contact: "#team-checkout"
mission: The checkout flow, from basket to payment confirmation.
- id: payments
type: stream-aligned
contact: "#team-payments"
mission: Payment providers, refunds and reconciliation.
- id: security-enablement
type: enabling
contact: "#security-office-hours"
mission: Helps teams learn secure delivery and agent safety, then steps back.
- id: search-ranking
type: complicated-subsystem
contact: "#search-ranking"
mission: The ranking models behind product search, which need specialist skills.
interactions:
- from: platform
to: checkout
mode: collaboration
until: 2027-02-28
then: x-as-a-service
why: Build the first golden path together with its first user. Ends when checkout ships on it without help.
- from: platform
to: payments
mode: x-as-a-service
why: Payments uses the platform as it is and asks for changes through the platform's backlog.
- from: security-enablement
to: checkout
mode: facilitating
why: Teaches checkout to review agent pull requests by risk, for one quarter.
- from: search-ranking
to: checkout
mode: x-as-a-service
why: Checkout calls the ranking API and does not need to understand the models.
Run the check. Expect ok for both platform.yaml and teams.yaml. The check reads them together now: platform.yaml says the owner is platform, and teams.yaml must say that platform is a team of type platform.
npm run check
2. See the links between files
From now on every owner in the design must be a team in this file. Try it: say the platform is owned by team-checkout.
Change in platform.yaml
- owner: platform
+ owner: checkout
Expect FAIL teams.yaml with [T5]: checkout is a stream-aligned team, not a platform team.
npm run check
Put it back:
Change in platform.yaml
- owner: checkout
+ owner: platform
Expect All checks passed.
npm run check
3. Look at it as team-checkout
You are team-checkout for a moment. Find every interaction that involves you: who works with you, how, and until when.
Expect three interactions with to: checkout: collaboration with the platform team, facilitating from security-enablement, and X-as-a-Service from search-ranking. That is a lot of contact for one team. The collaboration is the one with a date on it.
grep -n -B1 -A3 "to: checkout" teams.yaml
4. Commit
Save it.
git add -A && git commit -qm "Teams and their interactions" && git push -q
gh run list --workflow design-check --limit 1
Simplified for the course
Five teams, all named. A real map lists every team that uses the platform, and the platform team often splits into several teams as it grows.
The interactions are written by the platform team. In a company they are agreed with each team, and reviewed when one of them changes.
Dates are fixed in the file. Teams review them in a regular meeting and move them, with a reason, when the work takes longer.
Break it on purpose: Collaboration forever
Team-checkout loves working with the platform team. Their lead asks to make it permanent, and you agree: you delete the end date and what comes after it. Do this one, fix included: the next steps build on what the fix leaves in your repo.
You practise: recognising a collaboration that has become a dependency, and planning how it ends.
1. Break it
Delete from teams.yaml
- until: 2027-02-28
- then: x-as-a-service
npm run check
2. What you see
Expected: ok teams.yaml. You get: FAIL teams.yaml and two lines with [T4]. Read both: one is about a date, the other about what happens after it.
3. Fix it yourself
Make the collaboration with team-checkout end on a date you choose, and say what the interaction becomes afterwards. Done when the check passes and you can say what team-checkout must be able to do alone by then.
Hint 1
Collaboration costs both teams time. If it never ends, the platform team can only ever serve one team this closely. What should the next ten teams get?
Hint 2
Add until: with a date as YYYY-MM-DD, and then: with the mode it becomes: x-as-a-service for a service checkout can use alone.
The fix
Any date and either x-as-a-service or facilitating pass. The why line already says when it ends in words: "when checkout ships on it without help".
Add to teams.yaml in the first interaction, under mode: collaboration
until: 2027-02-28
then: x-as-a-service
npm run check
git add -A && git commit -qm "Collaboration with checkout ends on a date" && git push -q
After you fixed it: the five questions
- What failed?
- The team design. A permanent collaboration makes the platform team part of one product team and unavailable to the rest.
- How was it detected?
- By rule
T4of the check, when the file was changed. - Who responds?
- The platform team's lead and product owner, with team-checkout's lead.
- How is it corrected?
- Give the collaboration an end and a next mode, and write down what checkout must be able to do alone.
- How is it prevented?
- Review every collaboration at its
untildate: extend it with a reason, or move to X-as-a-Service.
Quiz
- Which interaction mode should the platform team have with most product teams most of the time?
- Collaboration, so the platform team always knows what each team needs
- X-as-a-Service: teams use the platform without needing to talk to the platform team
- Facilitating, so every team learns to build its own platform
- What is the main job of a platform team in Team Topologies?
- To reduce the cognitive load of stream-aligned teams by providing internal services they use
- To approve the technology choices of every stream-aligned team
- To run the production systems of the stream-aligned teams for them
- A security team spends one quarter teaching checkout to review agent pull requests, then steps back. What type and mode is that?
- A platform team in collaboration mode
- A complicated-subsystem team providing X-as-a-Service
- An enabling team, facilitating
Answers
- X-as-a-Service: teams use the platform without needing to talk to the platform team Collaboration is for discovery and is costly; a working platform is used as a service.
- To reduce the cognitive load of stream-aligned teams by providing internal services they use The platform lets product teams deliver with fewer things to know and fewer things to wait for.
- An enabling team, facilitating Enabling teams help others learn a skill and then step back.
Field note
The question I ask platform teams most is "who did you help this week, and will they need you again next week?" If the answer to the second half is always yes, the team is a service desk with better tools. A collaboration with an end date is the cheapest fix I know.