Skip to content

WriteAmp

Write once, read many.

Deploy docs License: MIT

Read it as a site: https://jeetparekh3005.github.io/writeamp/

A working notebook on software architecture: patterns, algorithms, and the design of scalable systems, with real-world case studies and the trade-offs behind every decision.

It spans the full altitude of architectural thinking, from code-level patterns to distributed and decentralized 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, decentralized systems (DLTs, blockchain, BFT)
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 patterns
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 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; link related notes liberally.
  • 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: foundations (replication, consensus) and the core algorithms first, then the system-design method and a first product teardown, then AI systems. Decisions and cross-cutting fill in as real trade-offs come up.

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.