Project 1: Team Interaction Audit (Mapping Friction)
Create a visual map of how teams currently interact, identifying “high-friction” zones where communication is constant and “low-friction” zones where teams work autonomously.
Quick Reference
| Attribute | Value |
|---|---|
| Difficulty | Beginner |
| Time Estimate | Weekend (8-12 hours) |
| Primary Language | Markdown / Graphviz (DOT) |
| Alternative Languages | Python, Mermaid.js |
| Prerequisites | Basic graph concepts, organizational awareness |
| Key Topics | Conway’s Law, Team Topologies, Interaction Modes |
1. Learning Objectives
By completing this project, you will:
- Map organizational communication patterns using directed graphs
- Distinguish between necessary and unnecessary communication
- Identify friction points where coordination overhead is highest
- Apply Team Topologies interaction modes to categorize team relationships
- Create actionable visualizations that drive organizational change
2. Theoretical Foundation
2.1 Core Concepts
Conway’s Law
Melvin Conway observed in 1967 that organizations produce systems mirroring their communication structures. This isn’t just an observation—it’s a force of nature in software organizations.
ORGANIZATION STRUCTURE SOFTWARE ARCHITECTURE
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ Team A │<─>│ Team B │ ==> │ Module A│<─>│ Module B│
└─────────┘ └─────────┘ └─────────┘ └─────────┘
^ ^ ^ ^
└──────┬──────┘ └──────┬──────┘
│ │
Communication Dependencies
If two teams talk frequently, their code will be tightly coupled. If two teams never talk, their systems will have clean interfaces (or none at all).
The Three Interaction Modes (Team Topologies)
| Mode | Purpose | Duration | Example |
|---|---|---|---|
| Collaboration | Discovery of new boundaries | Time-boxed (weeks) | Two teams building a new shared API |
| X-as-a-Service | Clean consumption interface | Ongoing | Platform team providing CI/CD |
| Facilitation | Knowledge transfer | Time-boxed (weeks) | Enabling team teaching observability |
The Friction Spectrum
LOW FRICTION HIGH FRICTION
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ Self-service │ Async docs │ Scheduled │ Ad-hoc calls │
│ API │ request │ syncs │ meetings │
└─────────────────────────────────────────────────────────────┘
│ │
Autonomous Coupled
2.2 Why This Matters
You cannot design a better operating model until you see the existing one. Most organizations have no visibility into their actual communication patterns—they only see the org chart, which rarely reflects reality.
The invisible costs of high friction:
- 3+ hours/day in coordination meetings
- Days of wait time for cross-team approvals
- Duplicated work because teams don’t know what others are building
- Low morale from “death by a thousand meetings”
2.3 Historical Context
Value Stream Mapping originated in Toyota’s manufacturing system (1950s) and was adapted for software by the Lean/Agile movement. Team Topologies (2019) brought organizational design into the DevOps era, providing a vocabulary for team interactions that didn’t exist before.
2.4 Common Misconceptions
| Misconception | Reality |
|---|---|
| “More communication is better” | Communication has a cost. Goal is sufficient communication, not maximum. |
| “The org chart shows how teams interact” | Informal networks often override formal structures. |
| “Daily standups solve coordination” | Standups often create false sense of alignment without actual coordination. |
| “Remote work increased friction” | Remote work exposed existing friction that was previously hidden. |
3. Project Specification
3.1 What You Will Build
A Team Interaction Graph that visualizes:
- Every team in your organization (or a subset)
- The type and frequency of interactions between teams
- “Hot spots” where friction is highest
- Comparison between formal structure and actual behavior
3.2 Functional Requirements
- Data Collection
- Track interaction types (Slack, meetings, tickets, PRs)
- Capture frequency (daily, weekly, ad-hoc)
- Record direction (who initiates, who responds)
- Categorization
- Label each edge with interaction mode (Collaboration, X-as-a-Service, Facilitation)
- Identify “undefined” interactions (friction!)
- Track wait times for cross-team requests
- Visualization
- Generate a directed graph
- Color-code by friction level (red = high, green = low)
- Line thickness = frequency
- Support filtering by team, type, or time period
- Analysis
- Identify teams with most inbound dependencies (bottlenecks)
- Identify circular dependencies
- Highlight teams that should be talking but aren’t
3.3 Non-Functional Requirements
- Output must be version-controllable (text-based graph definition)
- Must support incremental updates (add new interactions over time)
- Should work without requiring sensitive data (no message content)
3.4 Example Usage / Output
Input (DOT format):
digraph TeamInteractions {
rankdir=LR;
node [shape=box, style=rounded];
// Teams
Checkout [label="Checkout Team"];
Payment [label="Payment Team"];
Platform [label="Platform Team"];
SRE [label="SRE Team"];
Security [label="Security Review"];
// Interactions
Checkout -> Payment [label="Daily Sync", color=red, penwidth=3];
Platform -> Checkout [label="API", color=green, penwidth=1];
SRE -> Payment [label="Mentoring", color=blue, style=dashed];
Payment -> Security [label="Wait: 3 Days", color=red, penwidth=2];
}
Generated Graph:
┌──────────────┐ ┌──────────────┐
│ Checkout │──── Daily Sync (RED) ───────►│ Payment │
│ Team │◄─── API (GREEN) ─────────────│ Team │
└──────────────┘ └──────┬───────┘
▲ │
│ │
│ API Wait: 3 Days (RED)
│ (GREEN) │
│ ▼
┌──────────────┐ ┌──────────────┐
│ Platform │ │ Security │
│ Team │ │ Review │
└──────────────┘ └──────────────┘
Friction Report:
=== FRICTION ANALYSIS ===
HIGH FRICTION (Immediate Action Required):
- Checkout <-> Payment: 15 Slack messages/day, daily sync meeting
RECOMMENDATION: Define API contract, move to X-as-a-Service
- Payment -> Security: 3-day average wait time
RECOMMENDATION: Create self-service security scan pipeline
LOW FRICTION (Model Examples):
- Platform -> Checkout: 0 direct messages, uses documented API
STATUS: X-as-a-Service working as intended
UNDEFINED INTERACTIONS:
- Database Admins <-> Everyone: No formal protocol found
RECOMMENDATION: Define Team API for DBA team
3.5 Real World Outcome
You will produce a “Friction Heatmap” where:
- Hot lines (thick/red) = teams stuck in meetings or waiting for each other
- Cool lines (thin/green) = clean, service-based interfaces
This visualization becomes the starting point for every organizational design conversation.
4. Solution Architecture
4.1 High-Level Design
┌─────────────────────────────────────────────────────────────────┐
│ DATA SOURCES │
├─────────────┬─────────────┬─────────────┬─────────────────────┤
│ Slack │ Calendar │ Jira │ GitHub/GitLab │
│ Logs │ Invites │ Tickets │ PR Reviews │
└──────┬──────┴──────┬──────┴──────┬──────┴──────────┬──────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ INTERACTION COLLECTOR │
│ (Python script or manual survey) │
└───────────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ INTERACTION DATABASE │
│ (YAML/JSON file or SQLite) │
│ │
│ interactions: │
│ - from: team-checkout │
│ to: team-payment │
│ type: sync_meeting │
│ frequency: daily │
│ friction: high │
└───────────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ GRAPH GENERATOR │
│ (DOT/Mermaid output) │
└───────────────────────────┬─────────────────────────────────────┘
│
┌─────────────┴─────────────┐
▼ ▼
┌─────────────────────────┐ ┌─────────────────────────┐
│ VISUALIZATION │ │ FRICTION REPORT │
│ (SVG/PNG graph) │ │ (Markdown summary) │
└─────────────────────────┘ └─────────────────────────┘
4.2 Key Components
- Team Registry: List of all teams with metadata (size, mission, Slack channel)
- Interaction Log: Time-series of team-to-team communications
- Graph Generator: Converts log to visual representation
- Analyzer: Calculates metrics (centrality, clusters, friction score)
4.3 Data Structures
# teams.yaml
teams:
- id: team-checkout
name: "Checkout Team"
size: 6
mission: "End-to-end checkout experience"
slack: "#team-checkout"
oncall: "checkout-oncall"
# interactions.yaml
interactions:
- id: int-001
from: team-checkout
to: team-payment
type: collaboration # collaboration | x-as-a-service | facilitation
channel: meeting # meeting | slack | ticket | pr
frequency: daily
direction: bidirectional
notes: "Daily sync to discuss payment failures"
friction_score: 8 # 1-10 scale
4.4 Algorithm Overview
- Load team registry and interaction log
- Build directed graph with teams as nodes
- Calculate edge weights from frequency and friction
- Identify clusters (teams that only talk to each other)
- Detect bottlenecks (high in-degree nodes)
- Generate DOT/Mermaid output
- Render visualization and report
5. Implementation Guide
5.1 Development Environment Setup
# Create project directory
mkdir team-interaction-audit && cd team-interaction-audit
# Python setup (optional, for automation)
python3 -m venv venv
source venv/bin/activate
pip install pyyaml networkx matplotlib
# Install Graphviz for rendering
# macOS:
brew install graphviz
# Ubuntu:
sudo apt-get install graphviz
5.2 Project Structure
team-interaction-audit/
├── data/
│ ├── teams.yaml # Team registry
│ └── interactions.yaml # Interaction log
├── output/
│ ├── graph.dot # Generated DOT file
│ ├── graph.svg # Rendered visualization
│ └── report.md # Friction analysis
├── scripts/
│ ├── collect.py # Data collection helper
│ ├── generate.py # Graph generation
│ └── analyze.py # Metrics calculation
└── README.md
5.3 The Core Question You’re Answering
“Where does the ‘Coordination Tax’ live in our organization, and why is it so high?”
Most coordination overhead is invisible until you map it. It feels like “work,” but it’s actually “waste” generated by poorly defined boundaries. Your audit will make the invisible visible.
5.4 Concepts You Must Understand First
Stop and research these before coding:
- The Three Interaction Modes
- When is Collaboration appropriate? (Discovery phase, new boundaries)
- When should you switch to X-as-a-Service? (After boundaries stabilize)
- What is Facilitation? (Enabling team helping, not doing)
- Book Reference: “Team Topologies” Ch. 7 - Skelton & Pais
- Wait Time vs. Processing Time
- A 1-hour task takes 3 days because of queues and handoffs
- Book Reference: “The Phoenix Project” - Gene Kim
- Graph Theory Basics
- What is in-degree? (How many teams depend on you)
- What is a cycle? (A -> B -> C -> A circular dependency)
- Reference: Any algorithms textbook, Chapter on Graphs
5.5 Questions to Guide Your Design
Before implementing, think through these:
Data Collection
- How will you track “interaction”? (Slack data, calendar invites, surveys?)
- How do you distinguish a social chat from a technical dependency?
- Can you automate collection, or is manual survey better for accuracy?
Visualization
- How can you represent “Wait Time” on a graph?
- What happens if Team A says they interact with Team B, but Team B disagrees?
- Should you show individual interactions or aggregate by week?
Analysis
- What threshold defines “High Friction”?
- How do you handle seasonal variations (release week vs. normal week)?
- Should you weight interactions by seniority of people involved?
5.6 Thinking Exercise
The “Silent Meeting” Test
Imagine a week where no team is allowed to have a meeting with another team. They can only communicate via tickets and documented APIs.
Questions while analyzing:
- Which teams would stop functioning immediately?
- Which teams would continue delivering without issue?
- The teams that stop are your “High Coupling” points. Are those boundaries correct?
Write down:
- 3 teams that would thrive in “silent mode”
- 3 teams that would collapse without meetings
- For each collapsing team, what is missing? (Documentation? API? Clear ownership?)
5.7 Hints in Layers
Hint 1: Start with the Org Chart List every team in the department. Don’t look at names; look at what they actually do. Many “teams” are really part of the same functional unit.
Hint 2: Track the Handoffs Pick one feature that shipped recently and trace its path from “Idea” to “Production.” Every time it moves from one person/team to another, that’s an interaction. Count them.
Hint 3: Categorize by Intent For each interaction you’ve identified, ask: Is Team A helping Team B (Facilitation), building with Team B (Collaboration), or providing a tool for Team B (X-as-a-Service)?
Hint 4: Use DOT or Mermaid Don’t get stuck in UI tools. Write the interactions as text:
TeamA -> TeamB [label="High Friction"];
Let a tool render it. This makes your graph version-controllable and reproducible.
5.8 The Interview Questions They’ll Ask
Prepare to answer these:
- “How do you identify if two teams are too tightly coupled?”
- Look for: daily syncs, shared on-call, PRs requiring both teams’ approval
- “What are the signs that a team boundary is in the wrong place?”
- Constant coordination meetings, features requiring 3+ teams, no one knows who owns a component
- “Explain Conway’s Law and how it impacts system design.”
- Organization structure predicts code structure. Want microservices? Need small independent teams first.
- “How do you measure the cognitive load of a team?”
- Survey-based (perceived load), objective (number of services owned, on-call burden)
- “When is ‘Collaboration’ actually a bad thing?”
- When it becomes permanent. Collaboration should be time-boxed discovery, not ongoing dependency.
5.9 Books That Will Help
| Topic | Book | Chapter |
|---|---|---|
| Interaction Modes | “Team Topologies” by Skelton & Pais | Ch. 7: Choose Team Interaction Modes |
| Value Stream Mapping | “Learning to See” by Mike Rother | Entire book |
| Wait Time & Flow | “The Phoenix Project” by Kim et al. | Parts 2-3 |
| Conway’s Law | “Team Topologies” | Ch. 2: Conway’s Law and Why It Matters |
5.10 Implementation Phases
Phase 1: Manual Survey (2-3 hours)
- Create a simple spreadsheet with columns: From Team, To Team, Type, Frequency
- Interview 3-5 team leads
- Ask: “Who do you talk to every day? Every week? Rarely?”
Phase 2: Data Enrichment (2-3 hours)
- Convert spreadsheet to YAML format
- Add friction scores (1-10) based on your judgment
- Categorize each interaction by Team Topologies mode
Phase 3: Graph Generation (2-3 hours)
- Write a simple script to convert YAML to DOT format
- Render the graph with Graphviz
- Iterate on layout until it’s readable
Phase 4: Analysis & Report (2-3 hours)
- Identify top 3 friction hotspots
- For each hotspot, write a recommendation
- Create a one-page summary for stakeholders
5.11 Key Implementation Decisions
| Decision | Option A | Option B | Recommendation |
|---|---|---|---|
| Data source | Automated (Slack API) | Manual (Surveys) | Start manual, automate later |
| Graph format | DOT | Mermaid | DOT for control, Mermaid for simplicity |
| Friction scoring | Objective (msg count) | Subjective (1-10 rating) | Both, then correlate |
| Scope | All teams | One value stream | One value stream first |
6. Testing Strategy
Unit Tests
- Graph generation produces valid DOT syntax
- Friction score calculation is consistent
Integration Tests
- End-to-end: YAML input → rendered graph
- Report generation includes all high-friction pairs
Validation Tests
- Show graph to interviewed team leads
- Ask: “Does this match your experience?”
- Iterate based on feedback
7. Common Pitfalls & Debugging
| Problem | Symptom | Root Cause | Fix |
|---|---|---|---|
| Graph is unreadable | 50+ crossing lines | Too many teams in scope | Limit to one value stream |
| Missing interactions | Team says “we never talk” but they do | Survey didn’t capture async communication | Check Slack channel membership |
| Skewed data | One team appears as bottleneck | Survey was conducted during incident | Collect data over 2+ weeks |
| Subjective friction | Team A says “low friction” Team B says “high” | Different expectations | Interview both teams together |
8. Extensions & Challenges
Extension 1: Temporal Analysis
Track interactions over 4 weeks. Identify patterns:
- Does friction spike during release week?
- Are there “seasonal” dependencies?
Extension 2: Automated Collection
Integrate with Slack API to count cross-team messages. Compare to survey data.
Extension 3: Simulation
Build a model that predicts friction if you move a service from Team A to Team B.
Extension 4: Compare to Code
Generate a code dependency graph. Overlay on team interaction graph. Do they match?
9. Real-World Connections
How Big Tech Does This:
- Google: Uses internal tooling to track cross-team code reviews
- Spotify: Famously visualized their “Guild” and “Squad” model
- Amazon: Two-Pizza Rule was explicitly about reducing coordination
What Happens Without This:
- “Distributed Monolith”: Microservices that require 10 teams to deploy
- “Incident Ping-Pong”: No one knows who owns the bug
- “Meeting Creep”: 30 hours/week spent aligning, 10 hours shipping
10. Resources
Tools
- Graphviz - Graph rendering
- Mermaid Live Editor - Web-based diagram creation
- NetworkX - Python graph analysis library
Articles
Related Projects in This Series
- P02: Team Service Interface - Define what your team provides
- P08: Dependency Visualizer - Code-level dependency mapping
11. Self-Assessment Checklist
Before considering this project complete, verify:
- I can explain Conway’s Law without looking at notes
- I know the three Team Topologies interaction modes and when to use each
- My graph is readable (< 20 crossing lines)
- I’ve identified at least 3 high-friction interactions
- Each high-friction interaction has a recommendation
- At least one team lead has validated the graph matches reality
- The graph is version-controlled (DOT/YAML files checked in)
12. Submission / Completion Criteria
This project is complete when you have:
- teams.yaml - Registry of at least 5 teams
- interactions.yaml - At least 15 documented interactions
- graph.svg - Rendered visualization
- report.md - Analysis with:
- Top 3 friction hotspots
- Recommendation for each
- Comparison to formal org chart
- Validation - At least one stakeholder has reviewed and provided feedback
Next Project: P02: Team Service Interface