cleaning up code, implementing test feed data

clarifying the architecture and choices with lots of documentation and
comments.