documentation improvements

Reviewer: @poolakiran

Kiran, once this is merged could you also add some docs to INTERNALS.md about
your new generic flowtable?