changes, refactors and bug fixes derived from PR comments