lots of refactoring to include score in entities and improve the readme