adding documentation and comments to explain key components