general refactor, revisited validations and improved README