structure

docs/en/data-flow.md

@@ -87,4 +87,6 @@ Here you will notice the component itself is extremely simple: it simply display
 
 You will also notice the data flow is unidirectional, as it should be in Flux:
 
-![data-flow](vuex.png)
+<p align="center">
+  <img width="600px" src="https://raw.githubusercontent.com/vuejs/vuex/master/docs/en/vuex.png">
+</p>

docs/en/state.md

@@ -25,7 +25,7 @@ export default {
 }
 ```
 
-In order to ensure reactive updates, you should **always reference state via `vuex.state.xxx` inside your computed properties**. Do not cache the reference to a piece of state outside computed properties.
+There's no need to worry about setting up and tearing down listeners, or "connecting" the component to a store. The only thing to remember is that you should **always reference state via `vuex.state.xxx` inside your computed properties**. Do not cache the reference to a piece of state outside computed properties.
 
 > Flux reference: this can be roughly compared to [`mapStateToProps`](https://github.com/rackt/react-redux/blob/master/docs/api.md#connectmapstatetoprops-mapdispatchtoprops-mergeprops-options) in Redux and [getters](https://optimizely.github.io/nuclear-js/docs/04-getters.html) in NuclearJS.
 
@@ -47,4 +47,6 @@ Because the `data` function does not track any reactive dependencies, we are onl
 
 Using read-only computed properties has another benefit in that it helps emphasizing the rule that **components should never directly mutate Vuex state**. Because we want every state mutation to be explicit and trackable, all vuex state mutations must be conducted inside vuex mutation handlers.
 
-With this rule enforced, our Vue components now hold a lot less responsibility: they connect to Vuex state via read-only computed properties, and the only way for them to affect Vuex state is by calling **actions**, which in turn trigger **mutations**. They can still possess and operate on their local state if necessary, but we no longer put any data-fetching or global-state-mutating logic inside individual components.
+To help enforce this rule, when in [Debug Mode](debug.md), if Vuex state is mutated outside of mutation handlers, Vuex will throw an error.
+
+With this rule in place, our Vue components now hold a lot less responsibility: they connect to Vuex state via read-only computed properties, and the only way for them to affect Vuex state is by calling **actions**, which in turn trigger **mutations**. They can still possess and operate on their local state if necessary, but we no longer put any data-fetching or global-state-mutating logic inside individual components.

docs/en/structure.md

@@ -0,0 +1,54 @@
+# Application Structure
+
+Vuex doesn't really restrict how you structure your code. Rather, it enforces a set of opinions:
+
+1. Application state lives in a single object.
+2. Only mutation handlers can mutate the state.
+3. Mutations must be synchronous and as simple as possible.
+4. All asynchronous logic such as data fetching should be performed in actions.
+
+The nice thing about Vuex actions and mutations is that **they are just functions with no external dependencies**. As long as you follow these rules, it's up to you how to structure your project. The simplest Vuex instance can even be declared [in a single file](https://github.com/vuejs/vuex/blob/master/examples/counter/vuex.js)! However, this is unlikely to suffice for any serious project, so here are some recommended structures depending on the scale of your app.
+
+### Simple Project
+
+For a simple project, we can simply separate **actions** and **mutations** into respective files:
+
+``` bash
+.
+├── index.html
+├── main.js
+├── components
+│   ├── App.vue
+│   └── ...
+└── vuex
+    ├── index.js     # exports the vuex instance
+    ├── actions.js   # exports all actions
+    └── mutations.js # exports all mutations
+```
+
+For an actual example, check out the [TodoMVC example](https://github.com/vuejs/vuex/tree/master/examples/todomvc).
+
+### Medium to Large Project
+
+For any non-trivial app, we probably want to further split Vuex-related code into multiple "modules" (roughly comparable to "stores" in vanilla Flux), each dealing with a specific domain of our app. Each module would be managing a sub-tree of the state, exporting the initial state for that sub-tree and all mutations that operate on that sub-tree:
+
+``` bash
+├── index.html
+├── main.js
+├── api
+│   └── ... # abstractions for making API requests
+├── components
+│   ├── App.vue
+│   └── ...
+└── vuex
+    ├── actions.js # exports all actions
+    ├── index.js
+    ├── modules
+    │   ├── cart.js       # state and mutations for cart
+    │   └── products.js   # state and mutations for products
+    └── mutation-types.js # constants
+```
+
+Note that we do not put actions into modules, because a single action may dispatch mutations that affect multiple modules. Also, since actions are only concerned with how to dispatch mutations, it's a good idea to decouple them from the state shape and the implementation details of mutations. If the actions file gets too large, we can turn it into a folder and split out the implementations of long async actions into individual files as well.
+
+For an actual example, check out the [Shopping Cart Example](https://github.com/vuejs/vuex/tree/master/examples/shopping-cart).