add documentation for methods and flow