updated api design with feedback from ag_dubs
added class diagram for (my) clarification