Skip to content
MerchOS Engineering Handbook

MerchOS Engineering Handbook

How MerchOS works end-to-end. Written for a new senior engineer reading on day 1.
Start with Welcome Architecture

What this is

The MerchOS codebase has ~150 phases shipped, 116 ADRs accepted, 22 service-note deep-reads, and a dozen runbooks. That’s the canonical record. This handbook is the reading order over the record — chapters that synthesize the corpus into a narrative an engineer can actually onboard from.

What this isn’t

A replacement for ADRs, service notes, or git log. Every chapter ends with a Canonical sources footer linking to the underlying record. If a chapter contradicts the underlying record, the record wins — update the chapter, not the other way around. See ADR-0117 for the maintenance contract.

Reading paths

  • New engineer, day 1: start at Welcome and read in order through Chapter 13.
  • Specific module work: jump to the relevant chapter from the sidebar, then follow the Canonical sources footer.
  • Operational incident: jump to Operations and the runbook index there.