Chapter 60: Architecture Decisions & Publishing to ClawHub
You built the application. You understand its economics. Now you learn why it is built this way, and you publish it to the world.
This chapter has two halves. The first half is a case study in real-world architecture decisions: six pivots from "build everything ourselves" to "publish an app on the agent OS." The second half teaches you to document, version, and distribute an OpenClaw application on ClawHub.
📚 Teaching Aid
What This Chapter IS
Part A: Architecture Decisions (L1-L6)
- Six architectural pivots that led from Architecture 1 (custom brain) to Architecture 4 (MCP-first), told as case studies James traces through his own TutorClaw build
- What survived all six pivots: invariant layers (pedagogy, content, pricing) vs variant layers (infrastructure, delivery, routing)
- Eight meta-lessons grouped into three themes: structure for replacement, ship and learn, question the premise
- The Platform Inversion: the insight that learners ARE the infrastructure
Part B: Professional Practice & Distribution (L7-L10)
-
Architecture Decision Records (ADRs) as a professional practice: James writes a real ADR for TutorClaw
-
Versioning strategy: the 95% server-side update advantage and when shim updates are needed
-
Distribution strategy: ClawHub marketplace dynamics, discovery, ratings, network effects
-
Part 5 retrospective: from Consumer (Ch56) through Architect (Ch60), bridging to Part 6
-
Not the mechanics of
clawhub publish(Chapter 58 Lesson 15)
| # | Lesson | What You Learn |
|---|---|---|
| 1 | Plans Are Useless | Architecture as a sequence of decisions; the six-pivot overview |
| 2 | Pivots One and Two | Hype vs requirements; layer identification; the layer stacking anti-pattern |
| 3 | Pivots Three and Four | Testing against the most demanding requirement; the 90/10 rule; build vs right-now |
| 4 | Pivots Five and Six | Parallel tracks for different timelines; the Platform Inversion; MCP as delivery |
| 5 | What Survived | Invariant vs variant layers; designing invariants for portability |
| 6 | Eight Meta-Lessons | Three themes: structure for replacement, ship and learn, question the premise |
| 7 | Write Your First ADR | ADR format and purpose; documenting the WHY; ADR as a living document |
| 8 | Versioning and Maintenance | The 95% server-side update advantage; when shim updates are needed |
| 9 | Distribution Strategy | Marketplace dynamics; three install paths; network effects |
| 10 | Part Five Retrospective | Consumer to Architect: the five roles of Part 5; bridge to Part 6 |
| 11 | Chapter Quiz | 50 scenario-based questions across all 10 lessons |
Five Session Groups
Session 1: Architecture Case Study (L1-L4) traces six architectural pivots through James's own TutorClaw build. Each pivot is a case study, not a lecture. The student discovers the failed architecture before learning why it failed.
Session 2: Patterns and Principles (L5-L6) steps back from the pivots to find what survived and distill eight meta-lessons into three actionable themes.
Session 3: Professional Practice (L7) is the one hands-on lesson. James writes a real ADR for TutorClaw's MCP-first decision. The student writes their own.
Session 4: Distribution Strategy (L8-L9) goes beyond Ch58 L16's publishing mechanics into versioning strategy and marketplace dynamics.
Session 5: Part 5 Capstone (L10) synthesizes the entire Part 5 journey and bridges to Part 6, where students build agents from scratch with SDKs.
Prerequisites
- Chapter 58: Building TutorClaw (the application whose architecture we analyze)
- Chapter 59: The Economics Stack (the economics that validate the architecture)