Document how the code works

[pmcelhaney]

This is a reminder to myself. Each directory should have a README.md that explains how the code works at a high level, maybe a one line description of each file, and some UML diagrams.

Also there should be a document somewhere that lists design principles, e.g.:

• the principle of least surprise
• "Easy things should be easy, hard things should be possible" - Larry Wall
• speed is important
• as much as possible, make restarting the server unnecessary
• degrade gracefully without breaking