trying to work out the ending here...[screams intensify]
added more design documentation