a bit of logic + placeholder design docs

some logic + lots of design doc excerpts as comments
for rtr are we using linked list?