added updated design docs
added some comments
merge