update design doc

CONTRIBUTING.md

@@ -15,8 +15,10 @@ Dotdrop's code base is located in the [dotdrop directory](/dotdrop).
 Here's an overview of the different files and their role:
 
 * **action.py**: represent the actions and transformations
+* **cfg_yaml.py**: the lower level config parser
+* **cfg_aggregator.py**: the higher level config parser
 * **comparator.py**: the class handling the comparison for `compare`
-* **config.py**: the config file (*config.yaml*) parser
+* **dictparser.py**: abstract class for parsing dictionaries
 * **dotdrop.py**: the entry point and where the different cli commands are executed
 * **dotfile.py**: represent a dotfile
 * **installer.py**: the class handling the installation of dotfile for `install`
@@ -24,10 +26,54 @@ Here's an overview of the different files and their role:
 * **linktypes.py**: enum for the three types of linking (none, symlink, children)
 * **logger.py**: the custom logger
 * **options.py**: the class embedding all the different options across dotdrop
+* **profile.py**: represent a profile
+* **settings.py**: represent the config settings
 * **templategen.py**: the jinja2 templating class
 * **updater.py**: the class handling the update of dotfiles for `update`
 * **utils.py**: some useful methods
 
+## Config parsing
+
+The configuration file (yaml) is parsed in two layers:
+
+  * the lower layer in `cfg_yaml.py`
+  * the higher layer in `cfg_aggregator.py`
+
+Only the higher layer is accessible to other classes of dotdrop.
+
+The lower layer part is only taking care of basic types and
+does the following:
+  * normalize all config entries
+    * resolve paths (dotfiles src, dotpath, etc)
+    * refactor actions to a common format
+    * etc
+  * import any data from external files (configs, variables, etc)
+  * apply variable substitutions
+  * complete any data if needed (add the "profile" variable, etc)
+  * execute intrepreted variables through the shell
+  * write new entries (dotfile, profile) into the dictionary and save it to a file
+  * fix any deprecated entries (link_by_default, etc)
+  * clear empty entries
+
+In the end it makes sure the dictionary (or parts of it) accessed
+by the higher layer is clean and normalize.
+
+The higher layer will transform the dictionary parsed by the lower layer
+into objects (profiles, dotfiles, actions, etc).
+The higher layer has no notion of inclusion (profile included for example) or
+file importing (import actions, etc) or even interpreted variables
+(it only sees variables that have already been interpreted).
+
+It does the following:
+  * transform dictionaries into objects
+  * patch list of keys with its corresponding object (for example dotfile's actions)
+  * provide getters for every other classes of dotdrop needing to access elements
+
+Note that any change to the yaml dictionary (adding a new profile or a new dotfile for
+example) won't be *seen* by the higher layer until the config is reloaded. Consider the
+`dirty` flag as a sign the file needs to be written and its representation in higher
+levels in not accurate anymore.
+
 # Testing
 
 Dotdrop is tested with the use of the [tests.sh](/tests.sh) script.