Add architecture docs

README.md

@@ -7,13 +7,15 @@
 
 The Add-ons Validator, JS edition.
 
-## Required node version
+## Development
+
+### Required node version
 
 Node v0.12.x or greater is required. Using nvm is probably the easiest way
 to manage multiple node versions side by side. See
 [nvm on github](https://github.com/creationix/nvm) for more details.
 
-## Install dependencies
+### Install dependencies
 
 Install dependencies with [npm](http://nodejs.org/):
 
@@ -23,7 +25,7 @@ npm install
 
 Dependencies are automatically kept up-to-date using [greenkeeper](http://greenkeeper.io/).
 
-## Testing
+### Testing
 
 Tests use `grunt` but don't require global `grunt`. Just run:
 
@@ -31,7 +33,7 @@ Tests use `grunt` but don't require global `grunt`. Just run:
 npm test
 ```
 
-## Logging
+### Logging
 
 We use [bunyan](https://github.com/trentm/node-bunyan) for logging:
 
@@ -41,3 +43,46 @@ We use [bunyan](https://github.com/trentm/node-bunyan) for logging:
 * Bunyan by default logs JSON. If you want the json to be pretty printed
   pipe anything that logs into `bunyan` e.g. `LOG_LEVEL=debug grunt test
   | node_modules/bunyan/bin/bunyan`
+
+
+## Architecture
+
+In a nutshell the way the validator works is to take an add-on
+package, extract the metadata from the xpi (zip) format and then
+process the files it finds through various content scanners.
+
+### Scanners
+
+Generally each file-type has a scanner. For example we have a CSS and a
+JavaScript scanner amongst others. Each scanner looks at relevant
+files and passes each file through a parser which then hands off to
+various rules that look for specific things.
+
+### Rules
+
+Rules are exported via a single function in a single file. A rule can
+have private functions it uses internally, but rule code should not depend
+on another rule file and only one function should be exported per file.
+
+Each rule function is passed data from the scanner in order to carry
+out the specific checks for that rule it returns a list of objects which
+are then made into message objects and are passed to the Collector.
+
+### Collector
+
+The Collector is simply an in-memory store for all the validation
+message objects that are "collected" as the contents of the package are
+processed.
+
+### Messages
+
+Each message has a code which is also its key. It has a message which
+is a short outline of what the message represents, and a description
+which is more detail into why that message was logged. The type of
+the message is set as messages are added so that if necessary the
+same message could be an error *or* a warning for example.
+
+### Output
+
+Lastly when the processing has been completed the validator will output
+the collected data as text or JSON.