Skip to content

Home

WriteAmp

Write once, read many.

Deploy docs License: MIT

Read it as a site: https://writeamp.com/

WriteAmp is the working notebook of a technical architect, written after more than a decade of building, scaling, and optimizing distributed systems. The core of it is a single idea: the discipline we built for distributed systems over the last twenty years (idempotency, backpressure, failure taxonomies, consensus) applies directly to the AI systems everyone is now rushing into production, and almost nobody is applying it.

This is for senior engineers and architects, and the people on their way there. The writing assumes you have shipped things and watched them fail.

It spans the full altitude of architectural thinking, from code-level patterns to distributed and adversarial systems, alongside the practice of it: a system-design methodology, real-world case studies (each ending in what to steal, what to avoid), cross-cutting concerns, and a decision log. It grows with whatever I'm building.

Map

Area What lives here
Foundations Theory: data systems, distributed systems, adversarial & Byzantine systems (BFT, trust boundaries, verification)
Patterns Three altitudes: code (GoF), architectural (CQRS, saga, hexagonal), distributed (outbox, idempotency)
Algorithms The toolbox: consistent hashing, bloom filters, HyperLogLog, CRDTs, merkle trees, consensus
System Design The method: estimation, component catalog, how to approach any design
AI Systems RAG, agents, extraction, agentic data, rules, LLMOps, AI architectures
Case Studies Architecture teardowns of real systems, each ending in steal / avoid
Cross-Cutting Reliability, observability, security, performance, cost
Decisions ADR log and X vs Y, when and why trade-off frameworks
Engineering Leadership Conway's law, team topologies, migration playbooks
Reading Companions that index into the topic folders (e.g. DDIA)

How to read this notebook

  • Came from an article? Start at the notebook page it links, then follow the ladder down.
  • Shipping AI to production? Start at AI Systems and follow the evals and verification thread into Foundations.
  • Studying for depth? Start at the foundations spine: the log, how systems fail, time.
  • Designing something now? Start at System Design and follow the component and decision links.

How it's organized

The notebook separates three kinds of thing, and system-design/ is the method that ties them together:

  • Knowledge that teaches the primitives: foundations/, patterns/, algorithms/, ai-systems/
  • Judgment you apply when designing: decisions/, cross-cutting/
  • Evidence of the primitives composed in the wild: case-studies/

Topics are organized by concept, not by source. Books live in reading/ as indexes that link into the topic folders, so every concept has exactly one home.

Conventions

  • One concept per file, one home per concept; every other mention links to the home.
  • Every page opens by placing itself on the altitude ladder: article (story) > pattern (recipe) > foundation (theory) > algorithm (structure).
  • Living pages carry a "last compacted" date; articles are dated and never retroactively edited.
  • Every case study ends with a Steal / Avoid section (template).
  • Every non-trivial choice gets an ADR in decisions/ (template).
  • Diagrams are generated, not hand-drawn (see below), and referenced, not inlined.

Diagrams

Architecture diagrams use the house engine in tools/diagram-forge/: write a small JSON spec, get an animated diagram in one locked style (Neo-brutal on graph paper; pulse = a call, dashed = async, thick = hot path). It exports a static SVG for GitHub and the MkDocs site. The /diagram-forge skill turns a plain-language description of a system into a spec and builds it.

Roadmap

Depth over breadth, one node at a time. The primary workstream is the transfer-list series in patterns/distributed/: each installment ships an article, a pattern page, and a Gotham S&L incident. Foundations, algorithms, and decisions pages are written when an installment needs to link to them, spine first. Case studies follow the log thread: Cassandra, then Kafka, then the AI group.


Run the site locally with pip install -r requirements-docs.txt && mkdocs serve; pushes to main auto-deploy via GitHub Actions. Contributions welcome (CONTRIBUTING) under the MIT license.