further consolidation, annotation and refactoring