add a broad overview of the codebase to make life easier for reviewers.

1 files changed, 53 insertions, 0 deletions

diff --git a/README b/README
index b31db05..6bd0edb 100644
--- a/README
+++ b/README
@@ -68,3 +68,56 @@ CUSTOM MENUITEMS
    - x-canonical-time-format  s strftime format string
 
 
+
+CODE
+====
+
+Model
+
+  The app's model is represented by the "State" class, and "Menu" objects
+  are the corresponding views. "State" is a simple container for various
+  properties, and menus connect to those properties' changed() signals to
+  know when the view needs to be refreshed.
+
+  As one can see in main.c, the app's very simple flow is to instantiate
+  a state and its properties, build menus that correspond to the state,
+  and export the menus on DBus.
+
+  Because State is a simple aggregate of its components (such as a "Clock"
+  or "Planner" object to get the current time and upcoming appointments,
+  respectively), one can plug in live components for production and mock
+  components for unit tests. The entire backend can be mix-and-matched by
+  adding the desired test-or-production components.
+
+  Start with:
+  include/datetime/state.h
+  include/datetime/clock.h
+  include/datetime/locations.h
+  include/datetime/planner.h
+  include/datetime/settings.h
+  include/datetime/timezones.h
+
+  Implementations:
+  include/datetime/settings-live.h
+  include/datetime/locations-settings.h
+  include/datetime/planner-eds.h
+  include/datetime/timezones-live.h
+
+View
+
+  Menu is a mostly-opaque class to wrap GMenu code. Its subclasses contain
+  the per-profile logic of which sections/menuitems to show and which to hide.
+  Menus are instantiated via the MenuFactory, which takes a state and profile.
+
+  Actions is a mostly-opaque class to wrap our GActionGroup. Its subclasses
+  contain the code that actually executed when an action is triggered (ie,
+  LiveActions for production and MockActions for testing).
+
+  Exporter exports the Actions and Menus onto the DBus, and also emits a
+  signal if/when the busname is lost so indicator-datetime-service knows
+  when to exit.
+
+  include/datetime/menu.h
+  include/datetime/actions.h
+  include/datetime/exporter.h
+