@shaykec/bridge 0.4.24 → 0.4.26

package/modules/system-design/module.yaml

@@ -0,0 +1,46 @@
+slug: system-design
+title: "System Design -- From Requirements to Architecture"
+version: 1.0.0
+description: "Master the system design interview framework and scalable distributed architecture."
+category: architecture
+tags: [system-design, architecture, scalability, distributed-systems, infrastructure]
+difficulty: advanced
+
+xp:
+  read: 20
+  walkthrough: 50
+  exercise: 30
+  quiz: 25
+  quiz-perfect-bonus: 15
+  game: 25
+  game-perfect-bonus: 15
+
+time:
+  quick: 5
+  read: 25
+  guided: 60
+
+prerequisites: [api-design]
+related: [adr-writing, design-patterns]
+
+triggers:
+  - "How do I design a scalable system?"
+  - "What is system design?"
+  - "How do I handle millions of users?"
+  - "What are the key components of distributed systems?"
+
+visuals:
+  diagrams: [diagram-mermaid, diagram-architecture]
+  quiz-types: [quiz-drag-order, quiz-matching]
+  game-types: [scenario]
+  playground: bash
+  web-embeds: true
+  slides: true
+
+sources:
+  - url: "https://github.com/donnemartin/system-design-primer"
+    label: "System Design Primer"
+    type: docs
+  - url: "https://dataintensive.net/"
+    label: "Designing Data-Intensive Applications"
+    type: docs

package/modules/system-design/quick-ref.md

@@ -0,0 +1,59 @@
+# System Design Quick Reference
+
+## Interview Framework
+
+1. **Requirements** — Functional + non-functional (scale, latency, availability)
+2. **Estimation** — DAU, QPS, storage (back-of-envelope)
+3. **High-level design** — Boxes and arrows, API, data flow
+4. **Deep dive** — 2–3 components in detail
+5. **Bottlenecks** — SPOFs, scale limits, mitigations
+
+## CAP Theorem
+
+- **C**onsistency, **A**vailability, **P**artition tolerance — pick two
+- In practice: **CP** (banking) or **AP** (social feeds)
+
+## Caching
+
+| Strategy | When |
+|----------|------|
+| Cache-aside | App manages cache; on miss → DB → populate |
+| Write-through | Write to cache + DB together |
+| CDN | Static assets, edge |
+| Redis/Memcached | App-layer hot data |
+
+## Database
+
+| Type | Use case |
+|------|----------|
+| SQL | ACID, joins, relational |
+| NoSQL document | Flexible schema, high write |
+| NoSQL key-value | Simple lookups |
+| Sharding | Partition by key (user_id, etc.) |
+| Replication | Read replicas for scale |
+
+## Load Balancing
+
+- Round-robin, least connections, consistent hashing
+- Health checks to remove unhealthy nodes
+
+## Message Queues
+
+- Decouple producers/consumers
+- Async processing, buffering, retries
+- Kafka, RabbitMQ, SQS
+
+## Rate Limiting
+
+- Token bucket, sliding window, fixed window
+- `429 Too Many Requests`, `Retry-After` header
+
+## Microservices vs Monolith
+
+- Start monolith; extract when boundaries clear
+- Per-service DB, independent deploy
+
+## Consistent Hashing
+
+- Ring of hash space; nodes own ranges
+- Add/remove node → minimal key movement

package/modules/system-design/quiz.md

