walkthrough the code

added as a separate PR on the AGIOS-108 branch so the changes are visible.