some refactoring and developers documentation