bug fix, refactoring and docs for server handlers