add design & refactor devs a bit
fixes for issues pointed out in ML
Merge pull request #142 from SergioCrisostomo/ml-fixes

ML fixes