Architecture Decision Records

Design decisions are recorded once, with their reasoning, instead of being re-argued in review. When a change contradicts one of these, the ADR is what to update.

The records themselves live in the repository, next to the code they describe, at docs/adr/. They are working documents written in Russian, and they are kept in the repository rather than mirrored here so that a decision and the code implementing it move together.

The records

ADR	Subject	What it decides
001	DAP wire types	generating protocol types from the schema instead of hand-writing them
002	DAP transport, codec and request correlation	stdio and TCP, Content-Length framing, pairing responses with requests
003	Debugger Core state model	the command / event reducer, and discarding stale responses
004	GUI framework	egui, and the constraints that follow — including row virtualisation
005	Source frontend protocol and IPC	the editor boundary, the Unix socket, the hello snapshot
006	Variable tree	lazy loading, pagination, and caching per stop generation
007	Raising the window on a stop	one raise per stop generation, and what it costs
008	Native PHP/Xdebug transport	shipping our own DBGp adapter instead of depending on a Node bridge
009	The visual layer	palette, density, fonts, and the contrast thresholds enforced by tests

How they relate to this site

Several pages here summarise an ADR's conclusion without its reasoning:

Page	Related ADR
DAP model	001, 002, 003, 006, 008
IPC	005, 007
Architecture	003, 004
Variables	006
Debugger UI	004, 009
Languages → PHP	008

Read the ADR when you need to know why, and want the alternatives that were rejected along with it.