updated docs

docs/build.md

@@ -0,0 +1,22 @@
+Send has two build configurations, development and production. Both can be run via `npm` scripts, `npm start` for development and `npm run build` for production. Webpack is our only build tool and all configuration lives in [webpack.config.js](../webpack.config.js).
+
+# Development
+
+`npm start` launches a `webpack-dev-server` on port 8080 that compiles the assets and watches files for changes. It also serves the backend API and frontend unit tests via the `server/dev.js` entrypoint. The frontend tests can be run in the browser by navigating to http://localhost:8080/test and will rerun automatically as the watched files are saved with changes.
+
+# Production
+
+`npm run build` compiles the assets and writes the files to the `dist/` directory. `npm run prod` launches an Express server on port 1443 that serves the backend API and frontend static assets from `dist/` via the `server/prod.js` entrypoint.
+
+# Notable differences
+
+- Development compiles assets in memory, so no `dist/` directory is generated
+- Development does not enable CSP headers
+- Development frontend source is instrumented for code coverage
+- Only development includes sourcemaps
+- Only development exposes the `/test` route
+- Production sets Cache-Control immutable headers on the hashed static assets
+
+# Custom Loaders
+
+The `build/` directory contains custom webpack loaders specific to Send. See [build/readme.md](../build/readme.md) for details on each loader.

docs/encryption.md

