add some explanation and make config values explicit in diagrams