refactoring and documentation, small design changes