From 5f83584e4832c7597df61b74f9074e06d3b5aef5 Mon Sep 17 00:00:00 2001
From: David Erwin <davidjerwin@gmail.com>
Date: Fri, 26 May 2017 11:37:33 -0400
Subject: [PATCH] Update tooling and client architecture docs

---
 docs/_data/sidebars/talk_sidebar.yml |  13 ++-
 docs/client-architecture.md          | 128 +++++++++++++++++++++++++++
 docs/tools.md                        |   2 +-
 3 files changed, 139 insertions(+), 4 deletions(-)
 create mode 100644 docs/client-architecture.md

diff --git a/docs/_data/sidebars/talk_sidebar.yml b/docs/_data/sidebars/talk_sidebar.yml
index 6429aaf93..fcb3cb324 100644
--- a/docs/_data/sidebars/talk_sidebar.yml
+++ b/docs/_data/sidebars/talk_sidebar.yml
@@ -14,9 +14,6 @@ entries:
     - title: FAQ
       url: /faq.html
       output: web
-    - title: Tools
-      url: /tools.html
-      output: web
 
   - title: Installation
     output: web
@@ -46,3 +43,13 @@ entries:
     - title: Experimental
       url: /plugins-experimental.html
       output: web
+
+  - title: Development
+    output: web
+    folderitems:
+    - title: Client Architecture
+      url: /client-architecture.html
+      output: web
+    - title: Tools
+      url: /tools.html
+      output: web
diff --git a/docs/client-architecture.md b/docs/client-architecture.md
new file mode 100644
index 000000000..46f593758
--- /dev/null
+++ b/docs/client-architecture.md
@@ -0,0 +1,128 @@
+---
+title: Core Client Architecture
+keywords: homepage
+sidebar: talk_sidebar
+permalink: client-architecture.html
+summary:
+---
+
+## The Stack
+ - [React](#react)
+ - [Redux](#redux)
+ - [ImmutableJS](#immutablejs)
+
+
+## The Architecture
+Our frontend lives within [talk/client](https://github.com/coralproject/talk/tree/153193959cb4dfa5d8feaabb49811325f836ee68/client) folder. Every folder contains a plugin. In [coral-framework](https://github.com/coralproject/talk/tree/153193959cb4dfa5d8feaabb49811325f836ee68/client/coral-framework) you will find the core architecture of Talk.
+Here is where our Redux Application, translations, components, and helpers live.
+
+
+## Presentational and Container Components
+We use a common simple pattern called
+__Presentational and Container Components__
+
+It basically consist in having two types of components:
+  - Presentational
+  - Containers
+
+### Presentational Components
+- __How our UI looks like__
+- Are stateless components
+- Render props
+- Allow containment of children via `this.props.children`
+- They have DOM Markup
+
+### Container Components
+* __How things work__
+* They don’t have markup nor styles
+* They provide data and behaviour to Presentational or Container Components
+* They connect via `react-redux`’s `connect()` to the state.
+* They `mapStateToProps` the state to the Presentational Container.
+* They `mapDispatchToProps` to send actions to the Presentational Container.
+* Name Convention `<Name>Container.js`
+
+How a container looks like:
+```js
+/*
+* mapStateToProps
+* We map the part of the state that we want to use
+*/
+
+const mapStateToProps = state => ({
+  auth: state.auth.toJS()
+});
+
+/*
+* mapDispatchToProps
+* We map the actions that we want to use
+*/
+
+const mapDispatchToProps = dispatch => ({
+  checkLogin: () => dispatch(checkLogin())
+});
+
+
+/*
+* connect
+* We wrap our container in a connect() function
+*/
+
+export default connect(
+  mapStateToProps,
+  mapDispatchToProps
+)(SignInContainer);
+````
+
+How our SignInContainer works: [talk/SignInContainer.js · GitHub](https://github.com/coralproject/talk/blob/153193959cb4dfa5d8feaabb49811325f836ee68/client/coral-sign-in/containers/SignInContainer.js)
+
+Within our plugins we create two folders `containers` and `components` so we can differentiate them:
+```
+coral-sign-in/
+├── containers/
+│   └── SignInContainer.js
+└── components/
+    ├── SignInContent.js
+    └── SignUpContent.js
+```
+
+More about this architecture:
+
+[Container Components – Learn React with chantastic – Medium](https://medium.com/@learnreact/container-components-c0e67432e005#.w8mzgndcg)
+
+
+[Presentational and Container Components – Dan Abramov – Medium](https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0#.ai4ih55v3)
+
+
+## GraphQL
+We use [Apollo](http://www.apollodata.com/) to handle graph requests and handle state.
+
+## Redux
+We use [Redux](http://redux.js.org/) to handle the auth state.
+
+
+## ImmutableJS
+We use Immutable JS to maintain our state immutable.
+We found some really good tradeoffs while building Talk.
+
+[How to use ImmutableJS and how we use it with Talk](https://facebook.github.io/immutable-js/docs/#/)
+
+
+## Test
+[How we do testing at Coral with Talk](/tools.html)
+
+
+## Lint
+For linting in Talk we use `eslint:recommended`
+
+You can find more info about the rules and best practices here:
+http://eslint.org/docs/rules/#best-practices
+
+## Lint the code
+```js
+yarn lint
+```
+
+
+## The Future of the Frontend
+- Preact
+- Reselect
diff --git a/docs/tools.md b/docs/tools.md
index d32d16dfb..51036d96e 100644
--- a/docs/tools.md
+++ b/docs/tools.md
@@ -2,7 +2,7 @@
 title: Tooling
 keywords: homepage
 sidebar: talk_sidebar
-permalink: plugins-client.html
+permalink: tools.html
 summary:
 ---