Team Contracts & Governance

## What the shell is holding together A microfrontend architecture splits a single web application into several independently deployable pieces, each owned end-to-end by a different team, and stitched together at runtime by a **shell** (also called a container or host app). The shell might mount a checkout fragment inside a route, alongside a header fragment and a recommendations fragment, using a mechanism like Webpack Module Federation, single-spa, iframes, or web components. Because these pieces are compiled and deployed separately, there is no compiler pass that spans team boundaries — TypeScript in the checkout repo cannot type-check against the shell's expectations, and vice versa. The only thing standing between "this works" and "this silently breaks in production" is a contract everyone has agreed to honor. ## The three channels That contract has (at minimum) three channels. 1. **First, the props/config API:** whatever data the shell passes into a fragment at mount time — a `locale` string, a `cartId`, a callback for navigation — forms an implicit function signature that the fragment's code depends on. 2. **Second, custom events (or a pub/sub bus):** fragments communicate sideways and upward not by calling each other's internal functions but by emitting named events with a defined payload shape, e.g. a checkout fragment dispatching a `checkout:completed` CustomEvent with `{ orderId, total }` that the shell listens for to show a confirmation banner. 3. **Third, shared design tokens:** CSS custom properties or a tokens package (colors, spacing units, typography scale, breakpoints) that every fragment consumes so the seams between teams' UIs are invisible to the end user, even though the code was written by different people in different repos. ## Why it must be explicit rather than emergent The reason this needs to be explicit rather than emergent is **Conway's Law** in action: teams are organized around business capabilities (checkout, search, account) precisely so each can ship on its own cadence, without waiting for a company-wide release train. That independence is the entire point of the architecture. - But independence at the deploy layer only works if the *interface* between teams is stable even while the *implementation* behind it changes freely. - If the checkout team is free to refactor its internals but not free to silently rename an event field or add a required prop, then the shell team can build against a known shape and never has to redeploy in lockstep. - The moment a team treats their fragment's runtime behavior as an implicit, undocumented contract, they've reintroduced tight coupling through the back door — the systems are still deployed separately, but they are not actually independent, because nobody can safely change anything without grepping every consumer's source code (which may live in a repo they can't even see). ## The trade-off The trade-off is upfront cost: designing a props API, naming and documenting events, publishing a tokens package, and writing down what "breaking" means takes real design effort that a team moving fast might be tempted to skip in favor of "we'll just call into their global object." That shortcut is fast on day one and catastrophic on day ninety, when the other team ships an unrelated refactor and a production incident traces back to a coupling nobody remembered existed. ## Where it goes wrong Common failure modes include: | Failure mode | What it looks like | |---|---| | **Payload drift** | a field silently renamed or its type changed, e.g. `total: number` becoming `total: { amount, currency }` | | **Design-token drift** | a fragment hardcodes a hex color instead of consuming the token, so a rebrand only updates part of the page | | **Event-name collisions** | two teams independently choose the same custom event name for different purposes, and a listener fires on the wrong payload shape | ## How mature platforms formalize it A concrete, widely-cited real-world pattern: teams building large multi-team frontends (Zalando's Interface Framework and IKEA's microfrontend platform are both public examples) formalize fragment-to-shell communication as custom browser events with a documented, versioned payload schema, plus a shared, independently-versioned design-tokens npm package that every fragment installs as a dependency — so a rebrand or spacing-scale change propagates by a version bump rather than a coordinated multi-repo edit. The contract is the thing that makes "independently deployable" actually true rather than aspirational.