WIP – add README to lib/ to explain how things work

README.md

@@ -13,7 +13,7 @@ Hoodie lets you build apps [without _thinking_ about the backend](http://nobacke
 and makes sure that they work great [independent from connectivity](http://offlinefirst.org/).
 
 This is Hoodie’s main repository. It starts a server and serves the client API.
-Read more about [Hoodie’s core modules](#architecture).
+Read more about [how things work](lib).
 
 A good place to start is our [Tracker App](https://github.com/hoodiehq/hoodie-app-tracker).
 You can play around with Hoodie’s APIs in the browser console and see how it
@@ -48,7 +48,7 @@ port          | 8080                               | Port-number to run the Hood
 bindAddress   | 127.0.0.1                          | Address that Hoodie binds to
 public        | path.join(options.path, 'public')  | path to static assets
 inMemory      | false                              | Whether to start the PouchDB Server in memory
-dbUrl         | –                                  | If provided uses external CouchDB. Has to contain credentials.
+dbUrl         | –                                  | If provided, uses external CouchDB. URL has to contain credentials.
 data          | path.join(options.path, '.hoodie') | Data path
 
 Hoodie is using the [rc](https://www.npmjs.com/package/rc) module to retrieve
@@ -68,29 +68,6 @@ The `hoodie` test suite is run with `npm test`.
 
 You can [read more about testing Hoodie](test)
 
-## Architecture
-
-Hoodie is server built on top of [hapi](http://hapijs.com) with frontend APIs
-for account and store related tasks.
-
-It consists of three main components
-
-1. [**account**](https://github.com/hoodiehq/hoodie-account)  
-   Hoodie’s account module. It exposes [JSON API](http://jsonapi.org/) routes,
-   a corresponding server API at `server.plugins.account.api`,
-   a client API and a generic account UI.
-
-1. [**store**](https://github.com/hoodiehq/hoodie-store)  
-   Hoodie’s store module. It exposes [CouchDB’s Document API](https://wiki.apache.org/couchdb/HTTP_Document_API),
-   a corresponding client and a generic store UI.
-
-1. [**client**](https://github.com/hoodiehq/hoodie-client)  
-   Hoodie’s front-end client for the browser. It integrates the following client modules:
-   1. [account-client](https://github.com/hoodiehq/hoodie-account-client)
-   2. [store-client](https://github.com/hoodiehq/hoodie-store-client)
-   3. [log-client](https://github.com/hoodiehq/hoodie-log-client)
-   4. [connection-status](https://github.com/hoodiehq/hoodie-connection-status)
-
 ## License
 
 [Apache 2.0](LICENSE)

bin/start.js

@@ -117,6 +117,5 @@ getHoodieServer(options, function (error, server, env_config) {
 
   server.start(function () {
     console.log((useEmoji ? emoji.get('dog') + '  ' : '') + 'Your Hoodie app has started on ' + url.format(env_config.app))
-    log.verbose('app', 'Database running at ' + url.format(_.omit(env_config.db, 'auth')))
   })
 })

lib/README.md

@@ -0,0 +1,52 @@
+# How things work
+
+After [installing hoodie](../#setup), `npm start` will run [bin/start.js](../bin/start.js)
+which reads out [configuration](../#usage) from all the different places using
+the [rc](https://www.npmjs.com/package/rc) package, then passes it as options to
+`getHoodieServer`, the main function return by this package, defined in
+[lib/index.js](index.js).
+
+In `getHoodieServer` the passed options are amended with defaults and parsed
+into configuration for the hapi server and the core modules (see [architecture](#architecture)).
+For example, [hoodie-account-server](https://github.com/hoodiehq/hoodie-account-server)
+and [hoodie-store-server](https://github.com/hoodiehq/hoodie-store-server) require
+different kind of options, which are extracted from options and stored in `config.account`
+and `config.store` respectively.
+
+The biggest difference is wether data is stored using an external CouchDB (`options.dbUrl` is set)
+or using PouchDB (`options.dbUrl` is not set, this is the default behavior).
+For example, the server secret is stored & retrieved in different ways based on
+that, you can see [lib/config/db/couchdb.js](config/db/couchdb.js) and
+[lib/config/db/pouchd.js](config/db/pouchd.js) to see how the differences are handled.
+
+Once all configuration is taken care of, the internal plugins are initialised
+(see [lib/plugins/index.js](plugins/index.js)). We define simple hapi plugins
+for [logging](plugins/log.js) and for [serving the app’s public assets and the hoodie client](plugins/public.js).
+We also load the core modules and register them with the hapi server.
+
+Once everything is setup, `getHoodieServer` runs the callback and passes the
+hapi `server` instance. The server is then started at the end of [bin/start.js](../bin/start.js)
+and the URL where hoodie is running is logged to the terminal.
+
+## Architecture
+
+Hoodie is server built on top of [hapi](http://hapijs.com) with frontend APIs
+for account and store related tasks.
+
+It consists of three main components
+
+1. [**account**](https://github.com/hoodiehq/hoodie-account)  
+   Hoodie’s account core module. It exposes [JSON API](http://jsonapi.org/) routes,
+   a corresponding server API at `server.plugins.account.api`,
+   a client API and a generic account UI.
+
+2. [**store**](https://github.com/hoodiehq/hoodie-store)  
+   Hoodie’s store core module. It exposes [CouchDB’s Document API](https://wiki.apache.org/couchdb/HTTP_Document_API),
+   a corresponding client and a generic store UI.
+
+3. [**client**](https://github.com/hoodiehq/hoodie-client)  
+   Hoodie’s front-end client for the browser. It integrates the following client modules:
+   1. [account](https://github.com/hoodiehq/hoodie-account-client)
+   2. [store](https://github.com/hoodiehq/hoodie-store-client)
+   3. [log](https://github.com/hoodiehq/hoodie-log)
+   4. [connection-status](https://github.com/hoodiehq/hoodie-connection-status)