refactor and add more connect logic / docs