main module code cleanup: more comments & logging, better error handling etc.