policy api doc for review only
Incorporating all doc comments and adding flow diagrams