design doc update andyet another code refactoring and cleanup