docs: add design notes
first stab at it, should be fairly complete
some TODOs are still pending, but it looks good enough for a first integration, we can always iterate on this later
Related to #1926 (closed)
Migrated from D4042 (view on Phabricator)