BUG-5280: expand design documentation