updating documentation: architecture notes