improvements: refactoring, tests and documentation