pulled this out into a top level class
mostly through documenting the whole thing