Architecture updated

ARCHITECTURE.md

@@ -1,30 +1,44 @@
-# Transloadit JavaScript SDK architecture
+# Uppy File Uploader Architecture
 
-This file might be slightly outdate. Current proposal as of 2015-11-23 is reflected in  [classes.es6](https://github.com/transloadit/uppy/blob/f1aa1072d5159c372624a57d5a8edaad2119efa9/classes.es6)
+*Work in progress, API not stable. Last update: 2015-12-03*
 
+## The Gist
+
+``` javascript
+import Uppy from './src/core';
+import { DragDrop, Tus10 } from './src/plugins';
+
+const uppy = new Uppy({wait: false});
+const files = uppy
+  .use(DragDrop, {selector: '#upload-target'})
+  .use(Tus10, {endpoint: 'http://master.tus.io:8080'})
+  .run();
+```
 
 ## Core
 
-1. The core function `transloadit` accepts `options` and exposes methods like `.use` for adding plugins and `.set` for setting options.
-2. Each plugin is then called by the `use` with given `options` as an argument.
-3. The result is passed from the plugin to `prepareMedia` for some final processing
-4. Then the processed files go into `upload` which uploads everything to Transloadit servers, using `tus`.
+1. Core class `Uppy` accepts global object `options`, and exposes methods like `.use` for adding plugins and `.set` for setting options.
+2. We create a new instance of `Uppy` and call `.use` methods on that, passing the plugins and their options.
+3. Plugins have types: `presetter`, `selecter` and `uploader` (more types could be added in the future). When `use` is called, each plugin’s `run` method is added to an array of corresponding types, `methods`.
+4. Ok, here is the tricky part. Core’s method `run` iterates over plugin types in a waterfall manner — each `runTypes`  runs its `method`s in parallel and returns an array of results (files) to the next plugin type in the waterfall:
+
+![waterfall of parallels](uppy-core-plugins-architecture.jpg)
 
 ## Plugins
 
-1. Plugins should be registered like this:
+1. Plugins are registered like this:
 ```javascript
-  transloadit.use(dragndrop, {
-    selector: '.drop'
-  });
+uppy
+  .use(DragDrop, {selector: '#upload-target'})
+  .use(Tus10, {endpoint: 'http://master.tus.io:8080'})
 ```
 
-`dragndrop` here is function that we pass as an argument.
-*For reference, see [Markdown-It](https://github.com/markdown-it/markdown-it/blob/master/lib/index.js#L459).*
+Internally, plugins extend from a `UppyPlugin` class, see that for details.
+
 
-2. Settings and handlers should be chainable and set like this:
+2. Settings and handlers are chainable, set like this:
 ```javascript
-transloadit
+uppy
   .set({ wait: true })
   .use(transloaditModal, {some: 'config'})
   .use(dragdrop, {target: transloaditModal})
@@ -33,56 +47,24 @@ transloadit
   .on('error', handleError);
 ```
 
-3. In `transloadit-js` everything is a plugin: a `Modal` dialog, `Drag & Drop`, `Instagram`. We borrow general approach from the new Babel and PostCSS — almost barebones by default, each chunk of functionality exists as separate plugin — easier to pick and choose exactly what you need to get a lightweight solution for production, while also easier to develop and avoid merge conflicts.
-
-4. Presets should exist with basic plugins like `Modal` & `Drag & Drop`. This should let people who just want to get it working as quickly as possible get started in seconds:
-    ```javascript
-    transloadit
-      .set({ wait: true })
-      .use(transloaditBasic, {some: 'config'})
-    ```
+3. In `Uppy` everything is a plugin: a `Modal` dialog, `Drag & Drop`, `Instagram`. We borrow general approach from the new Babel and PostCSS — each chunk of functionality exists as separate plugin — easier to pick and choose exactly what you need to get a lightweight solution for production, while also easier to develop and avoid merge conflicts.
 
-    *See [`es2015-preset`](https://babeljs.io/docs/plugins/preset-es2015/) for Babel and [`PreCSS`](https://github.com/jonathantneal/precss#plugins) for PostCSS.*
-
-    or just make it a code sample for easy copy/pasting and future customizations (no need to change the main function call, just add/remove lines to modify behaviour):
-    ```javascript
-    transloadit
-      .set({ wait: true })
-      .use(transloaditModal, {some: 'config'})
-      .use(dragdrop, {target: transloaditModal})
-    ```
+4. There will be a simplified version that includes all the necessary plugins and sane defaults.
+```javascript
+uppyDist
+  .set({ wait: true })
+  .run();
+```
 
 5. Users should be able to set themes and style settings in config: `.use(myTheme)`.
 
 6. Would be cool if you could use whatever drag & drop library you wanted (DropZone) with our wrapper.
 
-## Usage
-
-```javascript
-import transloadit   from 'transloadit';
-import dragndrop     from 'transloadit-dragndrop';
-import instagram     from 'transloadit-instagram';
-import modal         from 'transloadit-modal';
-
-// import Transloadit from 'transloadit-client'
-// import { dropbox, instagram, dragdrop, webcam } from 'transloadit-client/plugins'
-
-// or to import all of them
-// import { * as plugins } from 'transloadit/plugins'
-
-transloadit
-  .set({ wait: true })
-  .use(modal, {some: 'config'})
-  .use(dragdrop, {target: transloaditModal})
-  .use(instagram, {some: 'config'})
-  .on('progress', handleProgress)
-  .on('error', handleError)
-  .on('done', handleResult);
-```
-
 ## References & Inspiration
 
-1. PostCSS
-2. Markdown-It
-3. Babel
-4. Lodash
+1. [PostCSS](https://github.com/postcss/postcss/blob/master/lib/postcss.es6#L19)
+2. [Markdown-It](https://github.com/markdown-it/markdown-it/blob/master/lib/index.js#L459)
+3. [Babel](babeljs.io)
+4. [Lodash](https://lodash.com/)
+5. [Vue.js](http://vuejs.org/guide/plugins.html#Using_a_Plugin)
+6. [Tus.js](https://github.com/tus/tus-js-client)