source: Dev/trunk/README.md @ 523

# QED

This document describes how to develop this code base and the source
code organisation.

## Development, Install and Deploy

Source files are located in `src`. Build and deployment is managed
with _Grunt_, a node based task runner.

First make sure _node_, _npm_, _couchdb_, _heroku_, _formena_, _git_
and _svn_ are installed. To run _grunt_, you'll have to install the
commandline client with `npm install -g grunt-cli`.

QED can run in two modes, _dev_ and _production_. This is controlled
by the environment variable `QED_ENV`. If it is not present, _dev_ is
the assumed mode. In development mode, QED runs agains another
database than in production. So, to run the production server, you
must use `QED_ENV=production grunt run`. Usually when developing you
will use the dev mode and you can omit the QED_ENV variable. The value
of QED_ENV on heroku is already set to production (this can be done
with `heroku config:set QED_ENV=production --app quod-erat` and is
persisent).

From source to a deployable version goes in few steps.
 1. Develop in `src`. You can run `grunt` (or `grunt compile`) to do
    compiling of Coffee and LESS sources and linting of Javascript,
    HTML etc.
 1. Run a server with `grunt run` and test. If client sources are
    changed, you only have to run `grunt compile` and reload the
    browser, for server sources you have to restart it.
 1. You can create a _Dojo_ build with `grunt build`, which will merge
    and compress sources. You can also run `grunt run-build`, which
    will do the build and start it locally for testing.
 1. When you feel your changes are production ready, you can deploy to
    Heroku by running `grunt deploy`. The heroku app must know about
    _quod-erat_ already, so you might have to add it by hand the first
    time.

## Database management

There are _grunt_ tasks to push local database to Cloudant, pull the
oter way or make a backup of the Cloudant database. Which database is
used (dev or production) is again controlled by `QED_ENV`.

In `src/server/bin` are some scripts to check if all database
documents are valid and to upload the latest version of the design
documents. Both the design documents and the database schema are
versioned and QED won't start if the versions don't match.

If an update required changes to (normally) immutable documents, you
can disable the modification check with
`config-db-for-upgrade.js`. It's usually a good idea to write and
update script instead of doing things by hand. Don't forget to restore
the check with `config-db.js`, although a server restart will also do
that for you.

Synchronisation doesn't ignore validation checks, so if you had to
disable the validation to do an upgrade, you also have to disable
validation on the database that you synchronize to. Currently this is
not automated, so you have to run the scripts yourself in a sane
order.

If you want to test locally but with the Cloudant database instead of
localhost, run like `CLOUDANT_URL=<ur> QED_ENV=dev grunt run`. You can
get the url by running `heroku config:get CLOUDANT_URL --app
quod-erat`.

## File organisation

 * _/_ Project root
   * _build/_ Builds go here
     * _development/_ Uncompressed build
     * _production/_ Minified build
   * _docs/_ Project documentation, design documents etc
   * _src/_ Source code
     * _client/_ Dojo web client
     * _server/_ Node/Express server
     * _Procfile_ Heroku process description

```
client/
  The web application for QED.
  routes.js
    Contains the mapping from URLs to pages.
  run.js
    The script for starting the web application (the researchers part).
  stddeps.js
    Contains many dependencies that are used declarativly in the
    templates. Maybe it can be deprecated with Dojo 1.8+'s auto require
    if the build scans templates as well.
  store.js
    Module that returns a fully configured store for the rest of the
    application to use for database access. Handles caching and exposes
    some common serialization functions.
  view.js
    Script that starts the survey part (the respondent part).
  data/
    Apache proxy configuration for transparant access to CouchDB.
  dijit/
    Dijit library (UI components)
  dojo/
    Dojo library (Dojo JS framework)
  dojox/
    DojoX library (contrib library for Dojo and Dijit)
  qed/
    Sourcecode of the QED application
    app/
      Small app framework for handling pages, content, notifications
      and URL history. Our application is build on this.
    css/
      Contains all CSS of the application. Should be distributed better
      with the widgets. The styling is based on LESS, although a copy
      of the CSS is still there.
    model/
      Contains all code dependent on our model, that is, the concrete
      representation of our database documents.
      classes/
        Smart classes on top of the database documents, to help with
        creating and validating objects.
      widgets/
        All widgets that are specific for objects of our model.
    pages/
      The pages in the application. Are wired up to URLs in the routes.js
      file.
    store/
      Dojo Store implementations for Couch and Elastic.
    ui/
      Deprecated. Used to contain all widgets, but these are now split
      between general and model specific widgets. Contains a few widgets
      that were not yet refactored.
    widgets/
      Contains general widgets that are used in our application but do
      not depend on our model.
  util/
    Dojo utils (e.g. build infrastructure)
```