add some docs and plans for refactor