---
title: Integration vs. Composition
synced_from_vault: true
vault_source: 03-living-docs/patterns/Integration-vs-Composition.md
public: true
type: pattern
tags:
  - pattern
  - philosophy
  - design
  - systems-thinking
created: 2026-02-22T00:00:00.000Z
---

## Core Concept

**Integration makes the experience better inside. Composition makes the system better alongside everything else.** These are opposing forces in system design, and the history of computing is largely the story of which won in different contexts.

- **Smalltalk chose integration:** Everything is an object, the image contains the whole world, the environment is self-contained and beautiful. But it couldn't talk to anything outside itself.
- **Unix chose composition:** Files are the universal interface, pipes connect anything to anything, each tool does one thing. The individual experience is worse, but the ecosystem is infinite.
- **The best systems find both:** Smalltalk's conceptual model implemented through Unix's compositional primitives.

---

## The Pattern

When designing a system, you face this tension at every level:

| Choice | Integration | Composition |
|---|---|---|
| **Data format** | Proprietary binary (fast, rich) | Plain text (universal, greppable) |
| **Storage** | Custom database (optimized) | Filesystem + git (composable) |
| **Protocol** | Custom API (tailored) | Standard protocol (interoperable) |
| **Environment** | All-in-one IDE (seamless) | Unix tools + editor (flexible) |
| **Knowledge** | Walled garden (curated) | Open graph (extensible) |

**The trap:** Integration feels better during demos. Composition wins over years. The enclosed system impresses on day one and frustrates on day 1,000. The composable system frustrates on day one and becomes indispensable by day 1,000.

---

## Where I've Seen It

- **Smalltalk vs. Unix:** The canonical case. Smalltalk's environment died; its ideas (OO, MVC, live inspection) were absorbed into composable systems.
- **This OS:** Markdown files in git (composition) with entity index and rituals providing the integrated experience on top. Avoids the Smalltalk trap by keeping files as the primitive.
- **WCP:** Designed as a protocol (composable — any PM system can serve it via adapter) not a product (integrated — works only with one PM tool). See [Protocol-Over-Tool](/patterns/protocol-over-tool).
- **Entity Index:** Derives structure from existing file conventions (composable) rather than requiring a proprietary schema language (integrated).
- **MCP itself:** The Model Context Protocol is composition personified — any tool can plug into any AI via a standard interface.
- **Apple vs. Microsoft (1990s):** Apple chose integration (hardware + software). Microsoft chose composition (runs on anything). Microsoft won the volume war. Apple survived by finding both (beautiful integration that also composes with standard protocols).
- **Notion vs. Obsidian:** Notion integrates (proprietary format, cloud-only, one vendor). Obsidian composes (markdown files, local-first, plugin ecosystem). Different tradeoffs, different audiences.

---

## The Design Principle

**When in doubt, compose.** You can always add integration on top of composable primitives (entity index on top of files, rituals on top of markdown). You cannot easily add composability to an integrated system (extracting data from Notion is hard; extracting data from markdown is trivial).

The hierarchy of durability:
1. **Ideas** survive across systems (Smalltalk's OO ideas live everywhere)
2. **Protocols** survive across implementations (HTTP, TCP/IP, MCP)
3. **Environments** don't survive — they get replaced

Invest in ideas and protocols. Build environments lightly and be ready for them to change.

---

## Related Patterns

- [Protocol-Over-Tool](/patterns/protocol-over-tool) — the direct application of this tension: protocols compose, tools integrate
- [Galls-Law](/patterns/galls-law) — composable systems evolve incrementally; integrated systems require big-bang adoption
- [Augmentation-Over-Automation](/patterns/augmentation-over-automation) — augmentation composes (human + AI, each doing what they're good at); automation integrates (replace the human entirely)
- [Zettelkasten-as-Object-Model](/patterns/zettelkasten-as-object-model) — atomic notes compose; monolithic documents integrate

---

## Cross-References