added more comments, test script, and conceptual notes