updated with some architecture notes