@@ -0,0 +1,46 @@
+# File Encryption
+
+Send use 128-bit AES-GCM encryption via the [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) to encrypt files in the browser before uploading them to the server. The code is in [app/keychain.js](../app/keychain.js).
+
+## Steps
+
+### Uploading
+
+1. A new secret key is generated with `crypto.getRandomValues`
+2. The secret key is used to derive 3 more keys via HKDF SHA-256
+    - an encryption key for the file (AES-GCM)
+    - an encryption key for the file metadata (AES-GCM)
+    - a signing key for request authentication (HMAC SHA-256)
+3. The file and metadata are encrypted with their corresponding keys
+4. The encrypted data and signing key are uploaded to the server
+5. An owner token and the share url are returned by the server and stored in local storage
+6. The secret key is appended to the share url as a [#fragment](https://en.wikipedia.org/wiki/Fragment_identifier) and presented to the UI
+
+### Downloading
+
+1. The browser loads the share url page, which includes an authentication nonce
+2. The browser imports the secret key from the url fragment
+3. The same 3 keys as above are derived
+4. The browser signs the nonce with it's signing key and requests the metadata
+5. The encrypted metadata is decrypted and presented on the page
+6. The browser makes another authenticated request to download the encrypted file
+7. The browser downloads and decrypts the file
+8. The file prompts the save dialog or automatically saves depending on the browser settings
+
+### Passwords
+
+A password may optionally be set to authenticate the download request. When a password is set the following steps occur.
+
+#### Sender
+
+1. The original signing key derived from the secret key is discarded
+2. A new signing key is generated via PBKDF2 from the user entered password and the full share url (including secret key fragment)
+3. The new key is sent to the server, authenticated by the owner token
+4. The server stores the new key and marks the record as needing a password
+
+#### Downloader
+
+1. The browser loads the share url page, which includes an authentication nonce and indicator that the file requires a password
+2. The user is prompted for the password and the signing key is derived
+3. The browser requests the metadata using the key to sign the nonce
+4. If the password was correct the metadata is returned, otherwise a 401

docs/experiments.md

@@ -0,0 +1,84 @@
+# A/B experiment testing
+
+We're using Google Analytics Experiments for A/B testing.
+
+## Creating an experiment
+
+Navigate to the Behavior > Experiments section of Google Analytics and click the "Create experiment" button.
+
+The "Objective for this experiment" is the most complicated part. See the "Promo click (Goal ID 4 / Goal Set 1)" for an example.
+
+In step 2 add as many variants as you plan to test. The urls are not important since we aren't using their js library to choose the variants. The name will show up in the report so choose good ones. "Original page" becomes variant 0 and each variant increments by one. We'll use the numbers in our `app/experiments.js` code.
+
+Step 3 contains some script that we'll ignore. The important thing here is the **Experiment ID**. This is the value we need to name our experiment in `app/experiments.js`. Save the changes so far and wait until the code containing the experiment has been deployed to production **before** starting the experiment.
+
+## Experiment code
+
+Code for experiments live in [app/experiments.js](../app/experiments.js). There's an `experiments` object that contains the logic for deciding whether an experiment should run, which variant to use, and what to do. Each object needs to have these functions:
+
+### `eligible` function
+
+This function returns a boolean of whether this experiment should be active for this session. Any data available to the page can be used determine the result.
+
+### `variant` function
+
+This function returns which experimental group this session is placed in. The variant values need to match the values set up in Google Analytics, usually 0 thru N-1. This value is usually picked at random based on what percentage of each variant is desired.
+
+### `run` function
+
+This function gets the `variant` value chosen by the variant function and the `state` and `emitter` objects from the app. This function can do anything needed to change the app based on the experiment. A common pattern is to set or change a value on `state` that will be picked up by other parts of the app, like ui templates, to change how it looks or behaves.
+
+### Example
+
+Here's a full example of the experiment object:
+
+```js
+const experiments = {
+  S9wqVl2SQ4ab2yZtqDI3Dw: { // The Experiment ID from Google Analytics
+    id: 'S9wqVl2SQ4ab2yZtqDI3Dw',
+    run: function(variant, state, emitter) {
+      switch (variant) {
+        case 1:
+          state.promo = 'blue';
+          break;
+        case 2:
+          state.promo = 'pink';
+          break;
+        default:
+          state.promo = 'grey';
+      }
+      emitter.emit('render');
+    },
+    eligible: function() {
+      return (
+        !/firefox|fxios/i.test(navigator.userAgent) &&
+        document.querySelector('html').lang === 'en-US'
+      );
+    },
+    variant: function(state) {
+      const n = this.luckyNumber(state);
+      if (n < 0.33) {
+        return 0;
+      }
+      return n < 0.66 ? 1 : 2;
+    },
+    luckyNumber: function(state) {
+      return luckyNumber(
+        `${this.id}:${state.storage.get('testpilot_ga__cid')}`
+      );
+    }
+  }
+};
+```
+
+## Reporting results
+
+All metrics pings will include the variant and experiment id, but it's usually important to trigger a specific event to be counted as the experiment goal (the "Objective for this experiment" part from setup). Use an 'experiment' event to do this. For example:
+
+```js
+emit('experiment', { cd3: 'promo' });
+```
+
+where `emit` is the app emitter function passed to the [route handler](https://github.com/choojs/choo#approuteroutename-handlerstate-emit)
+
+The second argument can be an object with any additional parameters. It  usually includes a custom dimension that we chose to filter on while creating the experiment in Google Analytics.

docs/localization.md

@@ -0,0 +1,29 @@
+# Localization
+
+Send is localized in over 50 languages. We use the [fluent](http://projectfluent.org/) library and store our translations in [FTL](http://projectfluent.org/fluent/guide/) files in `public/locales/`. `en-US` is our base language, and other languages are managed by [pontoon](https://pontoon.mozilla.org/projects/test-pilot-firefox-send/).
+
+## Process
+
+Strings are added or removed from [public/locales/en-US/send.ftl] as needed. Strings **MUST NOT** be *changed* after they've been commited and pushed to master. Changing a string requires creating a new ID with a new name (preferably descriptive instead of incremented) and deletion of the obsolete ID. It's often useful to add a comment above the string with info about how and where the string is used.
+
+Once new strings are commited to master they are available for translators in Pontoon. All languages other than `en-US` should be edited via Pontoon. Translations get automatically commited to the github master branch.
+
+### Activation
+
+The development environment includes all locales in `public/locales` via the `L10N_DEV` environment variable. Production uses `package.json` as the list of locales to use. Once a locale has enough string coverage it should be added to `package.json`.
+
+## Code
+
+In `app/` we use the `state.translate()` function to translate strings to the best matching language base on the user's `Accept-Language` header. It's a wrapper around fluent's [MessageContext.format](http://projectfluent.org/fluent.js/fluent/MessageContext.html). It works the same for both server and client side rendering.
+
+### Examples
+
+```js
+// simple string
+const finishedString = state.translate('downloadFinish')
+// with parameters
+const progressString = state.translate('downloadingPageProgress', {
+  filename: state.fileInfo.name,
+  size: bytes(state.fileInfo.size)
+})
+```