@@ -0,0 +1,102 @@
+# System Design Quiz
+
+## Question 1
+
+In the CAP theorem, partition tolerance means:
+
+A) The system can split into multiple data centers
+B) The system continues to operate despite network partitions
+C) Data is partitioned across shards
+D) You can choose between consistency and availability
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Partition tolerance means the system still works when network links fail or messages are lost. In practice, you must assume partitions happen; you choose between CP (consistency + partition tolerance) or AP (availability + partition tolerance). -->
+
+## Question 2
+
+Cache-aside (lazy loading) means:
+
+A) The cache is populated when the app starts
+B) The app checks the cache first; on miss, fetches from DB and populates cache
+C) Writes go to cache first, then DB
+D) The cache sits alongside the database
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Cache-aside: app reads from cache first. On miss, app fetches from DB, writes to cache, returns to client. The app is responsible for cache population. -->
+
+## Question 3
+
+When would you choose a message queue over synchronous HTTP calls?
+
+A) When you need real-time responses
+B) When you want to decouple services and handle traffic spikes asynchronously
+C) When the database is too slow
+D) When you need strong consistency
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Message queues decouple producers and consumers. Async processing handles spikes, retries, and offloads heavy work. They trade latency for reliability and decoupling. -->
+
+## Question 4
+
+Consistent hashing is used to:
+
+A) Encrypt data across nodes
+B) Minimize key reassignment when nodes are added or removed
+C) Balance load evenly across all nodes
+D) Ensure data consistency in a distributed database
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Consistent hashing maps keys to a ring. When a node joins/leaves, only keys in that node's range need to move. Used in CDNs, caches, and distributed storage. -->
+
+## Question 5
+
+For a URL shortener with 10:1 read:write ratio, the main scalability concern is:
+
+A) Write throughput to the database
+B) Read throughput — use caching aggressively
+C) Storage capacity
+D) Network latency between regions
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: With 10:1 read:write, reads dominate. Caching (CDN, app cache) for hot short URLs dramatically reduces DB read load. Writes are much lower volume. -->
+
+## Question 6
+
+Fan-out on write (precomputing feeds) is preferable when:
+
+A) Most users have millions of followers
+B) Most users have few followers and read frequently
+C) Writes are more frequent than reads
+D) You need real-time consistency
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Fan-out on write: when a user posts, push to all followers' feeds. Good when followers are modest in number; reads are fast. Bad for celebrities (millions of followers). -->
+
+## Question 7
+
+<!-- VISUAL: quiz-drag-order -->
+
+Put these system design interview steps in the recommended order:
+
+A) Scale the design (bottlenecks, sharding, caching)
+B) Clarify requirements and constraints
+C) Design high-level components
+D) Deep dive on 1–2 critical components
+E) Identify and address trade-offs
+
+<!-- ANSWER: B,C,A,D,E -->
+<!-- EXPLANATION: Clarify requirements first. Design high-level components. Scale the design (handle load). Deep dive on critical parts. Discuss trade-offs and alternatives. -->
+
+## Question 8
+
+<!-- VISUAL: quiz-matching -->
+
+Match each scaling technique to its description:
+
+A) Horizontal scaling → 1) Add more machines to handle load
+B) Vertical scaling → 2) Add more RAM, CPU to existing machines
+C) Sharding → 3) Partition data across multiple databases by key
+D) Load balancer → 4) Distribute requests across multiple servers
+
+<!-- ANSWER: A1,B2,C3,D4 -->
+<!-- EXPLANATION: Horizontal = add more nodes. Vertical = add resources to existing nodes. Sharding = partition data by key. Load balancer = distribute incoming requests. -->

package/modules/system-design/resources.md

