updated documentation with diagrams