[refactor] cleanup data structures, add docs