adding diagram

I will keep this PR open for the time being, and update it as new use cases come in.