@@ -0,0 +1,46 @@
+# System Design — Resources
+
+## Videos
+
+- [System Design Interview — Gaurav Sen](https://www.youtube.com/playlist?list=PLMCXHnjXnTnvo6alSjVkgxV-VH6EPyvoX) — Structured approach and common problems.
+- [ByteByteGo — System Design](https://www.youtube.com/@ByteByteGo) — Visual explanations of distributed systems.
+- [Gaurav Sen — CAP Theorem](https://www.youtube.com/watch?v=k-Yaq8AHlFA) — CAP explained clearly.
+- [Tech Dummies — System Design](https://www.youtube.com/playlist?list=PLkQkbY7JN6BpnK7Xn-HVXy4cR-LxxHrBQ) — Interview-style walkthroughs.
+
+## Articles and Guides
+
+- [System Design Primer](https://github.com/donnemartin/system-design-primer) — Comprehensive GitHub repo with topics, patterns, and exercises.
+- [High Scalability](http://highscalability.com/) — Case studies and patterns from real systems.
+- [Martin Fowler — CQRS](https://martinfowler.com/bliki/CQRS.html) — Command Query Responsibility Segregation.
+- [Martin Fowler — Event Sourcing](https://martinfowler.com/eaaDev/EventSourcing.html) — Event sourcing pattern.
+- [InfoQ — Distributed Systems](https://www.infoq.com/distributed-systems/) — Articles on distributed systems.
+
+## Books
+
+- **Designing Data-Intensive Applications** by Martin Kleppmann — The definitive guide (DDIA).
+- **System Design Interview** by Alex Xu — Two-volume interview preparation.
+- **Building Microservices** by Sam Newman — Microservices architecture.
+
+## Tools and References
+
+- [Consistent Hashing — Original Paper](https://www.akamai.com/blog/performance/what-is-consistent-hashing) — Akamai's explanation.
+- [Redis Documentation — Caching Strategies](https://redis.io/docs/manual/patterns/) — Cache patterns with Redis.
+- [AWS Well-Architected Framework](https://aws.amazon.com/architecture/well-architected/) — Scalability and reliability best practices.
+
+## Podcasts
+
+- [Software Engineering Daily — Distributed Systems](https://softwareengineeringdaily.com/category/all-episodes/exclusive-content/distributed-systems/) — Technical deep dives on databases, caching, messaging.
+- [The Pragmatic Engineer Podcast](https://newsletter.pragmaticengineer.com/) — Gergely Orosz on large-scale system decisions.
+- [InfoQ Podcast](https://www.infoq.com/podcasts/) — Architecture and scalability interviews with industry leaders.
+
+## Interactive and Visual
+
+- [ByteByteGo — System Design Visuals](https://bytebytego.com/) — Alex Xu's animated system design diagrams and newsletters.
+- [Excalidraw](https://excalidraw.com/) — Collaborative whiteboard for sketching architecture diagrams.
+- [System Design Primer — Anki Flashcards](https://github.com/donnemartin/system-design-primer#anki-flashcards) — Spaced-repetition cards for system design concepts.
+
+## Courses
+
+- [MIT 6.824 — Distributed Systems (free)](https://pdos.csail.mit.edu/6.824/) — Lecture videos, labs on Raft, MapReduce, and more.
+- [Grokking the System Design Interview](https://www.designgurus.io/course/grokking-the-system-design-interview) — Structured walkthrough of common design problems.
+- [Educative — System Design for Developers](https://www.educative.io/courses/grokking-modern-system-design-interview-for-engineers-managers) — Interactive text-based course with diagrams.

package/modules/system-design/walkthrough.md

@@ -0,0 +1,90 @@
+# System Design Walkthrough — Learn by Doing
+
+## Before We Begin
+
+<!-- hint:slides topic="System design process: requirements, estimation, high-level architecture, database choice, scaling, and CAP theorem" slides="6" -->
+
+**Diagnostic Question:** When someone says "design a system," what do you think they mean first — the boxes and arrows, the data model, the APIs, or something else? Why might different people answer differently?
+
+**Checkpoint:** You recognize that system design starts with understanding the problem before drawing anything. The "right" starting point depends on context.
+
+---
+
+## Step 1: Clarify Requirements
+
+<!-- hint:progress -->
+
+**Task:** You're asked to "design a URL shortener." Write down 3 functional and 3 non-functional requirements you'd ask the interviewer to clarify.
+
+**Question:** Why does it matter whether the short URLs are 6 chars or 8 chars? What about read vs write ratio?
+
+**Checkpoint:** You have a clear list of assumptions (scale, TTL, analytics, etc.).
+
+---
+
+## Step 2: Back-of-Envelope Estimation
+
+**Task:** Assume 100M URLs/month. Estimate: (a) writes per second, (b) reads per second (assume 10:1 read:write), (c) storage for 5 years (50 bytes per record).
+
+**Question:** What rounding and approximations did you use? How accurate do estimates need to be at this stage?
+
+**Checkpoint:** You have rough QPS and storage numbers that bound the problem.
+
+---
+
+## Step 3: High-Level Diagram
+
+<!-- hint:diagram mermaid-type="flowchart" topic="URL shortener architecture" -->
+
+**Embed:** https://excalidraw.com/
+
+**Task:** Draw a high-level architecture for the URL shortener: client, API, app servers, cache, database. Include the flow for "create short URL" and "resolve short URL."
+
+**Question:** Where would a cache sit, and what keys would it use? What happens on a cache miss?
+
+**Checkpoint:** You have a boxes-and-arrows diagram with clear data flow.
+
+---
+
+## Step 4: Choose a Database
+
+<!-- hint:buttons type="single" prompt="Which database would you choose for a URL shortener?" options="SQL for consistency,NoSQL for scale,Depends on requirements" -->
+
+**Task:** Would you use SQL or NoSQL for the URL shortener? Justify. Consider: schema, scale, consistency needs, operational simplicity.
+
+**Question:** What if the requirement was "we need to list all URLs created by user X"? Does that change your choice?
+
+**Checkpoint:** You can articulate tradeoffs between SQL and NoSQL for this use case.
+
+---
+
+## Step 5: Handle Scale and Bottlenecks
+
+**Task:** Identify 2 bottlenecks: (1) DB write throughput, (2) cache stampede when a viral link gets massive traffic. Propose mitigations.
+
+**Question:** What is a cache stampede? How would you prevent it (e.g., lock, probabilistic early expiration)?
+
+**Checkpoint:** You can name concrete techniques (sharding, queuing, cache locking) for each bottleneck.
+
+---
+
+## Step 6: CAP and Consistency
+
+<!-- hint:card type="concept" title="CAP Theorem" -->
+<!-- hint:celebrate -->
+
+**Task:** For the URL shortener, would you choose CP or AP? Why? What would "eventual consistency" mean for a redirect?
+
+**Question:** Can a user tolerate seeing a 404 for a few seconds after creating a link? What about a banking transfer?
+
+**Checkpoint:** You can explain why this system likely chooses AP and what tradeoffs that implies.
+
+---
+
+## Step 7: Rate Limiting
+
+**Task:** Design a rate limit for the "create short URL" endpoint: 10 req/min per IP. Describe the algorithm (fixed window, sliding window, or token bucket) and what headers to return.
+
+**Question:** What happens if a user hits the limit? Should you return 429 immediately or queue the request?
+
+**Checkpoint:** You have a concrete rate-limiting strategy and response format.

package/modules/team-topologies/content.md

@@ -0,0 +1,166 @@
+# Team Topologies — Structuring Teams for Fast Flow
+
+<!-- hint:slides topic="Team topologies: Conway's Law, four team types (stream-aligned, enabling, complicated-subsystem, platform), interaction modes, and cognitive load" slides="6" -->
+
+## Conway's Law
+
+**"Organizations design systems that mirror their communication structure."** — Melvin Conway (1967)
+
+If you have three teams working on a system, you'll get a three-part system. If teams don't talk to each other, the architecture will have hard boundaries where they don't. Conway's Law isn't a suggestion—it's an observation of how organizations actually work. The implication: **change the team structure to change the system architecture.**
+
+## The Four Fundamental Team Types
+
+From *Team Topologies* by Skelton & Pais:
+
+```mermaid
+flowchart TB
+    subgraph TeamTypes[Four Team Types]
+        SA[Stream-Aligned]
+        P[Platform]
+        E[Enabling]
+        CS[Complicated-Subsystem]
+    end
+    subgraph Modes[Interaction Modes]
+        Collab[Collaboration]
+        XaaS[X-as-a-Service]
+        Facil[Facilitating]
+    end
+    SA -->|XaaS| P
+    E -->|Facil| SA
+    CS -->|Collab| SA
+```
+
+```mermaid
+flowchart TB
+    subgraph Types["Four Team Types"]
+        SA[Stream-Aligned Team]
+        P[Platform Team]
+        E[Enabling Team]
+        CS[Complicated-Subsystem Team]
+    end
+
+    SA -->|"owns full stream"| P
+    P -->|"provides platform"| SA
+    E -->|"helps learn"| SA
+    CS -->|"owns complex domain"| SA
+```
+
+| Type | Purpose | Example |
+|------|---------|---------|
+| **Stream-aligned** | Own a full stream of value (e.g., checkout, search). They build, run, and evolve it. | "Checkout team" owns checkout end-to-end |
+| **Platform** | Provide internal services, APIs, tooling so stream-aligned teams can ship without reinventing the wheel. | Platform team provides auth, deploy pipelines, observability |
+| **Enabling** | Help stream-aligned teams learn new skills or adopt new tech. Temporary; they enable then step back. | Enable team helps adopt Kubernetes |
+| **Complicated-subsystem** | Own a highly specialized domain (e.g., ML model, cryptography) that requires deep expertise. | Team owns payment compliance and PCI |
+
+**Stream-aligned teams are the default.** Platform, enabling, and complicated-subsystem teams exist to *support* them.
+
+## The Three Interaction Modes
+
+How teams work together matters as much as team type:
+
+```mermaid
+flowchart LR
+    subgraph Modes["Interaction Modes"]
+        C[Collaboration]
+        X[X-as-a-Service]
+        F[Facilitating]
+    end
+
+    C -->|"high trust, discover together"| X
+    X -->|"clear API, SLA"| F
+    F -->|"teach, then step back"| C
+```
+
+| Mode | When to Use | What It Looks Like |
+|------|-------------|-------------------|
+| **Collaboration** | Discovery, new domain, high ambiguity | Two teams work side-by-side; shared goals; flexible boundaries |
+| **X-as-a-Service** | Stable, well-defined interface | Platform team provides a service; stream-aligned team consumes via API/SLA; low touch |
+| **Facilitating** | Learning, adoption, transition | Enabling team teaches and supports; stream-aligned team learns; enabling steps back when done |
+
+**Default to X-as-a-Service** for platform teams. Collaboration is expensive—use it when discovery is needed. Facilitating is time-bound.
+
+## Cognitive Load: The Key Constraint
+
+Teams can only hold so much in their heads. **Cognitive load** has three dimensions:
+
+1. **Intrinsic** — inherent complexity of the domain (e.g., payments is hard)
+2. **Extraneous** — unnecessary complexity from tooling, process, unclear ownership
+3. **Germane** — productive learning that improves the team over time
+
+**Goal:** Minimize extraneous, manage intrinsic, maximize germane. If a team's cognitive load is too high, they'll cut corners, create tech debt, or burn out. Splitting a team or adding a platform team can *reduce* load by simplifying what each team must understand.
+
+## Team Size: Two-Pizza Rule and Dunbar
+
+- **Two-pizza rule** (Amazon): Team should be feedable by two pizzas—roughly 5–9 people. Larger teams need more coordination.
+- **Dunbar's number:** Humans can maintain ~150 meaningful relationships, but effective *working* teams are typically 7±2. Beyond that, sub-teams form informally—design for it explicitly.
+
+**When to split:** When cognitive load is too high, when wait times for decisions grow, or when the team naturally divides into sub-domains.
+
+## Team APIs
+
+Teams interact through **APIs**—not just HTTP, but contracts: "We provide X; you consume Y; here's the SLA." A team API includes:
+
+- **Documentation** — What we offer, how to use it
+- **SLA** — Uptime, latency, support
+- **Versioning** — How we evolve without breaking consumers
+- **Support** — Who to ask, how to escalate
+
+Platform teams should have clear team APIs so stream-aligned teams can self-serve.
+
+## Evolving Team Structures
+
+Team topologies aren't static. As the product and organization evolve:
+
+- **Early stage:** Few stream-aligned teams; maybe one platform person
+- **Growth:** Add platform team when stream-aligned teams duplicate work
+- **Scale:** Add enabling teams for big transitions (e.g., cloud migration)
+- **Mature:** Complicated-subsystem teams when a domain requires dedicated expertise
+
+**Avoid the Inverse Conway Maneuver pitfall:** Don't reorganize to "match" a desired architecture without also changing communication and incentives. Structure and behavior must align.
+
+## Common Pitfalls
+
+| Pitfall | What Goes Wrong | Better Approach |
+|---------|-----------------|-----------------|
+| **Too many collaboration modes** | Everyone needs to work with everyone; meetings explode | Default to X-as-a-Service; limit collaboration to true discovery |
+| **Platform team does project work** | Platform becomes a bottleneck; stream-aligned teams wait | Platform provides capabilities; stream-aligned teams build features |
+| **Enabling never steps back** | Enabling team becomes permanent; stream-aligned doesn't own | Enabling has an exit criteria; handoff and step back |
+| **Ignoring cognitive load** | Teams are overwhelmed; quality drops | Split teams or add platform; simplify ownership |
+| **Reorg without behavior change** | New org chart, same silos | Change incentives, APIs, and communication patterns |
+
+## Four Team Types — Visual Summary
+
+```mermaid
+flowchart TB
+    subgraph StreamAligned["Stream-Aligned (default)"]
+        SA1[Own full stream]
+        SA2[Build, run, evolve]
+    end
+
+    subgraph Platform["Platform"]
+        P1[Internal services, APIs]
+        P2[X-as-a-Service to streams]
+    end
+
+    subgraph Enabling["Enabling"]
+        E1[Teach, support]
+        E2[Step back when done]
+    end
+
+    subgraph Complicated["Complicated-Subsystem"]
+        C1[Specialized domain]
+        C2[Deep expertise required]
+    end
+
+    Platform --> StreamAligned
+    Enabling --> StreamAligned
+    Complicated --> StreamAligned
+```
+
+## Key Takeaways
+
+1. **Conway's Law** — Structure and architecture are linked; change one to change the other.
+2. **Stream-aligned first** — Default team type; others support them.
+3. **Interaction modes** — Collaboration (discovery), X-as-a-Service (default), Facilitating (learning).
+4. **Cognitive load** — The key constraint; design to reduce it.
+5. **Team APIs** — Clear contracts between teams enable autonomy.

package/modules/team-topologies/exercises.md

@@ -0,0 +1,85 @@
+# Team Topologies — Exercises
+
+## Exercise 1: Map Your Organization
+
+**Task:** Create a diagram of your engineering organization (or a representative slice). Label each team by type: stream-aligned, platform, enabling, complicated-subsystem. Draw arrows for key interactions and label the mode (collaboration, X-as-a-Service, facilitating).
+
+**Validation:**
+- [ ] All teams classified
+- [ ] Key interactions shown with mode labels
+- [ ] At least one mismatch or improvement opportunity noted
+
+**Hints:**
+1. Stream-aligned = owns a full value stream (e.g., "checkout," "search")
+2. Platform = provides services/tooling for other teams
+3. Enabling = temporary; helps teams learn then steps back
+4. Complicated-subsystem = highly specialized domain
+
+---
+
+## Exercise 2: Design a Platform Team API
+
+**Task:** You're creating a platform team that will provide: CI/CD pipelines, observability (metrics, logs, traces), and a shared auth library. Write a one-page "team API" document: what each offering is, how to consume it, SLA (e.g., 99.9% uptime), and support path.
+
+**Validation:**
+- [ ] Each capability is defined
+- [ ] Consumption path is clear (docs, examples, onboarding)
+- [ ] SLA and support model specified
+- [ ] A stream-aligned team could self-serve from this doc
+
+**Hints:**
+1. SLA: What does "platform down" mean? Response time for support?
+2. Versioning: How do we evolve without breaking consumers?
+3. Onboarding: Link to runbooks, slack channel, office hours
+
+---
+
+## Exercise 3: Cognitive Load Assessment
+
+**Task:** Pick a team (real or hypothetical). List 5 sources of cognitive load. Classify each as intrinsic, extraneous, or germane. For each extraneous source, propose one change to reduce it.
+
+**Validation:**
+- [ ] 5 sources identified
+- [ ] Each classified correctly
+- [ ] At least 2 extraneous sources with proposed fixes
+- [ ] Fixes are concrete and actionable
+
+**Hints:**
+1. Intrinsic: domain complexity (payments, ML, crypto)
+2. Extraneous: unclear ownership, brittle tooling, excessive context-switching
+3. Germane: learning a new system, deliberate practice
+4. Fixes: simplify ownership, add platform, reduce meetings
+
+---
+
+## Exercise 4: When to Add a Platform Team
+
+**Task:** You have 3 stream-aligned teams. Each has built its own deploy pipeline, logging, and error tracking—slightly different in each case. Write a short proposal: when and why to add a platform team. Include: trigger (what signals "now"?), scope (what does platform own?), and transition plan (how do stream-aligned teams migrate?).
+
+**Validation:**
+- [ ] Clear trigger for adding platform
+- [ ] Scope is defined (what platform owns vs. streams)
+- [ ] Transition plan addresses "how do we get there"
+- [ ] Proposal is 1 page or less
+
+**Hints:**
+1. Trigger: duplication, inconsistency, long onboarding for new teams
+2. Scope: start with highest-leverage (deploy? observability?)
+3. Transition: platform builds v1; streams migrate over 2–3 months; deprecate old
+
+---
+
+## Exercise 5: Interaction Mode Mismatch
+
+**Task:** Describe a scenario where two teams use the *wrong* interaction mode. Example: platform and stream-aligned in constant collaboration when X-as-a-Service would work. What are the symptoms? What would need to change to fix it?
+
+**Validation:**
+- [ ] Scenario is concrete (teams, domain, current mode)
+- [ ] Wrong mode is justified (why is it a problem?)
+- [ ] Correct mode identified
+- [ ] Change plan includes: new API, SLA, communication pattern
+
+**Hints:**
+1. Collaboration when X-as-a-Service would work: everyone in every meeting, no clear API
+2. Symptoms: platform is bottleneck, stream-aligned teams wait
+3. Fix: define team API, document, establish SLA, reduce ad-hoc communication

package/modules/team-topologies/module.yaml

@@ -0,0 +1,41 @@
+slug: team-topologies
+title: "Team Topologies — Structuring Teams for Fast Flow"
+version: 1.0.0
+description: "Design teams for fast flow: Conway's Law, four team types, three interaction modes, and cognitive load."
+category: leadership
+tags: [team-topologies, organization-design, team-structure, conways-law, platform-teams]
+difficulty: advanced
+
+xp:
+  read: 20
+  walkthrough: 50
+  exercise: 30
+  quiz: 25
+  quiz-perfect-bonus: 15
+
+time:
+  quick: 5
+  read: 25
+  guided: 60
+
+prerequisites: []
+related: [system-design, one-on-ones]
+
+triggers:
+  - "How should I structure engineering teams?"
+  - "What are team topologies?"
+  - "What is Conway's Law?"
+  - "What are platform teams?"
+
+visuals:
+  diagrams: [diagram-mermaid, diagram-architecture]
+  quiz-types: [quiz-matching, quiz-timed-choice]
+  slides: true
+
+sources:
+  - label: "Team Topologies by Skelton & Pais"
+    type: book
+    url: "https://teamtopologies.com"
+  - label: "Conway's Law (original paper)"
+    type: article
+    url: "https://www.melconway.com/Home/Committees_Paper.html"